Matomo Analytics

Datafly Signal delivers events to Matomo Analytics server-to-server using the Tracking HTTP API. Matomo is the open-source, self-hostable analytics platform of choice for organisations that need full data sovereignty — popular with EU regulators, public-sector bodies, and privacy-led brands.

Tracking API delivery is operational with a default Retail preset covering page, product, and ecommerce events. Custom dimensions and goal conversions can be added through field mappings. Contact your account team for help wiring custom dimensions to Matomo slot IDs.

Why route Matomo Analytics through Datafly Signal

Your numbers stop depending on what the browser allows. Client-side analytics loses every visit where the tag is blocked or the page unloads early. Signal delivers from the server, so Matomo Analytics receives the complete event stream.
Client IP and user agent are carried in the payload. Both are taken from the original visitor request rather than your server, which is what Matomo Analytics needs to attribute the event to the right session.
One consent decision governs every destination. Matomo Analytics is gated by the same consent state as the rest of your stack, so a withdrawal applies everywhere at once.

Prerequisites

Before configuring Matomo in Signal you need:

A Matomo instance. Either:
- Matomo Cloud: your tenant base URL, e.g. https://yourcompany.matomo.cloud.
- Self-hosted Matomo: the public base URL of your deployed instance.
The Site ID of the Matomo site you want events delivered to.
An auth token (token_auth). Required for server-side tracking — without it Matomo will not let you override visitor IP, set custom visitor IDs, or stamp historical timestamps.

Get your credentials

Step 1: Note your Matomo instance URL

This is the base URL where you log into Matomo. Strip any trailing slash. Examples:

Matomo Cloud: https://acme.matomo.cloud
Self-hosted: https://analytics.example.com

Signal will POST events to {matomo_url}/matomo.php.

Step 2: Find your Site ID

Log into Matomo.
Go to Administration (cog icon) > Websites > Manage.
Find the site you want Signal to track and note the ID column. It is a small integer (1, 2, 3, …).

Step 3: Generate a token_auth

In Matomo, click your username (top right) > Security.
Scroll to Auth tokens and click Create new token.
Give it a name (e.g. Datafly Signal).
Confirm with your password.
Copy the token.

⚠️

Store this token as a secret. Anyone holding it has the same write access to your Matomo data that you do. Generate a per-environment token (one for staging, one for production) so revocation is granular.

Configure in Signal

Configuration fields

Field	Required	Description
`matomo_url`	Yes	Base URL of your Matomo instance, no trailing slash (e.g. `https://analytics.example.com`).
`site_id`	Yes	Numeric Matomo Site ID from the Websites admin page.
`token_auth`	Yes	Matomo auth token (32-character hex). Stored as a secret.

Management UI setup

Go to Integrations > Add Integration > Matomo Analytics.
Enter the matomo_url, site_id, and token_auth.
Select a preset: Default, Retail or Insurance.
Set consent categories to analytics.
Click Save.

Management API setup

curl -X POST http://localhost:8084/v1/admin/integrations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "src_abc123",
    "vendor": "matomo",
    "name": "Matomo Production",
    "enabled": true,
    "config": {
      "matomo_url": "https://analytics.example.com",
      "site_id": "1",
      "token_auth": "0123456789abcdef0123456789abcdef"
    },
    "consent_categories": ["analytics"]
  }'

API endpoint

POST {matomo_url}/matomo.php
Content-Type: application/x-www-form-urlencoded

Matomo’s tracker uses form-encoded key=value pairs, not JSON. Signal handles encoding automatically.

Event mapping

Every request carries idsite, rec=1 and token_auth (from the connection), _id, uid, cip, ua, lang, cdt (event time, Unix seconds), url, urlref, apiv=1, send_image=0 and _rcn/_rck (campaign name and keyword for goal attribution). Only the parameters the preset maps for the event are sent; an unmapped property is never forwarded.

Signal event	Matomo request	Parameters
`page`	Page view	`action_name` (page title)
`view_item`	Page view with product view	`_pks`, `_pkn`, `_pkc`, `_pkp` from the first item
`search`, `view_search_results`	Site search	`search`, `search_count`, `search_cat`
`view_cart`, `begin_checkout`	Cart update	`idgoal=0`, `ec_items` (the whole cart), `revenue`
`purchase` (and `policy_purchased` in Insurance)	Ecommerce order	`idgoal=0`, `ec_id`, `revenue`, `ec_items`, `ec_tx`, `ec_sh`, `ec_dt`
Everything else	Custom event	`e_c` (category), `e_a` (the event name), `e_n` (the most descriptive property, e.g. the item or plan name), `e_v` (numeric value), `ca=1`

