Events & catalogue

#Sending an event from the SDK

Call Pushlane.track() anywhere after Pushlane.identify(). The SDK builds an EventEnvelope with a fresh UUID event ID, a W3C traceparent, the current timestamp, and a full context block (app version, OS version, timezone, locale, install environment), then ships it to the ingest endpoint.

// Minimal — no properties
Pushlane.track("paywall_viewed")

// With typed properties
Pushlane.track("paywall_viewed", [
    "placement": "onboarding",
    "paywall_id": "pw_annual_v2"
])

Property value types — the Swift PushlaneValue enum accepts:

String, integer, float, and boolean literals are converted automatically, so you rarely need to write PushlaneValue.string(…) explicitly.

#Auto-emitted events

Two lifecycle events are emitted by the SDK itself — do not re-instrument them:

Both events carry context.appVersion and context.osVersion, which the ingest worker projects onto the user as targetable attributes (app_version, os_version, install_env) in ClickHouse. These attributes power the audience builder's version picker.

Three more names are written by Pushlane's own clients when a user interacts with a notification — opened, dismissed and received. They are reserved, and they are documented in the next section.

#Notification interaction events

These are the events that measure what happened after a push left Pushlane. They are reserved names: the iOS SDK and the drop-in clients emit them wherever the platform lets them — which is not everywhere, so read the availability table below before you assume a number exists. Where a client does emit one, do not re-instrument it; and never rename these events, whichever way they reach Pushlane.

Pushlane stamps message_id, flow_id and node_id at the top level of every push payload it sends, alongside aps. Reading those keys back on the interaction event is the entire attribution mechanism.

Availability per client. Open tracking landed in drop-in client v1.3.0 — if you pasted an earlier drop-in, re-copy it from the quickstart. What each client can actually report:

#Recommended event taxonomy

These are the high-signal events that unlock the most useful flows for subscription apps. Use the exact snake_case names — the catalogue types them automatically on first sight.

Revenue events arrive on their own once the RevenueCat integration is connected — you do not need to call Pushlane.track() for trials, purchases, renewals or cancels. They land under their own revenuecat. names, though: revenuecat.trial_started, revenuecat.initial_purchase, revenuecat.cancellation, and so on. A flow triggering on the bare trial_started above will not fire from RevenueCat — pick the revenuecat. name in the trigger picker instead, or track your own event if you want one name for both paths.

#Mirror your existing analytics into Pushlane.track

If your app already calls an analytics library (analytics.track, logEvent, Amplitude / Mixpanel / Segment), the fastest way to give Pushlane real signal is to mirror those calls into Pushlane.track additively — keep your existing analytics, and add a Pushlane.track alongside each call. Three rules keep the mirror honest:

1. Add, don't replace. Your analytics keeps working; Pushlane just also receives the event.
2. Rename reserved names. message_sent is written server-side by Pushlane (delivery telemetry) and can never trigger a flow, so a chat app's own event must be renamed (e.g. chat_message_sent). Otherwise your real event is silently un-triggerable and under-counted.
3. Skip the auto-emitted names. app_open and session_started are already emitted by the SDK (or a drop-in client's start()). Mirroring an “App Opened” / “Session Start” from your analytics would double-count.
4. Never hand-roll notification interactions. opened, dismissed and received are emitted for you (see above), and the reports open rate matches them on message_id. A “Push Opened” mirrored from your analytics under its own name carries no message_id, so it is invisible to the metric — and a second listener under the right name would log two events per tap.

// existing analytics — keep it
analytics.track('paywall_viewed', { placement: 'home' });

// mirror into Pushlane, additively
Pushlane.track('paywall_viewed', { placement: 'home' });

// a reserved name MUST be renamed for Pushlane:
// analytics.track('message_sent', …)  →  Pushlane.track('chat_message_sent', …)

// do NOT mirror app_open / session_started — the SDK already emits them.

// do NOT hand-roll a push-open event either. This one is INVISIBLE to open rate:
// analytics.track('Push Opened', { campaign: 'trial_day_3' });
// Pushlane's client already emits 'opened' with message_id / flow_id / node_id.

Reconcile every event name and property type you mirror against the catalogue below so you reuse existing types instead of creating drift. The Pushlane MCP's plan_instrumentation tool does this reconciliation for you — it flags reserved-name collisions and auto-emitted duplicates against your live catalogue.

#Sending events from a server (HTTP API)

You can also POST events directly from your backend — useful for server-side billing events or webhooks. The shape is identical to what the SDK sends:

curl -X POST https://ingest.pushlane.io/v1/events \
  -H "Authorization: Bearer lpk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_abc123",
    "name": "subscription_started",
    "properties": {
      "plan": "annual",
      "product_id": "com.yourapp.annual",
      "price_usd": 49.99
    },
    "occurredAt": 1719878400000
  }'

