Track from iOS

This tutorial gets the Binoban Native SDK sending its first identify and track events from an iOS app. The SDK is one Kotlin Multiplatform core; this page covers the iOS output of that core.

Before you begin

You need:

• An iOS app you can build, targeting iOS 12.0+ with Xcode 15.0+ / Swift tools 5.9.
• Your Binoban source credentials — apiKey and sourceIdentifier — and your apiHost, all from your Binoban workspace. (New to credentials? See the Quick Start.)

apiHost is required

Unlike the Web SDK, the Native SDK needs an explicit apiHost — there is no default on iOS. If it is blank, the SDK initializes in a disabled (no-op) state and sends nothing. For on-prem or air-gapped deployments, use your own deployment's host.

Step 1 — Add the dependency

In Xcode: File → Add Package Dependencies…, then enter:

https://github.com/binoban/binoban-sdk-swift

Select Up to Next Major Version, starting at 1.0.0, and add the binoban product to your app target.

CocoaPods is also supported as an alternative distribution path — see the iOS SDK reference for that install. Opening the generated .xcworkspace (instead of .xcodeproj) applies only to the CocoaPods path; Swift Package Manager needs no such step.

Use the current version

1.0.0 is shown for concreteness. Check the SDK compatibility matrix for the current version and platform status.

Step 2 — Initialize the SDK

Create the client once, in application(_:didFinishLaunchingWithOptions:), and keep a reference to it.

import SwiftUI
import binoban

class AppDelegate: NSObject, UIApplicationDelegate {
    var binoban: Binoban!

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
    ) -> Bool {
        binoban = BinobanFactory.shared.create(
            apiKey: "YOUR_API_KEY",
            sourceIdentifier: "YOUR_SOURCE_IDENTIFIER"
        ) { config in
            config.application = UIApplication.shared
            config.apiHost = "YOUR_API_HOST"   // required — no default on iOS
        }
        return true
    }
}

The SDK generates and persists an anonymous ID at this point, so it can attribute activity even before a user signs in.

Step 3 — Identify the current user

When the user signs in, call identify with your own user ID and any traits:

binoban.identify(
    userId: "user_123",
    traits: ["name": "Jane Doe", "email": "jane@example.com"]
)

Step 4 — Track an action

track records something the user did — its first argument is the event name, its second a properties object:

binoban.track(name: "signed_up", properties: ["plan": "Enterprise"])

Step 5 — Flush and verify

The SDK batches events and sends them automatically (every flushAt events or flushInterval seconds — 20 events / 30s by default). To send immediately during testing, flush by hand:

binoban.flush()

Then confirm delivery: watch your app's network traffic for a POST to …/api/tracker/sdk/ios returning 200. Unlike the Tracking REST API, the SDK-facing endpoint has no {sourceIdentifier} path segment or /track suffix — every platform's SDK posts its batch to one fixed per-platform path, and the apiKey on the Bearer header identifies the source. A 401 means the apiKey is wrong; a connection failure points at the apiHost. As with the Web SDK, a 200 means Binoban accepted the event — it then resolves into your source's profiles in the workspace.

What you've done

You added the SDK, initialized it with the required apiHost, identified a user, tracked an action, and verified delivery — the full iOS tracking loop.

Next steps

• See a working example → binoban-example-ios, a minimal SwiftUI app wiring up everything above plus opt-in push. See Example Apps for all three platforms.
• Full method surface and configuration → the iOS SDK reference — every method signature, the configuration options table, identity reads, and runtime controls.
• Register push tokens → App push on iOS covers the APNs (iOS) and FCM (Android) registration steps.
• Android instead? See the Android tutorial.
• React Native? The React Native SDK wraps these same native outputs (screen/group/alias are internal on every platform — not an RN-specific gap).
• Model identity well across platforms → Identity strategy, including deviceId and multi-device behavior.
• Before production → the Go-live checklist.