Matomo Analytics

Matomo gives you privacy-focused web analytics with self-hosted and cloud deployment options. The matomoAnalytics() helper sets up Matomo's _paq queue, points it at your tracker, and can queue consent-aware commands before the vendor bundle loads.

Integrate with c15t

import { type ReactNode } from 'react';
import { ConsentManagerProvider } from '@c15t/react';
import { matomoAnalytics } from '@c15t/scripts/matomo-analytics';

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

export function ConsentProvider({ children }: { children: ReactNode }) {
  return (
    <ConsentManagerProvider
      options={{
        mode: 'hosted',
        backendURL: 'https://your-instance.c15t.dev',
        scripts,
      }}
    >
      {children}
    </ConsentManagerProvider>
  );
}

How c15t loads it

• Category: measurement (Analytics)
• Loads when: measurement consent is granted by default
• Consent mode option: with defaultConsent, the helper switches to alwaysLoad: true and uses Matomo queue commands to grant/forget consent without unloading the SDK.

Configure the integration

If you want Matomo to manage consent internally, set defaultConsent to one of these values:

• 'required' queues Matomo's requireConsent command so no tracking runs until consent is granted.
• 'given' queues Matomo's setConsentGiven command so tracking starts as granted by default.

When defaultConsent is omitted, c15t uses the standard script-loader flow: Matomo only loads after measurement consent is granted.

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

matomoAnalytics({
  matomoUrl: 'https://analytics.example.com',
  siteId: 1,
  defaultConsent: 'required',
});

Tracking events in your app

Matomo's runtime API is queue-based (window._paq). When the script is not loaded yet, pushing to _paq is still safe as long as the queue exists. The helper creates _paq during setup.

From React:

import { useCallback } from 'react';
import { useConsentManager } from '@c15t/react';

function SignupExample() {
  const { has } = useConsentManager();

  const trackSignup = useCallback(() => {
    if (has('measurement')) {
      window._paq?.push(['trackEvent', 'signup', 'completed']);
    }
  }, [has]);

  return <button onClick={trackSignup}>Sign up</button>;
}

From plain JavaScript:

import { getOrCreateConsentRuntime } from 'c15t';

const { consentStore } = getOrCreateConsentRuntime();

if (consentStore.getState().has('measurement')) {
  window._paq?.push(['trackEvent', 'signup', 'completed']);
}

Types

MatomoAnalyticsOptions

Script