kremalicious / gatsby-plugin-matomo

🥂 Gatsby plugin to add Matomo (formerly Piwik) onto a site.

gatsby-plugin-matomo

🥂 Gatsby plugin to add Matomo (formerly Piwik) onto a site. https://kremalicious.com/gatsby-plugin-matomo/

---

• Features
• Usage
  • Options
• Development
• Changelog
• License

Features

Plugin uses sensible defaults prioritizing user experience, performance & privacy:

• include tracking code in all server-side rendered routes
• track all route views as custom events
• load tracking scripts at end of body tag
• use image tracking fallback for noscript
• don't load anything when visitor has Do Not Track enabled
• don't load anything in non-production environments
• consent mode for privacy
• allow loading tracking script locally
• define paths to be excluded from tracking
• preconnect to configured Matomo host url
• dev mode for local development

Usage

1. First, install the plugin from your project's root:

   cd yourproject/
   npm i gatsby-plugin-matomo

2. Then load the plugin from your gatsby-config.js and set the required variables:

   plugins: [
     {
       resolve: 'gatsby-plugin-matomo',
       options: {
         siteId: 'YOUR_SITE_ID',
         matomoUrl: 'https://YOUR_MATOMO_URL.COM',
         siteUrl: 'https://YOUR_LIVE_SITE_URL.COM'
       }
     }
   ]

3. That's it!

NOTE: By default, this plugin only generates output when run in production mode. To test your tracking code, run gatsby build && gatsby serve, or set dev option to true.

Options

Option	Explanation
siteId	Your Matomo site ID configured in your Matomo installation.
matomoUrl	The url of your Matomo installation.
siteUrl	The url of your site, usually the same as siteMetadata.siteUrl. Only used for generating the url for noscript image tracking fallback.
matomoPhpScript	(optional) The name of your Matomo PHP script. Defaults to matomo.php
matomoJsScript	(optional) The name of your Matomo JS script. Defaults to matomo.js
exclude	(optional) Specify an array of pathnames where tracking code will be excluded. The pathname /offline-plugin-app-shell-fallback/ is excluded by default.
requireConsent	(optional) If true, tracking will be disabled until you call window._paq.push(['setConsentGiven']);.
requireCookieConsent	(optional) If true, no cookies will be stored or used until you call window._paq.push(['setCookieConsentGiven']);.
disableCookies	(optional) If true, no cookie will be used by Matomo.
cookieDomain	(optional) Specify cookie domain.
localScript	(optional) If set, load local matomo.js script from the given path, instead of loading it from your matomoUrl.
trackLoad	(optional) If true, it will track the loading of the matomo library. Defaults to true.
respectDnt	(optional) If false, will load all scripts without respecting user preference to Do Not Track on browsers. Defaults to true.
dev	(optional) Activate dev mode by setting to true. Will load all scripts despite not running in production environment. Ignores your local browser's DNT header too. Outputs some information in console about what it is doing. Useful for local testing but careful: all hits will be send like in production.
enableJSErrorTracking	(optional) Enable basic JavaScript error tracking and reporting in Matomo by setting to true.
additionalTrackers	(optional) An array of additional trackers to track on different Matomo servers. Additional trackers are objects with the keys siteId and trackerUrl containing the full URL to the Matomo PHP script. Defaults to [].

plugins: [
  {
    resolve: 'gatsby-plugin-matomo',
    options: {
      siteId: 'YOUR_SITE_ID',
      matomoUrl: 'https://YOUR_MATOMO_URL.COM',
      siteUrl: 'https://YOUR_LIVE_SITE_URL.COM',
      // All the optional settings
      matomoPhpScript: 'matomo.php',
      matomoJsScript: 'matomo.js',
      exclude: ['/offline-plugin-app-shell-fallback/'],
      requireConsent: false,
      requireCookieConsent: false,
      disableCookies: false,
      cookieDomain: '*.example.org',
      localScript: '/matomo.js',
      dev: false,
      enableJSErrorTracking: true,
      additionalTrackers: [
        {
          siteId: 'ADDITIONAL_SITE_ID',
          trackerUrl: 'https://ADDITIONAL_MATOMO_URL.COM/matomo.php'
        }
      ]
    }
  }
]

Development

npm i
npm start

