Analytics

Matomo Analytics

Configure Matomo Analytics

Copy the site ID and your Matomo URL from the Matomo tracking code. For Matomo Cloud, pass cloudId, for example 'your-site.matomo.cloud', instead of matomoUrl.

npm install @c15t/integrations@alpha

src/consent-scripts.ts

import { matomoAnalytics } from '@c15t/integrations/matomo-analytics';

export const scripts = [
	matomoAnalytics({ matomoUrl: 'https://analytics.example.com', siteId: 1 }),
];

Register the scripts

Complete your framework quickstart first. Keep its Inth endpoint, policy, styles and consent UI. Remove the vendor's original script, SDK initializer or tag-manager entry, so the vendor loads only through c15t.

The vendor pages put the helper in src/consent-scripts.ts. If your framework quickstart already has a scripts array, such as the one in c15t.config.ts in the Next.js guide, add the helper to that array instead of creating a second file. The scripts export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration point for your framework below. These are edits to that provider, not a second provider.

Add the configuration to scripts in c15t.config.ts, next to next.config.ts:

import { defineConsentConfig } from 'c15t/next';
import { scripts } from './src/consent-scripts';

export default defineConsentConfig({ scripts });

Keep the rest of your config, such as mode and routePrefix, in the same call. ConsentRoot reads the config in the browser, so the layout keeps passing only state. App Router, Pages Router and static export all read the same file. See Next.js scripts and embeds.

Options

Option	Default	Behavior
`matomoUrl`	None	Self-hosted Matomo base URL. The helper loads `<matomoUrl>/matomo.js` and sends hits to `<matomoUrl>/matomo.php`.
`cloudId`	None	Matomo Cloud ID, used when `matomoUrl` is not set. A value ending in `.matomo.cloud` becomes `https://<cloudId>`. Any other value becomes `https://cdn.matomo.cloud/<cloudId>`.
`trackerUrl`	`matomo.php` on the Matomo origin	Tracker endpoint override.
`scriptUrl`	`matomo.js` on the Matomo origin	Loader URL override. Without `matomoUrl` or `cloudId`, set both `trackerUrl` and `scriptUrl`, or the helper logs an error and the script does not load.
`siteId`	`1`	Site ID queued with `setSiteId`.
`trackPageView`	`true`	Queues `trackPageView`. The table below shows when.
`enableLinkTracking`	`false`	Queues `enableLinkTracking`.
`disableCookies`	`false`	Queues `disableCookies`. It does not change when Matomo loads.
`defaultConsent`	None	`'required'` or `'given'` switches to Matomo consent mode.

Loading and revocation

matomoAnalytics uses the measurement category. defaultConsent picks the mode:

`defaultConsent`	Loads	When measurement is allowed	On revocation
Omitted	After measurement is allowed, with `trackPageView` queued	Loads `matomo.js`	Removes the script element and calls no Matomo API
`'required'`	On every page, with `requireConsent` queued	Queues `setConsentGiven` and `trackPageView`	Keeps the script and queues `forgetConsentGiven`
`'given'`	On every page. With measurement allowed as it loads, `setConsentGiven` and `trackPageView` are queued; otherwise `requireConsent`	Queues `setConsentGiven` and `trackPageView`	Keeps the script and queues `forgetConsentGiven`

In both consent modes Matomo holds tracking until setConsentGiven, and the helper only queues that call for a visitor who has measurement consent. The two modes differ for a visitor who already allowed measurement when the page loads: 'given' skips the up-front requireConsent. The helper queues another trackPageView only when measurement changes from denied to allowed, so a change to another category, such as allowing marketing, sends no extra page view. Matomo separates tracking consent from cookie consent.

Verify Matomo Analytics

Without defaultConsent, allowing measurement loads matomo.js, and a matomo.php request carries the page view.

Test in a private window with an opt-in policy. Open DevTools Network, disable the cache and filter by the vendor's domain:

Load the page. No request goes to the vendor before you choose.
Click Reject, then reload. There is still no vendor request.
Open Privacy settings and allow the helper's category. The vendor script loads without a page reload.
Turn the category off again and save. c15t reloads the page, and the new page makes no vendor request.

c15t reloads on revocation because removing a script element does not stop code that already ran. The vendor's listeners, timers and queued events stay alive until the page unloads. If you set reloadOnConsentRevoked: false, stop the vendor yourself. Register a callback-only script whose onConsentChange calls the vendor's opt-out API, as shown in custom integrations, and check the permission before each of your own event calls. The reload does not delete cookies the vendor already set; see clear on revocation for your framework.

The helper sets vendor to its script ID, so once you declare that vendor a visitor can turn it off inside an allowed category. See vendor consent for your framework. The consent verification guide covers navigation, expiry and hosting checks.

With defaultConsent: 'required', Matomo loads before the choice, so test it separately in a private window with an opt-in policy:

Load the page. matomo.js loads, and no matomo.php request follows.
Open Privacy settings and allow measurement. Without a reload, a matomo.php request carries the page view.
Turn measurement off and save. c15t reloads the page, and the new page loads matomo.js without a matomo.php request.

'given' behaves the same in this test. Under an opt-out policy, or after the visitor has allowed measurement, both modes send a matomo.php page view as the page loads. See the consent verification guide for navigation and hosting checks.