Installation guides
iOS & Swift
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
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.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")Configure it once at launch
MyApp.swiftimport 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() } } }Track screens
examplestruct SettingsView: View { var body: some View { Form { /* … */ } .onAppear { MetricRaven.screen("Settings") } } }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
| 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, 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 isconfigure(…, 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.