# create production build
npm run build

# publishing to npm & GitHub releases
# uses https://github.com/webpro/release-it
npm run release
npm run release minor
npm run release major

Changelog

See CHANGELOG.md.

License

The MIT License

Copyright (c) 2020 Matthias Kretschmann

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---

Made with ♥ by Matthias Kretschmann (@kremalicious)

Say thanks with BTC: 35UUssHexVK48jbiSgTxa4QihEoCqrwCTG

Say thanks with ETH: krema.eth

gatsby-plugin-matomo's Issues

Wrong page title when navigating

When navigating, the page title is not correctly set in Matomo, the pathname is sent instead.

gatsby-plugin-matomo/src/gatsby-browser.js

Line 40 in e237c1a

window._paq.push(['setDocumentTitle', pathname])

I'm using React Helmet to set my title, so the question is: is the title already updated when onRouteUpdate is called? If yes, maybe we could get the document title and it should be good for every usecase.

Tracking don't work

Hi,

i installed your plugin and can't get it work.

No matter production or dev-mode.

More Info:

• Matomo V4.5.0 - system check is OK
• I tested in production and local development
• Plugin options:
  siteId: 1,
  matomoUrl: https://xxxxxxx,
  siteUrl: https://www.xxxxxx.xx,
  // localScript: /piwik.js, <<< also tested
  exclude: ['/abc/'],
  requireConsent: false,
  requireCookieConsent: false,
  disableCookies: true,
  respectDnt: false,
  dev: true

I hope you can find time to help.

Best regards

requireConsent mode

Implement user consent mode, see https://developer.matomo.org/guides/tracking-javascript-guide#asking-for-consent

Most minimal implementation would be to add the requireConsent check for all tracking, and allow to activate it via plugin option. Implementing the consent flow would be then left to plugin user.

outbound link tracking

Verify if a component for link tracking (outlines & downloads) is needed. If so, provide component similar to https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-plugin-google-analytics/src/index.js#L4

• https://developer.matomo.org/guides/tracking-javascript-guide/#download-and-outlink-tracking

[email protected]

Javascript load event causing incorrect "Bounce Rate" in Matomo reports

The following code results in an event being tracked for every visit to a website or app:

gatsby-plugin-matomo/src/gatsby-browser.js

Lines 51 to 59 in b99a9a6

	if (trackLoad) {
	_paq.push([
	'trackEvent',
	'javascript',
	'load',
	'duration',
	getDuration()
	])
	}

Unfortunately with the javascript load duration event being tracked in Matomo, the "Actions in visit" are more than one and causes all of these visits to no longer count as "Bounced" even if the visitor didn't interact with the page and left without taking any further action. This can heavily skew the reports in Matomo by not accurately showing the actual bounce rate of visitors to a website or web page.

Matomo 4 includes advanced Page Performance reporting which may make these javascript load duration events no longer necessary: https://matomo.org/faq/how-to/how-do-i-see-page-performance-reports/

Add option to disable JavaScript load duration

Currently, every page load is preceded by a JavaScript event in Matomo. So even if a user visits just one page, two events are recorded. This is a severe issue, as it eliminates all bounces. A bounce has just a single action. Because there is no single action, there are no bounces, which falsifies all statistics.

I see in your docs, that there is an option "trackLoad", but it doesn't seem to be implemented. Maybe you meant to use:

    if (first && trackLoad) {
    }

on line 56 of your gatsby-browser.js file.

In my opinion, the load tracking event should be removed completely.

Channel misattribution?

Hey there.

This is a tall ask, so feel free to close the issue if you're not sure, but I'm hopeful that someone else may have experienced this issue & knows a remedy or understands why there is a discrepancy.

Since migrating our site to Gatsby & using this plugin, we've experienced significant shifts in traffic attribution by channel (despite overall visits remaining flat). We've seen sharp drops in SEO & referral traffic with a corresponding spike in Direct Entry.

Here's a view of SEO vs. Direct Entry:

Here's a view of website referrals vs. Direct Entry:

Does anyone have any ideas on why this plugin results in decreased channel attribution? You can view our configuration for the plugin here.

Thanks in advance!

An in-range update of release-it is breaking the build 🚨

The devDependency release-it was updated from 10.0.7 to 10.0.8.

