Measurement Protocol and server SDKs

Use the Measurement Protocol when an event happens outside a browser. Open Site settings → Measurement Protocol, create an ingest key and store it in your server-side secret manager. Keys are shown once, can expire and can be rotated without downtime.

Never embed an ingest key in browser or mobile application code. Calls from public clients should go through your backend.

Endpoint#

Send one event or a batch of up to 100 events to POST https://purestats.io/api/v1/events:

Authorization: Bearer ps_ingest_...
Content-Type: application/json

{
  "events": [
    {
      "type": "event",
      "event_id": "0123456789abcdef0123456789abcdef",
      "name": "Signup",
      "user_id": "your-internal-pseudonymous-id",
      "properties": { "method": "email" },
      "context": { "page": { "url": "https://example.com/register" } }
    }
  ]
}

Supported types are page, screen, event, identify, experiment and commerce. Event IDs are deduplication keys and must contain 12–32 URL-safe characters. Missing IDs are generated by PureStats, but SDKs generate them before the first attempt so retries remain idempotent.

Each result is stored, duplicate, filtered, invalid or error. A mixed batch returns HTTP 207 and keeps the outcome of every event independent.

Visitor IP forwarding#

The sender's server IP is never interpreted as a visitor IP. The optional X-PureStats-Client-IP header is accepted only with a timestamp no older than five minutes and an HMAC-SHA256 signature made with the ingest key:

signature = HMAC_SHA256(<timestamp> + "\n" + <ip> + "\n" + SHA256(<raw body>), ingest_key)

Send the timestamp in X-PureStats-Client-IP-Timestamp and the lowercase digest in X-PureStats-Client-IP-Signature. Site IP-anonymization and geo-precision settings still apply.

Official SDK source#

Publish-ready Node/TypeScript, PHP, Kotlin and Swift packages live in the PureStats SDK source tree. They provide stable event IDs, batches, retry with backoff and an in-memory offline queue. Persist the queue in your application's durable job system when delivery must survive a process restart.