Event protocol & standard events
The unified event schema, limits, validation rules and the standard event catalogue.
All SDKs speak the same protocol. Send batches to POST /v1/sdk/events with header X-Project-Key: pk_….
POST /v1/sdk/events
{
"events": [{
"event": "purchase_completed",
"user_id": "u_8f3a91",
"session_id": "s_29d1",
"timestamp": "2026-11-20T10:00:00Z",
"platform": "web",
"app_version": "1.4.2",
"consent": { "analytics": true, "personalization": true, "marketing": false },
"properties": { "revenue": 4.99, "currency": "USD", "sku": "gems_100" },
"insert_id": "b7c0…" // idempotency key
}]
}Response
{ "accepted": 1, "dropped_no_consent": 0, "duplicates": 0, "invalid": 0, "stripped_pii_keys": [] }Rules
- Up to 500 events per batch; properties up to 8 KB and 64 keys per event.
- Event names: lowercase
snake_case, ≤ 64 characters (^[a-z][a-z0-9_]{0,63}$). Reserved internal names:$exposure,$identify. - Events without
consent.analytics = trueare discarded. - Property keys that look like personal data (email, phone, card, address, names, date of birth…) are stripped and reported in
stripped_pii_keys. - Duplicate
insert_ids are ignored. Timestamps more than 10 minutes in the future or older than the project’s retention period are rejected. - Revenue:
properties.revenue(decimal, major units) plusproperties.currency(ISO 4217).
Standard events
| Event | Typical properties |
|---|---|
app_opened | — |
session_started / session_ended | automatic |
screen_viewed | screen |
feature_used | feature |
signup_completed | method |
purchase_completed | revenue, currency, sku |
subscription_started | plan, revenue, currency |
subscription_cancelled | plan |
ad_impression | placement, revenue |
ad_reward_completed | placement |
level_started / level_completed / level_failed | level |
offer_viewed / offer_accepted | offer |
notification_opened | campaign_id |
Custom events are welcome — any valid name works and appears in funnels and the Advisor.