IntegrationsAnalyticsPiwik PRO

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.

Why route Piwik PRO 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 Piwik PRO 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 Piwik PRO needs to attribute the event to the right session.
  • One consent decision governs every destination. Piwik PRO is gated by the same consent state as the rest of your stack, so a withdrawal applies everywhere at once.

Prerequisites

  • A Piwik PRO account 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.

No tracking credential is needed: the current tracking reference documents the IP (cip) and time (cdt) overrides without one.

Configuration

FieldRequiredDescription
Instance Host (account_url)YesYour Piwik PRO host, no scheme, no trailing slash (e.g. yourbrand.piwik.pro).
App ID (idsite)YesThe App UUID, e.g. 892d04bd-6e2b-4914-bfb4-bac721b37235.

Configure in Signal

  1. In Signal, add a new integration and choose Piwik PRO.
  2. Enter your Instance Host and App ID.
  3. Attach the integration to a pipeline and select a preset: Default, Retail or Insurance.
  4. Save and publish the pipeline.

API Endpoint

POST https://<account_url>/ppms.php
Content-Type: application/x-www-form-urlencoded

Each event is one hit: the tracking parameters as a query string in the request body, one of the three forms the reference documents. idsite, rec=1 and send_image=0 are added automatically. Only the parameters the preset maps for the event are sent.

Identity Signals

  • _id: a collected piwik_visitor_id (add a collected ID that reads the Piwik PRO visitor ID if you also run its JavaScript tracker), else the first 16 hex characters of md5(Signal anonymous ID). Piwik PRO requires 16 hexadecimal characters.
  • uid: the signed-in user ID.
  • cip, ua, lang: the visitor’s IP, user agent and locale.
  • cdt: the event time, Unix seconds.
  • uia=1 when analytics consent is denied (the event is delivered under an analytics exemption): Piwik PRO tracks the visitor anonymously.

No personal data is sent.

Event Mapping

Signal eventPiwik PRO hit
pagePage view: url, action_name, urlref
search, view_search_resultsSite search: search, search_count, search_cat
view_iteme_t=product-detail-view with ec_products (the first item)
add_to_cart, remove_from_carte_t=add-to-cart / remove-from-cart with ec_products
view_cart, begin_checkoute_t=cart-update with ec_products and revenue (cart total)
purchase (and policy_purchased in Insurance)e_t=order: ec_id, revenue, ec_products, ec_tx, ec_sh, ec_dt
Everything elseCustom event: e_c (category), e_a (the event name), e_n, numeric e_v

Ecommerce hits carry cur, the upper-cased ISO 4217 currency. ec_products is a JSON array of [sku, name, category, price, quantity, brand, variant] built from items[] (at most 100 products).

Example

datafly.track('purchase', {
  transaction_id: 'ORDER-9281', value: 196.00, currency: 'gbp',
  items: [{ item_id: 'SKU-123', item_name: 'Wool Runner', item_category: 'Shoes', price: 98.00, quantity: 2 }]
});
idsite=892d04bd-6e2b-4914-bfb4-bac721b37235&rec=1&send_image=0
&_id=a1b2c3d4e5f60718&uid=user-123&cip=203.0.113.7&cdt=1717628400
&url=https%3A%2F%2Fshop.example.com%2Fcheckout%2Fdone
&e_t=order&ec_id=ORDER-9281&revenue=196&cur=GBP
&ec_products=%5B%5B%22SKU-123%22%2C%22Wool+Runner%22%2C%22Shoes%22%2C98%2C2%2C%22%22%2C%22%22%5D%5D

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 — check that the event carried the visitor IP (cip) in the Event Debugger.
  • 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.
  • 404 — wrong account_url host or unknown idsite.
Piano AnalyticsStatsig