diff --git a/docs/extras-overview.md b/docs/extras-overview.md index de8b314..c0d607e 100644 --- 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 new file mode 100644 index 0000000..8d466e7 --- /dev/null +++ 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 `` tag. + +Take care to comment out the initial `trackPageView` as this will be handled within +`cms:route`. + +```html + + + +``` + +Include the following in `index.html` at the end of the `` tag: + +```html + + +``` + +## 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 new file mode 100644 index 0000000..e3f2eb9 --- /dev/null +++ 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} +``` \ No newline at end of file diff --git a/examples/extras/matomo/js/matomo.js b/examples/extras/matomo/js/matomo.js new file mode 100644 index 0000000..0d14807 --- /dev/null +++ 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 new file mode 100644 index 0000000..eee9ad1 --- /dev/null +++ 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.