🚨 View failing branch.

This version is covered by your current version range and after updating it in your project the build failed.

release-it is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.

Status Details

• ❌ Travis CI - Branch: The build errored.

---

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

---

Your Greenkeeper Bot 🌴

File download tracking

Hey there,

I'm using gatsby-plugin-matomo 0.8.3 and it's working perfectly (thanks!) for regular navigation on the page. The page also offers downloads (linked to static files) like this:

<a href="/static/somefile.zip" download="">Download</a>

Unfortunately, the downloads are not shown in the Matomo dashboard. Is there anything else to setup to get this working?

Thanks!

Support custom event tracking

Hey there! I'm curious - does this plugin support custom events?
https://developer.matomo.org/guides/tracking-javascript-guide#manually-trigger-events

I'm envisioning something similar to the function offered by the Gatsby GA plugin:
https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-plugin-google-analytics/src/index.js#L80

I looked through the code & didn't find anything. Is there something I'm missing? If not, consider this an enhancement request 😄

Thanks!

Matomo opt-out in cookieless mode

Hi,
we are using gatsby 5 with this cool matomo plugin in cookieless mode. We got the requirement to offer the opt-out tracking functionality in our privacy statement. (https://matomo.org/faq/general/faq_20000/)
I guess with a workaround using the requireConsent option it is possible to implement it. But my question is: Is there a better way to provide the opt out functionality?

^{Julian Schregle [email protected], Mercedes-Benz Tech Innovation GmbH, legal info/Impressum}

random 404 error with "_pk_ref"

No sure if this is an issue with this plugin, Matomo or Gatsby, but here goes...

We've moved the build into our non-prod environment (AWS S3 with CloudFront) and it works fine happily sending data over to Matomo, until... it decides that all routes are 404.

The issue was only noticed after we implemented this Matomo plugin.

On closer inspection, the only difference between the site working and not working, is when the cookie "_pk_ref.1.546b" gets set.

Removing this cookie fixes the issue.

Thanks

`sendPageView` should be called via `requestAnimationFrame`, when available

Hi,

The following code of this plugin is based on code from gatsby-plugin-google-analytics:

    // Minimum delay for reactHelmet's requestAnimationFrame
    const delay = Math.max(32, 0)
    setTimeout(sendPageView, delay)

In browsers with a refresh rate higher than 60, this can lead to a bug (where the wrong title is sent).

You can find more information in the issue I have created for gatsby-plugin-google-analytics:

gatsby-plugin-google-analytics: sendPageView should be called via requestAnimationFrame, when available #28591

Option to ignore Do-Not-Track and/or to track anonymous data

Hi,

This plugin looks very nice. One thing that I don't like, however, is that it forces plugin users to honor Do-Not-Track (DNT).

I believe website owners have the right to ask visitors for consent to track them, and that such an explicit consent overrules any DNT setting. Currently, this plugin doesn't allow users to do this, however.

Even if you are not willing to give plugin users the choice whether they honor DNT or not – at least there should be an option to collect anonymous data (I'm new to Matomo, but it seems, it is possible to collect anonymous data).

Anonymous data are no personal or personally identifiable information, so they don't fall under any privacy law (as far as I know).

Support JavaScript error tracking

Hey there!

Could you please add support for error tracking?
https://matomo.org/faq/how-to/how-do-i-enable-basic-javascript-error-tracking-and-reporting-in-matomo-browser-console-error-messages/

I think ideally it would just be an additional boolean option, e.g. enableErrorTracking:
https://github.com/kremalicious/gatsby-plugin-matomo#options

If enableErrorTracking is true, we could add _paq.push(['enableJSErrorTracking']);

Support for Gatsby 4

Currently the plugin doesn't officially support Gatsby 4 (even though everything seems to work). I suppose the dependency range just needs to be updated?

warn Plugin gatsby-plugin-matomo is not compatible with your gatsby version 4.0.0 - It requires gatsby@^2.0.0 || ^3.0.0

exclude option could be a regex ?

Hey,

I'm using gatsby-plugin-matomo and it's working perfectly.

do you think it would be possible that the exclude option could be a regex? for example to exclude everything that starts with a path or everything that does not start with a path ?

Thanks!

@kremalicious