Register a one-shot callback fired when the SDK's background device-registration phase resolves (either RegistrationState.Registered or RegistrationState.Failed).

addNetworkStateChangedListener

@JvmStatic

fun addNetworkStateChangedListener(listener: (TelemetryEvent.NetworkStateChanged) -> Unit): () -> Unit

Subscribe to the networkStateChanged lifecycle event.

addNotificationOpenedListener

@JvmStatic

fun addNotificationOpenedListener(listener: (NotificationOpenedPayload) -> Unit): (NotificationOpenedPayload) -> Unit

addPushLifecycleListener

@JvmStatic

fun addPushLifecycleListener(listener: (PushLifecycleEvent) -> Unit): () -> Unit

Subscribe to push-permission lifecycle events.

addPushNotificationReceivedListener

@JvmStatic

fun addPushNotificationReceivedListener(listener: (PushNotificationReceivedPayload) -> Unit): () -> Unit

Subscribe to the pushNotificationReceived lifecycle event — fires when a data-only FCM message arrives in the FOREGROUND, BEFORE the SDK posts the system notification.

addPushTokenRefreshListener

@JvmStatic

fun addPushTokenRefreshListener(listener: (TelemetryEvent.PushTokenRefreshed) -> Unit): () -> Unit

Subscribe to the pushTokenRefresh lifecycle event — fires on FCM token rotations (FirebaseMessagingService.onNewToken).

addPushTokenRegisteredListener

@JvmStatic

fun addPushTokenRegisteredListener(listener: (TelemetryEvent.PushTokenRegistered) -> Unit): () -> Unit

Subscribe to the pushTokenRegistered lifecycle event.

addPushTokenRegistrationFailedListener

@JvmStatic

fun addPushTokenRegistrationFailedListener(listener: (TelemetryEvent.PushTokenRegistrationFailed) -> Unit): () -> Unit

Subscribe to the pushTokenRegistrationFailed lifecycle event.

addSwanIdentifierChangedListener

@JvmStatic

fun addSwanIdentifierChangedListener(listener: (SwanIdentifierChangedPayload) -> Unit): () -> Unit

Subscribe to identifier-change events fired by identify and logout.

createNotificationChannel

@JvmStatic

@JvmOverloads

fun createNotificationChannel(channelId: String, channelName: String, importance: Int = 4, description: String? = null, soundResName: String? = null): String?

Create a notification channel (Android 8+; no-op on older API levels).

customEvent

@JvmStatic

@JvmOverloads

fun customEvent(name: String, attributes: Map<String, Any?> = emptyMap())

RN-parity alias for track.

deleteNotificationChannel

@JvmStatic

fun deleteNotificationChannel(channelId: String): Boolean

Delete a notification channel (Android 8+; no-op on older API levels).

enableLogs

@JvmStatic

fun enableLogs(enabled: Boolean)

Toggle the SDK's internal debug-log gate at runtime.

enrichProfile

@JvmStatic

fun enrichProfile(attributes: Map<String, Any?>)

Update arbitrary attributes on the user's customer profile.

@JvmStatic

fun enrichProfile(attributes: JsonObject)

Update arbitrary attributes on the user's customer profile using a pre-built JsonObject. Skips the Map<String, Any?> → JsonObject conversion.

flush

@JvmStatic

fun flush()

Force a flush of the pending event queue.

getBadgeCount

@JvmStatic

fun getBadgeCount(): Int

Read the current app-icon badge count.

getCurrentSessionId

@JvmStatic

fun getCurrentSessionId(): String?

Return the current session id, or null if init hasn't been called yet.

getDeviceInfo

@JvmStatic

fun getDeviceInfo(): SwanDeviceInfo?

Snapshot of the SDK's view of the host device.

getFcmToken

@JvmStatic

fun getFcmToken(): String?

Returns the current FCM token, or null if push hasn't been registered yet.

getNotificationChannelId

@JvmStatic

fun getNotificationChannelId(): String

The id of the default Swan notification channel.

getQueueSize

@JvmStatic

fun getQueueSize(): Int

Returns the number of pending events in the durable queue.

getSwanIdentifier

@JvmStatic

fun getSwanIdentifier(): String?

Returns the current Swan identifier — the logged-in CDID if present, else the anonymous generatedCDID, else null if registration hasn't completed yet.

