Piwik PRO

Datafly Signal delivers events server-to-server to your own Piwik PRO Analytics instance using the Tracking HTTP API (the ppms.php endpoint). Because delivery happens from your first-party Signal endpoint, pageviews, custom events, and ecommerce orders reach Piwik PRO even when the browser blocks third-party requests, and the visitor IP is resolved to geo on your terms.

Prerequisites

• A Piwik PRO account (Core or Enterprise) and an App created under Administration > Sites & apps.
• Your instance host (e.g. yourbrand.piwik.pro or yourbrand.eu.piwik.pro).
• The App ID UUID for the app you want events attributed to (Administration > Sites & apps).
• A tracking token (token_auth) with tracking write permission, created under Administration > API credentials. This token authorises server-side IP (cip) and timestamp (cdt) overrides; without it, backdated or IP-overridden hits are dropped.

Configuration

Configure in Signal

1. In Signal, add a new integration and choose Piwik PRO.
2. Enter your Instance Host, App ID, and Tracking API Token.
3. Attach the integration to a pipeline and select the Default preset.
4. Map your events. The Default preset already maps page, Products Searched, Product Viewed, Product Added, Signed Up, and Order Completed.
5. Save and publish the pipeline.

API Endpoint

POST https://<account_url>/ppms.php
Content-Type: application/json

Each event is sent as a flat JSON object of tracking parameters. idsite, token_auth, rec=1, and send_image=0 are added automatically. Signal sets send_image=0 so Piwik PRO returns 204 No Content instead of a tracking GIF.

Identity Signals

Signal forwards the strongest available identifiers so Piwik PRO can stitch visits and attribute conversions:

• _id / cid — the Piwik PRO visitor ID (16-character hex) for anonymous stitching across hits.
• uid — the logged-in User ID when the visitor is identified.
• cip — the original visitor IP, so Piwik PRO resolves geo server-side rather than seeing your server’s IP.
• ua / lang — the original user agent and locale.

Consent is mapped from your canonical marketing-consent signal so the same blueprint works with any CMP you have classified in Signal Settings.

Event Mapping

A Piwik PRO hit is a pageview when only url / action_name are present, and a custom event when both e_c (category) and e_a (action) are present, with optional e_n (name) and e_v (numeric value). Ecommerce orders set idgoal=0 plus ec_id, revenue, and ec_items.

Example

A Datafly.js call:

datafly.track('Product Viewed', {
  product_id: 'SKU-123',
  product_name: 'Wool Runner',
  price: 98.00,
  currency: 'GBP'
});

is delivered to Piwik PRO as:

{
  "idsite": "892d04bd-6e2b-4914-bfb4-bac721b37235",
  "token_auth": "••••••••",
  "rec": "1",
  "send_image": "0",
  "url": "https://shop.example.com/products/wool-runner",
  "e_c": "Ecommerce",
  "e_a": "view_item",
  "e_n": "Wool Runner",
  "e_v": 98.00,
  "_id": "a1b2c3d4e5f60718",
  "cip": "203.0.113.7",
  "ua": "Mozilla/5.0 ...",
  "lang": "en-GB"
}

An Order Completed event is delivered with idgoal=0 and ec_items as a JSON array of [sku, name, category, price, quantity] tuples:

{
  "idgoal": "0",
  "ec_id": "ORDER-9281",
  "revenue": 196.00,
  "ec_items": "[[\"SKU-123\",\"Wool Runner\",\"Shoes\",98.00,2]]"
}

Testing

1. Send a test event through your pipeline (use Signal’s Event Debugger or a live page).
2. In Piwik PRO, open Analytics > Live (or the real-time report) and confirm the visit, pageview, or event appears with the correct geo (proving cip was honoured).
3. For ecommerce, check Analytics > Ecommerce for the order under its ec_id.
4. Confirm custom events show under Analytics > Events with the expected category/action/name.

Troubleshooting

• Event not appearing — confirm account_url has no scheme and no trailing slash, and that idsite is the App UUID (not the numeric Matomo-style ID).
• Geo shows your server location — the token_auth is missing or lacks tracking permission, so the cip override was ignored. Regenerate the token under Administration > API credentials.
• Backdated events dropped — hits with a cdt timestamp older than ~24h require a valid token_auth. Verify the token and that the pipeline is delivering in near real time.
• Pageview recorded as an event (or vice versa) — a hit becomes a custom event only when both e_c and e_a are set. Check your event mappings if a pageview is misclassified.
• 403 / 401 responses — bad or missing token_auth. 404 — wrong account_url host or unknown idsite.