c15t/docs/integrations/matomo-analytics.md

Headless JavaScript consent management platform for cookie banners, privacy preferences, consent storage, and script gating.

---
title: Matomo Analytics
description: Load Matomo with c15t and keep Matomo's queue aligned with measurement consent.
group: integrations
icon: matomo
---
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

**React**

```tsx
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>
  );
}
```

**Next.js**

```tsx
'use client';

import { type ReactNode } from 'react';
import { ConsentManagerProvider } from '@c15t/nextjs';
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: '/api/c15t',
        scripts,
      }}
    >
      {children}
    </ConsentManagerProvider>
  );
}
```

**JavaScript**

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

getOrCreateConsentRuntime({
  mode: 'hosted',
  backendURL: 'https://your-instance.c15t.dev',
  scripts: [
    matomoAnalytics({
      matomoUrl: 'https://analytics.example.com',
      siteId: 1,
    }),
  ],
});
```

## 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.

```ts
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:

```tsx
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:

```ts
import { getOrCreateConsentRuntime } from 'c15t';

const { consentStore } = getOrCreateConsentRuntime();

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

## Types

### MatomoAnalyticsOptions

|Property|Value|
|:--|:--|
|Type Name|\`MatomoAnalyticsOptions\`|
|Source Path|\`./packages/scripts/src/vendors/analytics/matomo-analytics.ts\`|

\*ExtractedTypeTable: Could not extract "MatomoAnalyticsOptions" from "./packages/scripts/src/vendors/analytics/matomo-analytics.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

### Script

|Property|Value|
|:--|:--|
|Type Name|\`Script\`|
|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|

\*ExtractedTypeTable: Could not extract "Script" from "./packages/core/src/libs/script-loader/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*