Matomo
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.
Matomo is a web destination in the walkerOS flow:
Installation
npm install @walkeros/collector @walkeros/web-destination-matomo- Integrated
- Bundled
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/',
},
},
},
},
});
A complete flow.json with this destination:
{
"version": 4,
"flows": {
"default": {
"config": {
"platform": "web"
},
"destinations": {
"matomo": {
"package": "@walkeros/web-destination-matomo",
"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
| Property | Type | Description | More |
|---|---|---|---|
siteId | string | Matomo Site ID (like 1, 2, etc.). Required when loadScript is true | |
url | string | Base 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 | |
disableCookies | boolean | Disable all tracking cookies for cookie-free analytics | |
enableLinkTracking | boolean | Enable automatic outlink and download tracking | |
enableHeartBeatTimer | integer | Enable heart beat timer with interval in seconds for accurate time-on-page | |
customDimensions | Record<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.
| Property | Type | Description | More |
|---|---|---|---|
goalId | string | integer | Matomo goal ID, a positive integer like 1. Adds a trackGoal conversion alongside this event | |
goalValue | Mapping.Value | ||
siteSearch | boolean | Track as internal site search using trackSiteSearch | |
contentImpression | boolean | Track as content impression using trackContentImpression | |
contentInteraction | boolean | Track as content interaction using trackContentInteraction | |
customDimensions | Record<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.
{
"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"
}
}{
"name": "trackEvent",
"settings": {
"goalId": "1"
},
"data": {
"set": [
"data.name",
"data.slot"
]
}
}_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.
{
"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"
}
}{
"name": "trackEvent",
"settings": {
"goalId": "1",
"goalValue": "data.value"
},
"data": {
"set": [
"data.name"
]
}
}_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.
{
"loadScript": true,
"settings": {
"siteId": "1",
"url": "https://analytics.example.com/"
}
}_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.
{
"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"
}
}{
"data": "data.title"
}_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.
{
"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"
}
}{
"settings": {
"goalId": "1"
}
}_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.
{
"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"
}
}{
"name": "trackSiteSearch",
"settings": {
"siteSearch": true
},
"data": {
"set": [
"data.term",
"data.category",
"data.results"
]
}
}_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
failedwith codemissing-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.customDimensionsapplies to every hit.- A rule's
settings.customDimensionsapplies 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']);