Skip to main content
Ask your AI

Matomo

Web Source code Package Beta

Matomo is an open-source, privacy-focused web analytics platform that works self-hosted or in Matomo Cloud. This destination forwards walkerOS events to Matomo via the _paq command queue with support for page views, custom events, goals, site search, content tracking, and custom dimensions.

Where this fits

Matomo is a web destination in the walkerOS flow:

Installation​

npm install @walkeros/collector @walkeros/web-destination-matomo
import { startFlow } from '@walkeros/collector';
import destinationMatomo from '@walkeros/web-destination-matomo';

await startFlow({
  destinations: {
    matomo: {
      code: destinationMatomo,
      config: {
        loadScript: true,
        settings: {
          siteId: '1',
          url: 'https://analytics.example.com/',
        },
      },
    },
  },
});

The quickstart above sets no consent, so matomo.js loads and Matomo receives every event without analytics consent, and a revocation changes nothing. Add consent: { analytics: true } to config, next to settings, before you go live (see gate a destination).

Configuration​

This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.

Settings​

PropertyTypeDescriptionMore
siteIdstringMatomo Site ID (like 1, 2, etc.). Required when loadScript is true
urlstringBase URL of your Matomo instance, normalized to one trailing slash (like https://analytics.example.com/ or https://yourname.matomo.cloud/). Required when loadScript is true
disableCookiesbooleanDisable all tracking cookies for cookie-free analytics
enableLinkTrackingbooleanEnable automatic outlink and download tracking
enableHeartBeatTimerintegerEnable heart beat timer with interval in seconds for accurate time-on-page
customDimensionsRecord<string, Mapping.Value>Custom dimensions applied to every hit, keyed by bare dimension id (like { "1": "data.userType" }). Each value is resolved per event. Rule-level customDimensions win per key.

Mapping​

Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

PropertyTypeDescriptionMore
goalIdstring | integerMatomo goal ID, a positive integer like 1. Adds a trackGoal conversion alongside this event
goalValueMapping.Value
siteSearchbooleanTrack as internal site search using trackSiteSearch
contentImpressionbooleanTrack as content impression using trackContentImpression
contentInteractionbooleanTrack as content interaction using trackContentInteraction
customDimensionsRecord<string, Mapping.Value>Custom dimensions for this rule, keyed by bare dimension id (like { "3": "data.category" }). Set just before the hit and removed after it; wins per key over the destination customDimensions.

Examples

Custom event with goal

A promotion visible event fires Matomo trackEvent and then trackGoal to record a goal conversion.

Event
{
  "name": "promotion visible",
  "data": {
    "id": "promo_autumn26",
    "name": "Setting up tracking easily",
    "slot": "hero"
  },
  "context": {
    "ab_test": [
      "engagement",
      0
    ]
  },
  "globals": {
    "pagegroup": "homepage"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "1264bd65afd24f10",
  "trigger": "visible",
  "entity": "promotion",
  "action": "visible",
  "timestamp": 1700000401000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Mapping
{
  "name": "trackEvent",
  "settings": {
    "goalId": "1"
  },
  "data": {
    "set": [
      "data.name",
      "data.slot"
    ]
  }
}
Out
_paq.push([
  "trackEvent",
  "Setting up tracking easily",
  "hero"
]);

_paq.push([
  "trackGoal",
  "1",
  null
])

Goal with value

A promotion event fires Matomo trackEvent and then trackGoal with a monetary goal value from event data.

Event
{
  "name": "promotion visible",
  "data": {
    "name": "Setting up tracking easily",
    "slot": "hero",
    "value": 50
  },
  "context": {
    "ab_test": [
      "engagement",
      0
    ]
  },
  "globals": {
    "pagegroup": "homepage"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "1264bd65afd24f10",
  "trigger": "visible",
  "entity": "promotion",
  "action": "visible",
  "timestamp": 1700000406000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Mapping
{
  "name": "trackEvent",
  "settings": {
    "goalId": "1",
    "goalValue": "data.value"
  },
  "data": {
    "set": [
      "data.name"
    ]
  }
}
Out
_paq.push([
  "trackEvent",
  "Setting up tracking easily"
]);

_paq.push([
  "trackGoal",
  "1",
  50
])

Initialization

Destination bootstrap loads the Matomo tracker script and configures the tracker URL and site id.

Event
{
  "loadScript": true,
  "settings": {
    "siteId": "1",
    "url": "https://analytics.example.com/"
  }
}
Out
_paq.push([
  "setTrackerUrl",
  "https://analytics.example.com/matomo.php"
]);

_paq.push([
  "setSiteId",
  "1"
]);

_paq.push([
  "enableLinkTracking"
])

Page view

A page view is tracked in Matomo via trackPageView with the page title from event data.

Event
{
  "name": "page view",
  "data": {
    "domain": "www.example.com",
    "title": "walkerOS documentation",
    "referrer": "https://www.walkeros.io/",
    "search": "?foo=bar",
    "hash": "#hash",
    "id": "/docs/"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "pagegroup": "docs"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "f0cc5f6fec3d8eeb",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000400000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Mapping
{
  "data": "data.title"
}
Out
_paq.push([
  "trackPageView",
  "walkerOS documentation"
])

Page view with goal

A page view rule with a goal keeps the default trackPageView and adds a trackGoal conversion.

Event
{
  "name": "page view",
  "data": {
    "domain": "www.example.com",
    "title": "walkerOS documentation",
    "referrer": "https://www.walkeros.io/",
    "search": "?foo=bar",
    "hash": "#hash",
    "id": "/docs/"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "pagegroup": "docs"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "f0cc5f6fec3d8eeb",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000407000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Mapping
{
  "settings": {
    "goalId": "1"
  }
}
Out
_paq.push([
  "trackPageView",
  "walkerOS documentation"
]);

_paq.push([
  "trackGoal",
  "1",
  null
])

Site search

A search submit fires Matomo trackSiteSearch with the keyword, category, and number of results.

Event
{
  "name": "search submit",
  "data": {
    "term": "shoes",
    "category": "products",
    "results": 42
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "2e85f3543df81dfa",
  "trigger": "test",
  "entity": "search",
  "action": "submit",
  "timestamp": 1700000405000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
Mapping
{
  "name": "trackSiteSearch",
  "settings": {
    "siteSearch": true
  },
  "data": {
    "set": [
      "data.term",
      "data.category",
      "data.results"
    ]
  }
}
Out
_paq.push([
  "trackSiteSearch",
  "shoes",
  "products",
  42
])

When it fails

  • unmapped event: An event without a rule name, a tracking flag or a goal, and not a page view, has no Matomo command: the push fails with missing-input. Reported as failed with code missing-input.

With loadScript: true the destination loads matomo.js from url and sets the tracker URL and site id; a missing siteId or url fails it with a config error. Without loadScript, your own Matomo snippet does both. Commands go onto Matomo's _paq queue, which the tracker works through once it has loaded, so events pushed before that count as sent. If the injected matomo.js fails to load, the pushes after its error fail with vendor-not-loaded and an ERROR line. If no tracker ever loads (no loadScript and no snippet of your own, or a matomo.js that neither loads nor fails), every event counts as sent and none reaches Matomo.

A destination with config.consent tells Matomo when its consent changes: once none of its required keys is granted, it sends forgetConsentGiven, which stops link tracking too, and a grant sends setConsentGiven.

Unmapped events​

A page view needs no rule: it sends trackPageView with the page title. Any other event without rule.name and without a tracking flag (siteSearch, contentImpression or contentInteraction) sends only its goal when the rule has settings.goalId, so a goal-only rule needs no name. Without a goal, such an event fails with missing-input; add an ignore: true rule for events you do not send. A rule with silent: true sends only its goal, and nothing without one.

A goalId must be a Matomo goal ID, a positive integer like 1 or "1". Another value is skipped and logs one ERROR line per cause: the event's own hit goes without the goal, a goal-only rule fails with missing-input, and a silent: true rule sends nothing.

Ecommerce​

Matomo needs an addEcommerceItem call for each product before a cart update, and before an order to record the order's products. A product view is setEcommerceView followed by trackPageView. A rule sends one command per event, so the destination cannot send these sequences.

Custom dimensions​

Custom dimensions are keyed by bare dimension id, like { "1": "data.category" }. Each value is a mapping value, resolved for every event.

  • settings.customDimensions applies to every hit.
  • A rule's settings.customDimensions applies to that rule's hits and wins per key. A rule dimension that resolves to nothing removes that dimension for the hit, even when the destination sets it.

The dimensions are set with setCustomDimension right before the event's hits, a goal included. After them, rule-only dimensions are deleted with deleteCustomDimension and the destination values are set again, so a rule value never leaks into later requests such as outlinks or the heart beat. With destination dimension 1 set to globals.pagegroup and a page view rule dimension 2 set to data.id, a page view pushes:

_paq.push(['setCustomDimension', 1, 'docs']);
_paq.push(['setCustomDimension', 2, '/docs/']);
_paq.push(['trackPageView', 'walkerOS documentation']);
_paq.push(['deleteCustomDimension', 2]);
_paq.push(['setCustomDimension', 1, 'docs']);
💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)