Matomo Next

Matomo analytics for Next.js applications

• Basic SPA Matomo setup
• Will track next/router route changes routeChangeComplete event
• ⚠️ Notes for Next.js app router

Usage

Add the init call in your _app.js :

import React, { useEffect } from "react";
import App from "next/app";

import { init } from "@socialgouv/matomo-next";

const MATOMO_URL = process.env.NEXT_PUBLIC_MATOMO_URL;
const MATOMO_SITE_ID = process.env.NEXT_PUBLIC_MATOMO_SITE_ID;

function MyApp({ Component, pageProps }) {
  useEffect(() => {
    init({ url: MATOMO_URL, siteId: MATOMO_SITE_ID });
  }, []);

  return <Component {...pageProps} />;
}

export default MyApp;

Will track routes changes by default.

Exclude tracking some routes :

This wont track /login.php or any url containing ?token=.

init({
  url: MATOMO_URL,
  siteId: MATOMO_SITE_ID,
  excludeUrlsPatterns: [/^\/login.php/, /\?token=.+/],
});

Disable cookies :

To disable cookies (for better GDPR compliance) set the disableCookies flag to true.

init({
  url: MATOMO_URL,
  siteId: MATOMO_SITE_ID,
  disableCookies: true,
});

Track additional events :

import { push } from "@socialgouv/matomo-next";

// track some events
push(["trackEvent", "contact", "click phone"]);

Content-Security-Policy

Nonce

If you use a Content-Security-Policy header with a nonce attribute, you can pass it to the init function to allow the script to be executed.

init({
  url: MATOMO_URL,
  siteId: MATOMO_SITE_ID,
  nonce: "123456789",
})

Trusted Types

As the matomo-next injects a matomo script, if you use strict Trusted Types, you need to allow the script tag to be created by adding our policy name to your trusted types directive.

Content-Security-Policy: require-trusted-types-for 'script'; trusted-types matomo-next;

You can set a custom policy name by passing it to the init function.

init({
  url: MATOMO_URL,
  siteId: MATOMO_SITE_ID,
  trustedPolicyName: "your-custom-policy-name",
})

Extensibility

The function has three optional callback properties that allow for custom behavior to be added:

• onRouteChangeStart(path: string) => void: This callback is triggered when the route is about to change with Next Router event routeChangeStart. It receives the new path as a parameter.

• onRouteChangeComplete: This callback is triggered when the route change is complete with Next Router event routeChangeComplete. It receives the new path as a parameter.

• onInitialization: This callback is triggered when the function is first initialized. It does not receive any parameters. It could be useful to use it if you want to add parameter to Matomo when the page is render the first time.

• onScriptLoadingError: This callback is triggered when the script does not load. It does not receive any parameters. useful to detect ad-blockers.

Tests

init
  ✓ should create a js tag and initialize (7 ms)
  ✓ should NOT create events when url is not provided (9 ms)
push
  ✓ should append data to window._paq (1 ms)
  ✓ should append dimensions data to window._paq (1 ms)
onInitialization
  ✓ should work if the surcharge of the operator (1 ms)
router.routeChangeStart event
  ✓ should setReferrerUrl and setCustomUrl on route change start (1 ms)
  ✓ should setReferrerUrl and setCustomUrl on route change start and handle hashtag (by removing it)
  ✓ should use previousPath as referer on consecutive route change (1 ms)
  ✓ should work if the surcharge of the operator (3 ms)
router.routeChangeComplete event
  ✓ should trackPageView with correct title on route change (3 ms)
  ✓ should use previousPath as referer on consecutive route change (2 ms)
  ✓ should track route as search in /recherche (1 ms)
  ✓ should track route as search in /search (2 ms)
  ✓ should work if the surcharge of the operator (2 ms)
excludeUrlsPatterns
  ✓ should excluded login.php and token variables (2 ms)
  ✓ should exclude initial page tracking (3 ms)
  ✓ should track initial page if not excluded (2 ms)
disableCookies
  ✓ should NOT append disableCookies to window._paq by default (1 ms)
  ✓ should append disableCookies to window._paq (1 ms)