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.

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

1. Log into Matomo.
2. Go to Administration (cog icon) > Websites > Manage.
3. 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

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

Configure in Signal

Configuration fields

Management UI setup

1. Go to Integrations > Add Integration > Matomo Analytics.
2. Enter the matomo_url, site_id, and token_auth.
3. Select the Retail preset (the default — covers page, product, cart, and order events).
4. Set consent categories to analytics.
5. 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

Retail preset

All events also carry these global fields:

Example: Order Completed

Datafly.js call:

datafly.track("Order Completed", {
  order_id: "ORD-001",
  revenue: 129.99,
  tax: 21.66,
  shipping: 4.99,
  currency: "USD",
  url: "https://example.com/checkout/confirmation"
});

Matomo payload (form-encoded) sent by Signal:

idsite=1
&rec=1
&token_auth=01234...
&cip=203.0.113.50
&ua=Mozilla/5.0%20...
&_id=a1b2c3d4e5f60718
&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

Matomo records this as an ecommerce order against site 1 attributed to visitor a1b2c3d4e5f60718.

Custom dimensions and goals

To populate Matomo custom dimensions or goal conversions, add field mappings to the integration:

• Custom visit dimensions: target dimension{slot_id} where slot_id is the dimension slot configured in Matomo (1-50).
• Custom action dimensions: target dimension{slot_id} on the relevant event.
• Goals: target idgoal with the numeric goal ID.

Identity

Signal sends the following identity signals to Matomo:

No PII hashing is needed — Matomo’s privacy posture handles IP anonymisation at its own boundary (configurable in Matomo under Privacy > Anonymise data). Signal forwards the raw values; Matomo decides how much of each octet to retain.

Call datafly.identify() to populate uid

datafly.identify("user-123");

Subsequent events carry uid=user-123 to Matomo. Anonymous events fired before identify still map to the same _id so Matomo stitches the visit together.

Consent

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

1. In Matomo, go to Visitors > Visits Log.
2. Filter on Today.
3. 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 an Order Completed event and confirm it appears in Matomo under Ecommerce > Overview with the correct revenue and order ID.

Troubleshooting

See also

• Matomo Tracking HTTP API reference
• Matomo ecommerce setup
• Matomo privacy controls — for IP anonymisation, opt-out, and DNT