Include matomo support

cdp1337 · Nov 8, 2023 · f23cb93 · f23cb93
1 parent a9d1b46
commit f23cb93
Show file tree

Hide file tree

Showing 5 changed files with 288 additions and 0 deletions.
diff --git a/docs/extras-overview.md b/docs/extras-overview.md
@@ -31,6 +31,14 @@ Basic lightbox plugin for image and video galleries.
 * [Install Guide](../examples/extras/fslightbox-basic/INSTALL.md)
 
 
+## Matomo Analytics
+
+Provides integration with a privacy-focused analytics platform.
+
+* [Self-Hosted Documentation](https://matomo.org/matomo-on-premise/)
+* [Details](../examples/extras/matomo/README.md)
+* [Install Guide](../examples/extras/matomo/INSTALL.md)
+
 ## PrismJS
 
 Provides syntax highlighting for code blocks.

diff --git a/examples/extras/matomo/INSTALL.md b/examples/extras/matomo/INSTALL.md
@@ -0,0 +1,38 @@
+# Installation Instructions
+
+## 1. JS Library
+
+Include the Matomo init snippet in `index.html` within the `<head>` tag.
+
+Take care to comment out the initial `trackPageView` as this will be handled within 
+`cms:route`.
+
+```html
+<!-- Matomo -->
+<script>
+    var _paq = window._paq = window._paq || [];
+    /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
+    //_paq.push(['trackPageView']); // Handled within the CMS
+    _paq.push(['enableLinkTracking']);
+    (function() {
+        var u="//YOURTRACKING.DOMAIN/";
+        _paq.push(['setTrackerUrl', u+'matomo.php']);
+        _paq.push(['setSiteId', 'YOUR-MATOMO-SITE-ID']);
+        var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
+        g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
+    })();
+</script>
+<!-- End Matomo Code -->
+```
+
+Include the following in `index.html` at the end of the `</body>` tag:
+
+```html
+<!-- Include Matomo extra logic -->
+<script src="/extras/matomo/js/matomo.js"></script>
+```
+
+## 2. Privacy Policy Page
+
+An example privacy policy page has been created within `pages/privacy-no-pii.md`.
+Feel free to copy this to your `pages/` directory and edit as needed.
diff --git a/examples/extras/matomo/README.md b/examples/extras/matomo/README.md
@@ -0,0 +1,23 @@
+# Extra - Matomo Analytics
+
+
+Google Analytics alternative that protects your data and your customers' privacy
+
+Take back control with Matomo – a powerful web analytics platform that gives you 100% data ownership.
+
+
+* Matomo - https://matomo.org/matomo-on-premise/
+* License - GNU General Public License v3.0
+
+Since MarkdownMaster acts as a single page application, 
+some adjustments are needed to properly track page views.
+
+The included script will handle that automatically.
+
+Also includes some nicities when using Matomo to track your site analytics.
+
+Easy opt in/out for users:
+
+```markdown
+[You are either running adblock or the Analytics system cannot be reached.](#){is=matomo-opt-inout}
+```
diff --git a/examples/extras/matomo/js/matomo.js b/examples/extras/matomo/js/matomo.js
@@ -0,0 +1,96 @@
+/**
+ * Called after any page load operation
+ *
+ * Track Matomo/Piwik events on pageload
+ *
+ * @param {CMS} event.detail.cms CMS object for reference if needed
+ * @param {FileCollection[]|null} event.detail.collection Collection of files to view for listing pages
+ * @param {File|null} event.detail.file Single file to view when available
+ * @param {string} event.detail.mode Type of view, usually either "list", "single", or error.
+ * @param {string} event.detail.search Any search query
+ * @param {string} event.detail.tag Any tag selected to view
+ * @param {string} event.detail.type Content type selected
+ */
+document.addEventListener('cms:route', event => {
+    let _paq = window._paq || [];
+
+    if (event.detail.tag !== null) {
+        // Track tag listings as search events
+        // trackSiteSearch(keyword, [category], [resultsCount])
+        _paq.push(['trackSiteSearch', 'tag:' + event.detail.tag, event.detail.type, event.detail.collection.totalResults]);
+    }
+    else if(event.detail.search !== null) {
+        // Track search events
+        // trackSiteSearch(keyword, [category], [resultsCount])
+        _paq.push(['trackSiteSearch', event.detail.search, event.detail.type, event.detail.collection.totalResults]);
+    }
+    else {
+        // Track page views
+        _paq.push(['setCustomUrl', window.location.pathname + window.location.search]);
+        _paq.push(['setDocumentTitle', document.title]);
+        _paq.push(['trackPageView']);
+    }
+});
+
+
+/**
+ * Sent a ping periodically to notify Matomo that the user is still on the page.
+ */
+setInterval(() => {
+    let _paq = window._paq || [];
+    _paq.push(['ping']);
+}, 30000);
+
+
+/**
+ * Create a custom element to handle opting in and out of Matomo tracking.
+ */
+class MatomoOptInOutLink extends HTMLAnchorElement {
+
+    constructor() {
+        // Always call super first in constructor
+        super();
+
+        this.update();
+
+        this.addEventListener('click', event => {
+            let _paq = window._paq || [];
+
+            if( this.dataset['mode'] === 'optin' ) {
+                _paq.push(['forgetUserOptOut']);
+            }
+            else if( this.dataset['mode'] === 'optout' ) {
+                _paq.push(['optUserOut']);
+            }
+            else {
+                alert('Unable to connect to our Analytics software, you are probably running Ad-Block so there is nothing to do.');
+            }
+
+            event.preventDefault();
+            this.update();
+        });
+    }
+
+    update() {
+        let element = this;
+
+        if(Object.hasOwn(window, '_paq')) {
+            _paq.push([function() {
+                if( this.isUserOptedOut() ) {
+                    element.innerText = '❌ You are currently opted out. Click here to opt in.';
+                    element.dataset['mode'] = 'optin';
+                }
+                else {
+                    element.innerText = '✓ You are currently opted in. Click here to opt out.';
+                    element.dataset['mode'] = 'optout';
+                }
+            }]);
+        }
+        else {
+            element.innerText = 'You are either running adblock or the Analytics system cannot be reached.';
+            element.dataset['mode'] = 'unavail';
+        }
+    }
+}
+
+customElements.define('matomo-opt-inout', MatomoOptInOutLink, {extends: 'a'});
diff --git a/examples/extras/matomo/pages/privacy-no-pii.md b/examples/extras/matomo/pages/privacy-no-pii.md
@@ -0,0 +1,123 @@
+---
+title: Privacy Statement
+---
+
+This Policy describes the information we collect from you, 
+how we use that information and our legal basis for doing so. 
+It also covers whether and how that information may be shared 
+and your rights and choices regarding the information you provide to us.
+
+This Privacy Policy applies to the information that we obtain 
+through your use of this website.
+
+
+## Who we are
+
+WRITE-A-SHORT-INTRO-ABOUT-US
+
+We will never sell your personal data to anyone.
+
+## What We Collect and Receive
+
+In order for us to provide you the best possible experience on our website, 
+we need to collect and process certain information. 
+Depending on your use of the Services, that may include:
+
+### Usage data 
+
+When you visit our site, we will store some usage data about your visit. 
+We process this usage data in [Matomo Analytics](https://matomo.org) for statistical purposes, 
+to improve our site and to recognize and stop any misuse.
+
+
+* Anonymized User IP address
+* Generated User ID
+* Date and time of the request
+* Title of the page being viewed (Page Title)
+* URL of the page being viewed (Page URL)
+* URL of the page that was viewed prior to the current page (Referrer URL)
+* Screen resolution being used
+* Time in local user’s timezone
+* Files that were clicked and downloaded (Download)
+* Links to an outside domain that were clicked (Outlink)
+* Pages generation time (the time it takes for webpages to be generated by the webserver and then downloaded by the user: Page speed)
+* Location of the user: country, region, city, approximate latitude and longitude (Geolocation)
+* Main Language of the browser being used (Accept-Language header)
+* User Agent of the browser being used (User-Agent header)
+
+### Cookies 
+
+We use cookies (small data files transferred onto computers or devices by sites) 
+for record-keeping purposes and to enhance functionality on our site. 
+You may deactivate or restrict the transmission of cookies by changing 
+the settings of your web browser. 
+Cookies that are already stored may be deleted at any time.
+
+## Opt-out of website tracking
+
+You can opt out of being tracked by our Matomo Analytics instance below:
+
+[You are either running adblock or the Analytics system cannot be reached.](#){is=matomo-opt-inout}
+
+
+You may choose to prevent this website from aggregating and analyzing the actions you take here. 
+Doing so will protect your privacy, but will also prevent the owner 
+from learning from your actions and creating a better experience for you and other users.
+
+## Your Rights
+
+You have the right to be informed of Personal Data processed with Matomo, 
+a right to rectification/correction, erasure and restriction of processing. 
+You also have the right to ask from us a structured, 
+common and machine-readable format of Personal Data you provided to us.
+
+We can only identify you via your email address,
+(which we do not generally collect unless you email us directly), and we can only adhere 
+to your request and provide information if we have Personal Data 
+about you through you having made contact with us directly and/or you using our site and/or service.
+
+In addition, you have the right to lodge a complaint with the data protection authority in your jurisdiction. 
+
+## Subprocessors
+
+We use a select number of trusted external service providers for certain 
+technical data processing and/or service offerings. 
+These service providers are carefully selected and meet high data protection and security standards. 
+We only share information with them that is required for the services offered 
+and we contractually bind them to keep any information we share with them as confidential 
+and to process Personal Data only according to our instructions.
+
+ORGANIZATION-NAME-HERE uses the following subprocessors to process the data collected by 
+our website:
+
+| Subprocessor          | Data location  | Service         |
+|:----------------------|:---------------|:----------------|
+| HOSTING-PROVIDER-NAME | USA            | Server hosting  |
+| ANY-MSP-OR-TECHS      | USA            | IT Consulting   |
+
+
+## Retention of data
+
+We collect and maintain aggregated, anonymized or pseudonymized information 
+which we may retain indefinitely to protect the safety and security of our Site, 
+improve our Services or comply with legal obligations.
+
+
+## Privacy Policy Changes
+
+We may update this Policy from time to time. 
+
+
+## Reusing this Privacy Policy
+
+Before reading further, please, note that none of our team members are lawyers and 
+do not provide legal or business advice.
+
+You are welcome to reuse and be inspired by this Privacy Policy 
+(published under [license CC BY](https://creativecommons.org/licenses/by/4.0/) ) 
+after making sure it complies with the way your website tracks, uses and discloses users information.
+
+This privacy policy was derived from https://matomo.org/privacy-policy/.
+
+The accuracy, completeness, adequacy of this privacy policy cannot be warranted or guaranteed. 
+Please use it at your own risk.