Choose stable identifiers
| Identifier | Rule |
|---|---|
| event_id | Unique for each actual event. Persist and reuse the same ID on transport retries. |
| installation_id | Pseudonymous installation identifier persisted across launches. Do not use an email address. |
| session_id | Optional session identity; the source clients generate it per client instance. |
| flow_id / step_id | Use the saved flow and registered step IDs belonging to the selected app. |
| experiment_id / variant | Use the server assignment; never invent a variant for attribution. |
Supported journey signals
| Event | When to send |
|---|---|
| app_opened | Your app's actual open callback, after tracking is permitted. |
| onboarding_step_viewed | A registered step becomes visible. |
| onboarding_step_completed | The user actually completes the step. |
| onboarding_completed | The entire flow is completed. |
| onboarding_abandoned | Your app's defined abandonment condition occurs. |
| paywall_viewed | The paywall is actually visible. |
| trial_started | A real SDK journey signal for a trial start; not verified billing truth. |
| experiment_exposed | The server-assigned variant is displayed; normally use the SDK expose helper. |
Payload rules
POST /api/v1/events accepts 1–100 events with consent:true. The API rejects unknown object fields. Event names are 1–80 characters, start with a lowercase letter, and use lowercase letters, digits or underscores. Properties accept strings, finite numbers, booleans or null; native source-client helpers currently expose string values.
Use an ISO 8601 occurred_at timestamp with a time-zone offset. The server accepts at most 90 days in the past or 5 minutes in the future. Received time is recorded separately. Keep the request below the 256 KB body limit.
Queues, retries and deduplication
The source SDKs persist queues of up to 1,000 events and flush batches of at most 100. A flush retries network failures, server failures and 429 responses twice, with 500 ms then 1,000 ms waits. Other client errors are surfaced immediately. After the final failure, unsent events remain for a later application-driven flush.
Minimize event data
Do not put names, email addresses, store secrets or raw payment payloads in telemetry. Only send properties needed for the journey you are measuring. Consent revocation clears the local queue; it is not a retroactive deletion API for already-delivered events.