SDK Analytics Events

Send lifecycle and custom events from the mobile SDK.

Event types#

Custom events — any named event with optional data payload (e.g., purchase_completed).
Retention events — lifecycle signals like app_open. Retention is never sent automatically: it requires an explicit logRetention("app_open") call at the point the signal occurs.

Sending events#

json

POST /api/v1/sdk/analytics/events
Authorization: Bearer pk_live_xxx

{
  "appID": "app_abc123",
  "eventName": "purchase_completed",
  "data": { "bookingId": "104971", "amount": 199.0 },
  "eventId": "a1b2c3d4-e5f6-4a7b-8c9d-0123456789ab (optional)"
}

The SDK sends exactly { appID, eventName, data }; it generates and attaches eventId when you do not supply one. The backend also accepts payload as an alias for data and event as an alias for eventName. Optional attribution fields (top-level or inside the payload): linkId, clickContextId, qrCodeId, domainId, clickId.

Note

Event ingestion is non-blocking: the API returns { accepted: true, queued: true, eventId } immediately after queue acceptance. Processing happens asynchronously.

Processing pipeline#

text

SDK POST -> Worker validates minimal schema
  -> enqueue to SDK Events Queue
  -> return { "accepted": true, "queued": true, "eventId": "..." }

Queue consumer -> batch messages
  -> validate full schema
  -> idempotent write (event_id dedup)
  -> Analytics Engine + D1 sampled storage

Events are deduplicated by event_id within a scoped window. Failed messages retry with backoff and eventually route to a dead-letter queue.