handleDeepLink

@JvmStatic

fun handleDeepLink(url: String?): Boolean

Handle a deep-link URL from an EXTERNAL source — email, SMS, WhatsApp, Universal Links, custom schemes, ad-network click-throughs.

handleFcmDataForTests

@JvmStatic

fun handleFcmDataForTests(context: Context, data: Map<String, String>, transportMessageId: String? = null)

Test / demo entrypoint exposing handleFcmInbound to the sample app and instrumented tests. Behaves identically to a real FCM-dispatched RemoteMessage arriving via SwanMessagingService.onMessageReceived: the template router resolves NotificationTemplate, the appropriate renderer fires, and the notification is posted.

handleNotificationBundle

@JvmStatic

fun handleNotificationBundle(extras: Bundle?)

Cold-start handler — Bundle variant.

handleNotificationIntent

@JvmStatic

fun handleNotificationIntent(intent: Intent?)

Cold-start handler: extract the notification payload from a launch Intent and route it through the SDK.

handleNotificationTap

@JvmStatic

fun handleNotificationTap(data: Map<String, String>)

Deliver a notification tap to the SDK.

hasNotificationPermission

@JvmStatic

fun hasNotificationPermission(): Boolean

Check the current OS notification-permission state.

identify

@JvmStatic

@JvmOverloads

fun identify(identifier: String, attributes: Map<String, Any?> = emptyMap())

Assert external user identity.

init

@JvmStatic

fun init(context: Context, appId: String)

Initialize the SDK with the default SwanConfig (production backend, debug logs off).

@JvmStatic

fun init(context: Context, appId: String, config: SwanConfig)

Initialize the SDK.

isLocationEnabled

@JvmStatic

fun isLocationEnabled(): Boolean

Snapshot read — is location tracking enabled in the SwanConfig?

isPushEnabled

@JvmStatic

fun isPushEnabled(): Boolean

Snapshot read — is push enabled in the SwanConfig passed to init?

isPushReady

@JvmStatic

fun isPushReady(): Boolean

Snapshot read of the push subsystem state.

isReady

@JvmStatic

fun isReady(): Boolean

Snapshot read — is the SDK fully initialized and ready to track / send?

suspend fun login(identifier: String, attributes: Map<String, Any?> = emptyMap()): LoginResult

Log a user in — typed, suspending RN-parity surface.

logout

@JvmStatic

fun logout()

Log the user out, revert to the anonymous profile, and clear the cached identifier.

registerFcmToken

@JvmStatic

fun registerFcmToken(token: String)

removeDeepLinkOpenedListener

@JvmStatic

fun removeDeepLinkOpenedListener(listener: (DeepLinkOpenedPayload) -> Unit)

Unregister a previously-registered DEEP_LINK_OPENED listener.

removeNotificationOpenedListener

@JvmStatic

fun removeNotificationOpenedListener(listener: (NotificationOpenedPayload) -> Unit)

Unregister a previously-registered NOTIFICATION_OPENED listener.

requestFcmToken

suspend fun requestFcmToken(): Result<String?>

Fetch the FCM token via the host's Firebase Messaging SDK and register it with Swan.

requestNotificationPermission

suspend fun requestNotificationPermission(): Boolean

Prompt the user for notification permission.

screen

@JvmStatic

@JvmOverloads

fun screen(name: String, attributes: Map<String, Any?> = emptyMap())

Track a manual screen-view event.

setBadgeCount

@JvmStatic

fun setBadgeCount(count: Int): Boolean

Set the app-icon badge count.

setBusinessUnit

@JvmStatic

fun setBusinessUnit(businessUnit: String)

Set the businessUnit super-property.

setCountry

@JvmStatic

fun setCountry(country: String)

Set the country super-property. Auto-enriched onto every subsequent event's data.country.

setCurrency

@JvmStatic

fun setCurrency(currency: String)

Set the currency super-property.

setCurrentActivity

@JvmStatic

fun setCurrentActivity(activity: Activity?)

Register the host Activity backing the notification-permission OS dialog. Call from onResume(); pass null from onDestroy() if you want to be explicit (the SDK uses a java.lang.ref.WeakReference internally so it never prevents the Activity from being GC'd).