# 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

```swift
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](https://submetry.com/docs/http.md) for payload validation and [RevenueCat](https://submetry.com/docs/revenuecat.md) for server event normalization.
