Installation guides

iOS & Swift

On this page

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

    example
    // 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

    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

    example
    struct SettingsView: View {
        var body: some View {
            Form { /* … */ }
                .onAppear { MetricRaven.screen("Settings") }
        }
    }
  5. Send events and identify users

    example
    // 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

CallNotes
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, server identify, 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 to show app users on the live map without this package.
  • React Native and Expo apps: use @metricraven/react-native.
  • Native Android apps: use the Android (Kotlin) SDK. Flutter apps: the Flutter package.