# iOS & Swift

> Track screens, events and signed-in users in native iOS, iPadOS, macOS and visionOS apps, with an offline queue and consent.

Source: https://metricraven.com/docs/ios-sdk  
Markdown: https://metricraven.com/docs/ios-sdk.md  
Section: Installation guides

The `MetricRaven` Swift package records screen views, goals and identified users from native apps. Each device shows on the realtime globe as a live visitor, under the person you identified it as. It has no dependencies.

## Set up

1. **Allow your app in Settings**

   In your site's **Settings → General → Site**, add your bundle ID under **Mobile apps**, for example `com.example.app`. App events from IDs that aren't listed are rejected.

2. **Add the package**

   ```swift
   // Xcode: File → Add Package Dependencies…, then https://github.com/Dual-Ninja-LLC/metricraven-swift
   // Or in Package.swift:
   .package(url: "https://github.com/Dual-Ninja-LLC/metricraven-swift", from: "0.2.0")
   // and in your target:
   .product(name: "MetricRaven", package: "metricraven-swift")
   ```

3. **Configure it once at launch**

   ```swift title="MyApp.swift"
   import MetricRaven

   @main
   struct MyApp: App {
       init() {
           // The app ID defaults to your bundle ID; version, build and device are read automatically.
           MetricRaven.configure(siteId: "ana_pub_…")
       }
       var body: some Scene { WindowGroup { ContentView() } }
   }
   ```

4. **Track screens**

   ```swift
   struct SettingsView: View {
       var body: some View {
           Form { /* … */ }
               .onAppear { MetricRaven.screen("Settings") }
       }
   }
   ```

5. **Send events and identify users**

   ```swift
   // A goal, with up to 10 props.
   MetricRaven.track("signup", props: ["plan": "pro", "seats": 3])

   // After sign-in: the same user ID as your server events, server identify and payments.
   MetricRaven.identify(user.id, traits: ["name": user.name, "email": user.email])

   // Verified instead: your server signs the user (signIdentity in @metricraven/node).
   MetricRaven.identify(token: tokenFromYourServer)

   // On sign-out.
   MetricRaven.reset()
   ```

> **Verify it works**
>
> Open the app on a device or simulator. It appears as a live visitor in **Traffic**, with the name you identified it with. Screens are listed under **Pages** as paths like `/Settings`, and your app ID appears under **Hostnames**.

## API

| Call | Notes |
| --- | --- |
| configure(siteId:appId:consent:) | Once at launch. appId defaults to the bundle ID. Returns false for an app ID that isn't a bundle ID. |
| screen(_:props:) | A screen view. Names like "Settings" become the path /Settings. |
| track(_:props:) | A goal. Names: letters, digits, _ : . -, up to 100 characters. Up to 10 props. |
| identify(_:traits:) | Links this device to your user ID, with optional name, email, image (https) and up to 10 custom traits. Self-asserted, so a server identify takes precedence. |
| identify(token:) | Signed identify with a token your server signed. Verified, like server identify; get a fresh token at sign-in and launch. |
| reset() | On sign-out. Forgets identify state and, with consent, starts a new visitor ID. |
| setConsent(_:) | With consent a random visitor ID is kept on the device; without it the server derives a daily one. |
| openedFrom(url:) | utm_\* campaign parameters from a deep link, attached to the next screen view. |
| flush() | Sends what is queued now. The package also flushes when the app enters the foreground or background. |
| MetricRavenPaywall(provider:…) | Paywall views, closes, cancels and taps from RevenueCat, Superwall, Adapty or your own paywall. See Paywall events (/docs/paywall-events). |

Each screen view carries the device's preferred language and the screen size in points. They show under **Language** and **Screen size**. Events and identify calls never carry them.

## One person across the app and your server

Use the same user ID everywhere: [server events](https://metricraven.com/docs/server-events), [server identify](https://metricraven.com/docs/identify-users), payments and the app's `identify`. For a verified profile on the device, have your server sign a token for the signed-in user and call `identify(token:)`: the live map then shows the device as that person, marked verified. An unsigned `identify` is a self-asserted claim and never borrows a verified profile.

## Details

- Events wait in UserDefaults while the device is offline (up to 500, for 7 days) and are delivered in order, with backoff on network errors, rate limits and server errors.
- Without consent nothing is stored on the device. Let people choose in your app and call `setConsent`; consent at launch is `configure(…, consent: true)`.
- Using GA4 or Firebase instead? Connect it through [Google Analytics 4 realtime](https://metricraven.com/docs/search-console#ga4-realtime) to show app users on the live map without this package.
- React Native and Expo apps: use [@metricraven/react-native](https://metricraven.com/docs/react-native).
- Native Android apps: use the [Android (Kotlin) SDK](https://metricraven.com/docs/android-sdk). Flutter apps: [the Flutter package](https://metricraven.com/docs/flutter).
