Install the Userorbit SDK in an iOS app

Add the Userorbit SDK to your iOS app with Swift Package Manager, call setup once at launch, and identify people after they sign in. When you're done, Userorbit receives your app's events and screens, and surveys created in Userorbit can appear in the app.

Before you begin

You need:

an app that targets iOS 15 or later, built with Xcode and Swift 5.9 or later
the public Account ID from the install snippet in Settings → Channels → Widget
a stable user ID from your own system for signed-in people

The Account ID is safe to ship in your app. Keep API keys and signing secrets on your server.

1. Add the package

In Xcode, choose File → Add Package Dependencies, enter https://github.com/userorbit/userorbit-ios, and add the Userorbit product to your app target.

If you manage dependencies in a Package.swift file, add:

dependencies: [
    .package(url: "https://github.com/userorbit/userorbit-ios", from: "0.1.0"),
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [.product(name: "Userorbit", package: "userorbit-ios")]
    ),
]
swift

The package includes a privacy manifest (PrivacyInfo.xcprivacy), so Xcode adds Userorbit's data declarations to your app's privacy report. See What the Userorbit mobile SDKs store and send for what it declares.

2. Set up the SDK at launch

Call setup once, as early as possible. In a SwiftUI app, use the App initializer:

import SwiftUI
import Userorbit

@main
struct AcmeApp: App {
    init() {
        Userorbit.shared.setup(UserorbitConfig(accountId: "YOUR_ACCOUNT_ID"))
    }

    var body: some Scene {
        WindowGroup { ContentView() }
    }
}
swift

In a UIKit app, call the same line in application(_:didFinishLaunchingWithOptions:). Replace YOUR_ACCOUNT_ID with the Account ID from your workspace.

Setup starts session tracking and records Application Installed, Application Updated, Application Opened and Application Backgrounded. To turn lifecycle events off, pass captureApplicationLifecycleEvents: false.

3. Track screens and events

Call screen when a screen appears. Screen views send $uo_screen_view, which is also the event Userorbit uses to confirm your installation.

struct ProjectsView: View {
    var body: some View {
        List { /* ... */ }
            .onAppear { Userorbit.shared.screen("Projects") }
    }
}
swift

Track product events after the action succeeds:

Userorbit.shared.track("Project Created", properties: ["template": "blank"])
swift

Event names are case-sensitive. A survey that triggers on Project Created won't respond to project_created.

4. Identify signed-in people

Call identify after your app knows who is signed in. Use an immutable ID from your system, not an email address.

Userorbit.shared.identify(
    user.id,
    email: user.email,
    name: user.name,
    attributes: ["plan": user.plan, "role": user.role]
)
swift

Identifying links the person's earlier anonymous events to their profile and creates or updates their contact in Userorbit. Send email and name only when your privacy basis allows it.

To update attributes later, call setUserProperties or unsetUserProperties. These only work after identify. To attach a property to every event from this device, call register, and remove it with unregister.

5. Reset on sign-out

Call reset from your sign-out path:

Userorbit.shared.reset()
swift

Reset starts a new anonymous identity, ends the session, clears registered properties and forgets the person's support conversations on this device. Without it, the next person who signs in on the same device inherits the previous person's identity.

6. Verify the installation

Run the app and open a screen that calls screen.
Send the app to the background, or call Userorbit.shared.flush(). Events are otherwise sent every 30 seconds or once 20 are queued.
In Userorbit, open Settings → Channels → Widget. Select Check again if needed. The verification step shows SDK activity detected and the time of the last SDK activity.
Open Live Events and confirm the $uo_screen_view event shows the expected screen name and user.

If nothing arrives, set debug: true in UserorbitConfig and watch the Xcode console. Messages use the subsystem com.userorbit.sdk. See Troubleshoot the Userorbit mobile SDKs for common causes.

Configuration options

Option	Default	Purpose
`accountId`	Required	Your workspace's public Account ID.
`apiHost`	`https://api.userorbit.com`	Change only if your workspace uses a different API host.
`flushAt`	20	Number of queued events that triggers a send.
`flushIntervalSeconds`	30	How often queued events are sent.
`maxBatchSize`	50	Maximum events per request.
`maxQueueSize`	1000	Maximum stored events. The oldest are dropped beyond this.
`captureApplicationLifecycleEvents`	`true`	Records install, update, open and background events.
`surveys`	`true`	Set to `false` to stop surveys from loading.
`optOut`	`false`	Start opted out until the person gives consent.
`debug`	`false`	Logs SDK activity to the console.
`storageDirectory`	Application Support	Where the queue and state are stored.
`beforeSend`	None	Edit an event, or return `nil` to drop it, before it's queued.