Events
Submetry creates an Events entry automatically when it accepts a new event name for your app. Custom events need no registration. Built-in dashboards use specific names and properties; preserve their meaning.
Automatic Swift SDK events
| Event | Trigger |
|---|---|
first_open | First configuration with new persisted installation state |
session_start | Configuration and each foreground entry |
app_open | Configuration and each foreground entry |
identity_linked | A valid call to identify |
When using the Swift SDK, do not duplicate these manually. The downloadable Android, Dart and JavaScript adapters also emit these at configuration. Wire subsequent foreground session transitions using their platform guide.
Manual funnel and paywall events
| Event | Swift helper | Properties / trigger |
|---|---|---|
onboarding_step | onboardingStep(0, id: "goal", answer: "fitness") | index, id, optional answer; completed step |
onboarding_completed | onboardingCompleted() | End of onboarding |
| Your configured activation event | track("activation_completed") | First meaningful product outcome |
paywall_shown | paywallShown("onboarding") | paywall; a visible paywall |
paywall_plan_selected | paywallPlanSelected("annual") | plan; a selected plan |
paywall_dismissed | paywallDismissed() | Paywall closes without changing purchase meaning |
trial_started | trialStarted("annual") | plan; confirmed free-trial purchase |
purchase_completed | purchaseCompleted("annual") | plan; confirmed paid purchase |
Do not record purchase success when the user taps a button, cancels, fails payment or restores a past purchase. The client event is purchase_completed, not paywall_purchased. Verified revenue comes from RevenueCat webhooks. Client outcomes and webhook outcomes join users instead of supplying independent financial totals.
The subscription funnel measures the ordered journey from first open through onboarding, activation, paywall, trial/first purchase and paid subscription. Steps count resolved unique people. Repeated paywall views remain event counts. Onboarding reports read id (or step); paywall reports read paywall and plan/product.
Custom product events
Submetry.track("workout_completed", properties: [
"type": "strength",
"duration_min": 25,
"is_first_workout": true
])Choose 5–10 events covering core actions, success, failure and return usage. Use lowercase snake_case names starting with a letter, up to 80 characters. Prefer completed outcomes such as document_exported over ambiguous names. Renaming creates a new entry. rc_ is reserved for authenticated server events and rejected from client ingestion.
Properties must be a JSON object of at most 8 KiB. JSON-compatible strings, numbers, booleans, nulls, arrays and objects are supported. Prefer small scalar dimensions. Avoid user-entered text, names, emails, credentials and document content.
Context and identity
Each event has its own ID, Unix timestamp in seconds, anonymous installation ID and session ID. uid is optional; when using RevenueCat it should match the RevenueCat app user ID. Short string context values describe platform, version, build, OS, locale, timezone and environment. The backend resolves country from supplied context or Cloudflare request metadata.
The dashboard environment must match production, debug, sandbox or testflight. See HTTP ingestion for payload validation and RevenueCat for server event normalization.