Skip to main content
sdk

Native SDK (KMP → Android & iOS)

active
Audience: developerUpdated 2026-08-02

The Binoban Native SDK is a single Kotlin Multiplatform (KMP) core, compiled and shipped as two outputs: an Android library (via Maven Central) and an iOS framework (via Swift Package Manager or CocoaPods, distributed as an XCFramework). Both platforms share the same tracking model, configuration, and method names — so the concepts on this page apply to both, and the platform pages cover the install and language specifics.

apiHost is required

The Native SDK does not ship with a built-in default host, on either platform. You always set apiHost explicitly — your cloud host, or your own deployment's host for on-prem and air-gapped installs. If it is blank, the SDK initializes in a disabled (no-op) state and sends nothing.

Pick your platform​

  • Android SDK — Gradle install, Application setup, and Android lifecycle/push specifics.
  • iOS SDK — Swift Package Manager (or CocoaPods) install and Swift setup.
  • React Native bridge — a thin wrapper over these native outputs (not a standalone SDK).

New to the Native SDK? Start with the Native SDK quickstart — Android · iOS — for the fastest path to a first event, then return here for the full surface.

Shared concepts​

These hold on both Android and iOS:

  • Credentials. Construct the client with apiKey and sourceIdentifier from your workspace, plus the required apiHost.
  • Identity. The SDK assigns an anonymousId automatically and persists it. You set a userId with identify; when collectDeviceId is enabled the SDK also tracks a deviceId. See Identity strategy.
  • Batching & flush. Events are queued and sent in batches — by default after flushAt events (20) or every flushInterval seconds (30). Call flush() to send immediately.
  • Lifecycle. The SDK auto-tracks application lifecycle events (trackApplicationLifecycleEvents).
  • Deep links. Android can track the links that launch your app, but this is opt-in: add AndroidDeepLinkPlugin yourself. See deep-link tracking. Not available on iOS or React Native.
  • Push. Both platforms receive Engage push through Firebase Cloud Messaging. The SDK displays the notification and reports delivery, clicks, and dismissals; your app forwards the incoming message to it. The platform entry points differ — see App push.

Method surface​

The KMP core exposes these tracking methods to consumers:

MethodPurpose
identify(userId, traits)Associate the current person with your user ID and traits.
track(name, properties)Record an action the user took.
screen(title, properties)Record a screen view. Arrives as a track named screen.
flush()Send queued events immediately.
reset()Clear userId/traits and start a new anonymousId (call on logout).
anonymousId() / userId() / deviceId() / traits()Read the current identity.
enabledPause/resume all tracking.
setDeviceToken(token)Register the FCM push token through a live instance, and stamp it on later events.
Notification.refreshToken(token)Register the FCM push token with no live instance required — the background/cold-start path.
Notification.initialize(config)Configure the notification layer (icon and channel on Android; permission and sound on iOS).
Notification.notify(data)Display an incoming Binoban push. Non-Binoban payloads are ignored.

Exact argument shapes are language-specific — see the Android and iOS pages.

On iOS the notification entry points are not methods on your Binoban instance — call them on BinobanNotifications.shared (initializeNotifications, onNewToken, onApplicationDidReceiveRemoteNotification, onWillPresentForwarded, onDidReceiveForwarded). See the iOS SDK page.

How a screen reaches the backend

The tracking API has no screen event type, so a screen view travels as a track named screen, with the screen's own title copied into properties.name. The SDK does that rewrite for you — you just call screen(). The Web SDK behaves identically, so a screen from a browser and a screen from an app land in the same shape.

group() and alias() remain internal: the backend does not accept them yet.

Distribution​

  • Android — Maven Central: io.binoban.sdk:sdk-android.
  • iOS — Swift Package Manager (primary) or CocoaPods (pod 'binoban'), distributed as an XCFramework binary.

Check the SDK compatibility matrix for the current version and per-platform status.