add_to_cart and remove_from_cart are custom events, not cart updates: Matomo treats a cart update as the whole cart and removes anything it does not list. ec_items is a JSON array of [sku, name, category, price, quantity] built from items[]. Matomo has no currency parameter; revenue is recorded in the site’s currency.

Presets: Default (page, search, purchase, and sign-up, login, lead, add to cart, checkout and subscription start and cancel as custom events), Retail (the full ecommerce spec) and Insurance (the insurance spec, with purchase and policy_purchased as orders).

Example: purchase

datafly.track("purchase", {
  transaction_id: "ORD-001", value: 129.99, tax: 21.66, shipping: 4.99, currency: "GBP",
  items: [{ item_id: "SKU-A", item_name: "Widget", item_category: "Tools", price: 62.5, quantity: 2 }]
});

idsite=1&rec=1&token_auth=01234...
&_id=a1b2c3d4e5f60718&uid=user-123&cip=203.0.113.50&cdt=1717628400
&url=https%3A%2F%2Fexample.com%2Fcheckout%2Fconfirmation
&idgoal=0&ec_id=ORD-001&revenue=129.99&ec_tx=21.66&ec_sh=4.99
&ec_items=%5B%5B%22SKU-A%22%2C%22Widget%22%2C%22Tools%22%2C62.5%2C2%5D%5D

Custom dimensions and goals

Add field mappings on the installed integration: dimension{id} for a custom dimension, idgoal with a numeric goal ID for a goal conversion.

Identity

Matomo field	Signal source	Description
`_id`	A collected `matomo_visitor_id`, else the first 16 hex characters of md5(anonymous ID)	Matomo requires exactly 16 hexadecimal characters. If you also run Matomo’s JavaScript tracker, add a collected ID named `matomo_visitor_id` that reads the visitor ID from the `_pk_id` cookie, so server events join the browser visits.
`uid`	`user_id`	Matomo’s User ID, once the visitor signs in.
`cip`	Visitor IP	Drives GeoIP. Requires `token_auth`.
`ua`	Visitor user agent	Browser, OS and device detection.
`cdt`	Event time	Unix seconds. An event older than 24 hours needs `token_auth`, which the connection supplies.

No personal data is sent. Matomo applies its own IP anonymisation (Privacy > Anonymise data).

The default consent category is analytics. Matomo is a first-party analytics destination and respects the visitor’s analytics consent state — events drop silently when consent has been withdrawn.

If you have configured Matomo’s opt-out feature on your site, the Tracking API request honours it through the standard Matomo logic (Signal forwards the relevant headers).

Verify it’s working

Step 1: Trigger a test pageview

From a page running Datafly.js:

datafly.page({
  url: window.location.href,
  title: document.title
});

Step 2: Check Matomo’s Visitor Log

In Matomo, go to Visitors > Visits Log.
Filter on Today.
Your test visit should appear within a few seconds, with Source = Direct Entry (or the appropriate referrer) and the page title you sent.

Step 3: Inspect the Signal event debugger

In the Signal Management UI, open the Matomo integration’s Recent Events tab. You should see the event with a 204 response (Matomo’s success code) and the form-encoded payload.

Step 4: Verify ecommerce tracking

Fire a purchase event and confirm it appears in Matomo under Ecommerce > Overview with the correct revenue and order ID.

Troubleshooting

Problem	Solution
Events arrive but `cip` and `_id` are not honoured	The `token_auth` is missing, invalid, or its account lacks write access to the site. Regenerate a token under an admin user.
Geo location is blank	Matomo’s GeoIP database is not configured. Install GeoIP under Administration > Geolocation. Signal sends the IP correctly.
Events return 200 but do not appear in reports	Check `idsite` matches the target site. If Matomo’s opt-out or Do Not Track setting is enabled, events for opted-out visitors are intentionally dropped.
Ecommerce orders missing	`idgoal=0` is required for orders, plus `ec_id` for the order ID. Verify both are mapped. Also ensure ecommerce tracking is enabled on the Matomo site under Administration > Websites > Manage > Enable Ecommerce.
Slow page rendering in Matomo reports	Matomo is self-hosted on under-provisioned infrastructure. This is a Matomo-side performance question, not a Signal delivery question.
Server and browser visits do not join	Add the `matomo_visitor_id` collected ID (the `_pk_id` visitor ID); otherwise `_id` is derived from the Signal anonymous ID.