React Native SDK

The React Native TurboModule bridge (@binoban/react-native) over the Binoban Native SDK's Android and iOS outputs — the exhaustive configuration and method reference. It is not an independent implementation: every call crosses the bridge into native code (Android via io.binoban.sdk:sdk-android, iOS via the binoban XCFramework), so its behavior — identity, batching, the apiHost requirement — matches the native platforms.

For installing the package, initializing the bridge (createClient + BinobanProvider + useBinoban), and sending a first event, start with the Track from React Native tutorial. The underlying native initialization this bridge wraps is documented on the Native SDK tutorials — Android · iOS.

Requirements: react >= 18, react-native >= 0.71, New Architecture (TurboModules) — on the old architecture the native module resolves to null and the SDK is an inert no-op; Android minSdk 24+; iOS per React Native's min_ios_version_supported. Check the compatibility matrix for the current version and publish status.

Config options

Option	Default	Purpose
credentials.android / credentials.iOS	—	Required. { apiKey, sourceIdentifier } per platform. Android and iOS credentials are independent — you can point them at different sources if your setup requires it, though most integrations use the same sourceIdentifier on both.
apiHost	'' (required)	API endpoint. Blank leaves the client inert — no default, no cloud fallback.
debug	false	Verbose native logging.
collectDeviceId	true	Collect a device identifier.
trackAppLifecycleEvents	true	Auto-track app open/close/update.
useLifecycleObserver	true	Hook into the app lifecycle observer.
trackDeepLinks	true	Passed through to the native layer, where deep-link tracking requires a plugin the React Native bridge does not register. No deep-link events are emitted through React Native today.
flushAt	20	Send after this many queued events.
flushInterval	30	…or after this many seconds.
autoAddSegmentDestination	true	Internal batching destination toggle.
disableTelemetry	false	Disable SDK-health telemetry.
telemetryHost	''	Telemetry endpoint, if enabled.
uploadMaxRetries	3	Upload retry ceiling.
backoffBaseMillis	1000	Retry backoff base.
backoffFactor	2.0	Retry backoff multiplier.
backoffMaxMillis	60000	Retry backoff ceiling.
maxFilesPerFlush	20	Batched files per flush.

An optional onError(e) callback on createClient's config surfaces JS and native failures; native errors set e.method to "native" or "native:<ClassName>".

Method reference

Method	Signature	Notes
track	(event: string, properties?: JsonMap) => void	Record an action.
identify	(userId: string, userTraits?: UserTraits) => void	Associate the current person with your user ID and traits.
flush	() => void	Send queued events immediately.
reset	() => void	Clear identity and start a new anonymousId — call on logout.
anonymousId	() => string | undefined	Read the current anonymous ID.
userId	() => string | undefined	Read the current user ID, if identified.
deviceId	() => string | undefined	Read the device ID, when collectDeviceId is on.
notify	(payloadData: JsonMap) => void	Trigger a local notification.
setDeviceToken	(token: string) => void	Register a push token.
onNotificationInteraction	(listener) => { remove(): void }	Subscribe to push interaction events.
getInitialNotificationInteraction	() => Promise<NotificationInteraction | null>	The interaction that cold-started the app, if any.
didReceiveNotificationResponse / willPresentNotification / didReceiveRemoteNotification	iOS host-forwarding calls	No-ops on Android.

screen, group, alias are not exposed

The underlying Native SDK marks screen(), group(), and alias() as internal on both Android and iOS, so the React Native bridge does not expose them either. This mirrors the native platforms — it is not an RN-specific gap.

Push notifications

The bridge exposes the native push surface through a single JS API. For the step-by-step integration see App push in React Native.

Android configuration

Unlike native Android, the bridge does not take a configuration object — it reads the notification icon and channel from AndroidManifest.xml meta-data when the first push arrives:

Meta-data key	Default
io.binoban.sdk.reactNative.default_notification_icon	Your app icon.
io.binoban.sdk.reactNative.push_channel_id	DEFAULT_NOTIFICATION_CHANNEL_ID
io.binoban.sdk.reactNative.push_channel_name	General
io.binoban.sdk.reactNative.push_channel_description	Empty.

The channel is created at IMPORTANCE_HIGH; an existing channel with that id is reused unchanged. POST_NOTIFICATIONS is still your app's to declare and request on Android 13+.

notify(payloadData)

Hand a received data message to the SDK to be displayed and tracked. Payloads whose source is not "binoban" are ignored, so it is safe to call for every message your push library delivers. On iOS, forwarding through didReceiveRemoteNotification does the same job.

Interactions

{
  notificationUuid: string;
  type: 'DELIVERED' | 'CLICKED' | 'CLOSED' | 'FAILED' | 'OPENED';
  actionId?: string;
  uri?: string;
  customData?: Record<string, string>;
  reason?: string;
}

onNotificationInteraction(listener) returns a subscription — call remove() to stop listening. getInitialNotificationInteraction() returns the tap that cold-started the app, if any, and is consumed once: call it at startup, since a launching tap is delivered before JS has had a chance to subscribe.

The bridge extends the SDK's default handler, so Binoban's own delivery and click tracking continues regardless of what your listener does.

iOS does not open uri itself — read it from the interaction and route it.

Platform wiring

	What you do
Android	Nothing extra. The SDK's notification trampoline delivers interactions to JS once you subscribe.
iOS	The SDK registers no UNUserNotificationCenterDelegate, so the host must forward. Either call didReceiveNotificationResponse / willPresentNotification / didReceiveRemoteNotification from JS, or forward from a native AppDelegate to the SDK's Swift functions — the bridge emits to JS either way. The three JS methods are no-ops on Android.

See Push events for what all of this emits.

Next steps

• Example Apps — binoban-example-react-native is a runnable integration of this surface.
• Native SDK overview — shared concepts across Android, iOS, and this bridge.
• Identity strategy — anonymousId/userId/deviceId across platforms.
• Go-live checklist