#How the catalogue works

The catalogue is the typed registry of event names and property names for your tenant. It fills in automatically as events arrive — no manual schema step is required.

When the queue consumer processes an event:

1. If the event name has never been seen, it is upserted into catalogue_events with declared=false.
2. Properties are coerced against any declared=true entry in catalogue_properties. If no declared type exists, the raw value is stored and the property is surfaced as undeclared.
3. You can promote any auto-discovered event or property to declared=true in the dashboard and set an explicit type. Once declared, mismatches produce a coercion warning in the trace log — the event is never dropped.

The catalogue is also the data source for the Audience builder and the flow condition editor — a property only appears in those pickers once it has been seen at least once in an event.

#Property kinds

The catalogue distinguishes two kinds of properties:

User attributes are what {{ name | fallback }} tokens in notification copy resolve against at send time. An event property is scoped to one occurrence and is not available as a token.

#Writing user attributes

Call Pushlane.setAttributes after Pushlane.identify to persist traits you want to use in notification personalisation — first name, onboarding answers, plan, preferences. Values are written most-recent-wins.

// Drop-in clients (Expo / React Native / Flutter / Android)
Pushlane.setAttributes({
  first_name: user.firstName,     // string
  plan: 'growth',                 // string
  trial_days_left: 7,             // number
});

// null explicitly unsets an attribute (stops it from resolving in templates):
Pushlane.setAttributes({ trial_days_left: null });

// iOS SDK — literals infer their PushlaneValue case; variables use the
// explicit case (.string(...) / .int(...)).
Pushlane.setAttributes([
    "first_name": .string(user.firstName),
    "plan": "growth",               // literal → .string
    "trial_days_left": 7,           // literal → .int
])

From a server, use POST /v1/attributes. The same Bearer write-key authenticates the request, and the same externalId ties the attributes to the user:

curl -X POST https://ingest.pushlane.io/v1/attributes \
  -H "Authorization: Bearer lpk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_42",
    "attributes": {
      "first_name": "Alice",
      "plan": "growth",
      "trial_days_left": 7
    }
  }'

#Marketing consent — opt-out model

Pushlane uses an opt-out model for marketing notifications. A device that has granted push permission (registering via PushlanePush.register() / POST /v1/register) is considered opted-in by default. Flows will send to that device unless the user has recorded an explicit opt-out.

To record a user's preference call Pushlane.setMarketingConsent(false) (opt out) or Pushlane.setMarketingConsent(true) (re-opt-in) from the iOS SDK. From your server, POST to /v1/consent:

curl -X POST https://ingest.pushlane.io/v1/consent \
  -H "Authorization: Bearer lpk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_42",
    "action":     "opt_out",
    "category":   "marketing"
  }'

#Event deduplication

Pushlane deduplicates events at two layers:

• DedupDO (in-process) — a Cloudflare Durable Object keyed by `${tenantId}:${eventId}` gates the event before any ClickHouse write. A duplicate is acknowledged immediately and skipped.
• ClickHouse dedup token — the same tenant-scoped key is passed as insert_deduplication_token to ClickHouse Cloud's SharedMergeTree, providing a storage-layer guarantee for events that made it past the DedupDO on a retry.

The SDK generates a fresh UUID eventId on each Pushlane.track() call. If you POST from a server and generate the ID yourself, use the same ID on retries to get idempotency for free.