SubmetryDocumentationSet up your app →

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

EventTrigger
first_openFirst configuration with new persisted installation state
session_startConfiguration and each foreground entry
app_openConfiguration and each foreground entry
identity_linkedA 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

EventSwift helperProperties / trigger
onboarding_steponboardingStep(0, id: "goal", answer: "fitness")index, id, optional answer; completed step
onboarding_completedonboardingCompleted()End of onboarding
Your configured activation eventtrack("activation_completed")First meaningful product outcome
paywall_shownpaywallShown("onboarding")paywall; a visible paywall
paywall_plan_selectedpaywallPlanSelected("annual")plan; a selected plan
paywall_dismissedpaywallDismissed()Paywall closes without changing purchase meaning
trial_startedtrialStarted("annual")plan; confirmed free-trial purchase
purchase_completedpurchaseCompleted("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.