# Submetry quickstart

Connect your application, record its user journey, then verify the events in Submetry. This guide is also available at https://submetry.com/docs/quickstart for people and as Markdown for coding agents.

## 1. Choose your app

Open [Setup](https://submetry.com/app/setup). Select an existing app, import from RevenueCat, or create an app with its name, platform, bundle/package ID and activation event. Copy its App ID and public ingestion key (`sub_pk_…`). Choose the framework and revenue provider, then copy the complete coding-agent prompt into the agent working on your application repository.

An event accepted with that key belongs to that app automatically. There is no event-registration step. RevenueCat app import creates or links projects; it does not instrument your code or import historical purchases.

## 2. Install tracking

For native Swift, download [Submetry.swift](https://submetry.com/sdk/Submetry.swift), add it to your app target in Xcode and enable target membership. It uses Foundation/UIKit, has no external dependencies and supports iOS 13+. When added as a source file, no `import Submetry` is needed. If your checkout already contains the `sdk/swift` package, use Xcode → File → Add Package Dependencies → Add Local, and `import Submetry`.

Configure once at application launch, before tracking user actions:

```swift
Submetry.configure(
    appId: "YOUR_APP_ID",
    key: "YOUR_PUBLIC_KEY",
    endpoint: URL(string: "https://api.submetry.com/v1/events")!
)
```

If RevenueCat is installed, configure Purchases first, and add `userId: Purchases.shared.appUserID` to the configuration. See [Native Swift](https://submetry.com/docs/swift.md) for launch and identity details.

For [Android](https://submetry.com/docs/android.md), [Flutter](https://submetry.com/docs/flutter.md), [React Native / Expo](https://submetry.com/docs/react-native.md) download the source adapter linked in the matching guide. Android, Dart and JavaScript adapters provide persistent queues and identity. They require your existing storage/lifecycle integration; device validation remains your responsibility. Browser web apps use [HTTP ingestion](https://submetry.com/docs/http.md) through a same-origin server.

## 3. Add meaningful events

Place calls at actual transitions and confirmed outcomes, rather than every view render:

```swift
Submetry.onboardingStep(0, id: "goal", answer: "fitness")
Submetry.onboardingCompleted()
Submetry.track("activation_completed")
Submetry.paywallShown("onboarding")
Submetry.paywallPlanSelected("annual")
// Only after a confirmed successful purchase, emit the applicable outcome:
Submetry.trialStarted("annual") // if a free trial actually started
// OR Submetry.purchaseCompleted("annual") for a paid purchase
Submetry.paywallDismissed()
Submetry.track("workout_completed", properties: ["type": "strength", "duration_min": 25])
```

Replace `activation_completed` with the activation event configured for your app. Record it when the user first receives your product's value. Add 5–10 custom events chosen from your main product flows, including useful completion and failure states. Keep names stable and properties small. The [event guide](https://submetry.com/docs/events.md) defines all supported names.

## 4. Connect subscription revenue

Use the [RevenueCat guide](https://submetry.com/docs/revenuecat.md) to configure the app-specific webhook and its separate Authorization secret. Link SDK users to RevenueCat's app user ID. Client purchase events measure the purchase flow; financial revenue and subscription lifecycle come from verified webhooks. [Superwall](https://submetry.com/docs/superwall.md) is an alternative financial source; disconnect RevenueCat before switching.

## 5. Verify the actual integration

Build and run your app. A new installation emits `first_open`, `session_start` and `app_open` automatically with the Swift SDK. Exercise onboarding, activation and the paywall. Call `Submetry.flush()` if you want an immediate upload.

In Setup, select “Écouter mon app”, or open Events and Journeys. Select the matching environment: debug builds send `debug`, sandbox receipts send `sandbox`, and release builds send `production`. Known TestFlight distributions should pass `environment: "testflight"` explicitly. Setup listens across all environments.

HTTP 202 means the batch was accepted. Cloudflare dashboard snapshots update on a ten-minute aggregation schedule; storage propagation can also take time. Event details and journeys depend on raw storage availability. A mock or synthetic request verifies only that request, not your app's integration.

## Troubleshooting

- 401: use this app's current public key; a rotated or revoked key no longer works.
- 400/413: inspect the [payload constraints](https://submetry.com/docs/http.md); timestamps are Unix seconds, not milliseconds.
- Empty dashboard: check environment, date range, App ID and whether the device can reach the HTTPS endpoint. Allow aggregation time.
- Revenue without a joined journey: pass the same user ID to Submetry and RevenueCat.
- Simulator or physical-device networking: `localhost` refers to the device; use the public HTTPS endpoint.

Continue with [Events](https://submetry.com/docs/events.md), [RevenueCat](https://submetry.com/docs/revenuecat.md) and [Managing apps](https://submetry.com/docs/apps.md).
