zixflow-reactnative 1.1.3 → 1.1.4

package/android/build.gradle

@@ -10,11 +10,14 @@ buildscript {
   dependencies {
     // noinspection DifferentKotlinGradleVersion
     classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    // Compose compiler plugin (Kotlin 2.x) for hosting the Visual Notification Inbox composables.
+    classpath "org.jetbrains.kotlin:compose-compiler-gradle-plugin:$kotlin_version"
   }
 }
 
 apply plugin: 'com.android.library'
 apply plugin: 'kotlin-android'
+apply plugin: 'org.jetbrains.kotlin.plugin.compose'
 apply plugin: "com.facebook.react"
 
 def getExtOrDefault(name) {
@@ -26,6 +29,7 @@ def getExtOrIntegerDefault(name) {
 }
 
 ext.zixflowLocationEnabled = rootProject.findProperty("zixflow_location_enabled")?.toBoolean() ?: false
+ext.zixflowGeofenceEnabled = rootProject.findProperty("zixflow_geofence_enabled")?.toBoolean() ?: false
 
 android {
   namespace = 'com.zixflow.reactnative.sdk'
@@ -33,12 +37,17 @@ android {
   defaultConfig {
     minSdkVersion getExtOrIntegerDefault('minSdkVersion')
     targetSdkVersion getExtOrIntegerDefault('targetSdkVersion')
-    buildConfigField "boolean", "ZIXFLOW_LOCATION_ENABLED", "${project.zixflowLocationEnabled}"
+    // Geofence implies Location, so the Location flag is on whenever geofence is enabled
+    // (mirrors the iOS geofence subspec, which also defines ZIXFLOW_LOCATION_ENABLED).
+    buildConfigField "boolean", "ZIXFLOW_LOCATION_ENABLED", "${project.zixflowLocationEnabled || project.zixflowGeofenceEnabled}"
+    buildConfigField "boolean", "ZIXFLOW_GEOFENCE_ENABLED", "${project.zixflowGeofenceEnabled}"
     consumerProguardFiles 'consumer-rules.pro'
   }
 
   buildFeatures {
     buildConfig true
+    // Required to host the Visual Notification Inbox Compose UI components.
+    compose true
   }
 
   buildTypes {
@@ -144,4 +153,12 @@ dependencies {
   // noinspection GradleDynamicVersion
   api 'com.facebook.react:react-native:+'
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+
+  // Jetpack Compose — needed because the Visual Notification Inbox view managers host
+  // the native `@Composable` inbox components inside a ComposeView.
+  def composeBom = platform('androidx.compose:compose-bom:2025.10.00')
+  implementation composeBom
+  implementation 'androidx.compose.ui:ui'
+  implementation 'androidx.compose.foundation:foundation'
+  implementation 'androidx.compose.runtime:runtime'
 }

package/android/consumer-rules.pro

@@ -1,3 +1,4 @@
-# Location module is an optional compileOnly dependency.
-# When not enabled, R8 must not fail on missing location classes.
+# Location and geofence modules are optional compileOnly dependencies.
+# When not enabled, R8 must not fail on their missing classes.
 -dontwarn io.customer.location.**
+-dontwarn io.customer.geofence.**

package/android/gradle.properties

@@ -2,4 +2,4 @@ zixflow.reactnative.kotlinVersion=2.1.20
 zixflow.reactnative.compileSdkVersion=36
 zixflow.reactnative.targetSdkVersion=36
 zixflow.reactnative.minSdkVersion=21
-zixflow.reactnative.sdkVersionAndroid=1.1.3
+zixflow.reactnative.sdkVersionAndroid=4.23.2

package/android/src/main/java/com/zixflow/reactnative/sdk/NativeZixflowModule.kt

@@ -101,11 +101,14 @@ class NativeZixflowModule(
                     cdnHost(it)
                 }
 
-                // Configure push messaging module based on config provided by customer app
+                // Configure push messaging module based on config provided by customer app.
+                // Live Activities are hosted by the FCM push module, so the `liveNotifications`
+                // config is applied to the same module.
                 packageConfig.getTypedValue<Map<String, Any>>(key = "push").let { pushConfig ->
                     NativeMessagingPushModule.addNativeModuleFromConfig(
                         builder = this,
-                        config = pushConfig ?: emptyMap()
+                        config = pushConfig ?: emptyMap(),
+                        liveNotificationsConfig = packageConfig.getTypedValue<Map<String, Any>>(key = "liveNotifications")
                     )
                 }
                 packageConfig.getTypedValue<Map<String, Any>>(key = "inApp")?.let { inAppConfig ->
@@ -114,12 +117,28 @@ class NativeZixflowModule(
                         config = inAppConfig
                     )
                 }
-                // Configure location module if enabled via gradle property
+                // Configure location module. Geofence implies location, so register location
+                // (with the app's config if given, otherwise defaults) whenever location or
+                // geofence is enabled, since geofence relies on the location module's fixes.
+                // ZIXFLOW_LOCATION_ENABLED is already true for geofence-enabled builds.
                 if (BuildConfig.ZIXFLOW_LOCATION_ENABLED) {
-                    packageConfig.getTypedValue<Map<String, Any>>(key = "location")?.let { locationConfig ->
+                    val locationConfig = packageConfig.getTypedValue<Map<String, Any>>(key = "location")
+                    val geofenceConfigured = BuildConfig.ZIXFLOW_GEOFENCE_ENABLED &&
+                        packageConfig.getTypedValue<Map<String, Any>>(key = "geofence") != null
+                    if (locationConfig != null || geofenceConfigured) {
                         NativeLocationModule.addNativeModuleFromConfig(
                             builder = this,
-                            config = locationConfig
+                            config = locationConfig ?: emptyMap()
+                        )
+                    }
+                }
+                // Configure geofence module if enabled via gradle property; it runs
+                // automatically once registered and relies on the location module above.
+                if (BuildConfig.ZIXFLOW_GEOFENCE_ENABLED) {
+                    packageConfig.getTypedValue<Map<String, Any>>(key = "geofence")?.let { geofenceConfig ->
+                        NativeGeofenceModule.addNativeModuleFromConfig(
+                            builder = this,
+                            config = geofenceConfig
                         )
                     }
                 }
@@ -133,6 +152,22 @@ class NativeZixflowModule(
         }
     }
 
+    override fun setDeepLinkRoutingReady() {
+        // UIScene and React Native Linking readiness are iOS-only concerns.
+    }
+
+    override fun registerDeepLinkHandler() {
+        // UIScene deep-link acknowledgement is an iOS-only concern.
+    }
+
+    override fun unregisterDeepLinkHandler() {
+        // UIScene deep-link acknowledgement is an iOS-only concern.
+    }
+
+    override fun acknowledgeDeepLink(id: String?, handled: Boolean) {
+        // UIScene deep-link acknowledgement is an iOS-only concern.
+    }
+
     override fun identify(params: ReadableMap?) {
         val userId = params?.getString("userId")
         val traits = params?.getMap("traits")

package/android/src/main/java/com/zixflow/reactnative/sdk/ZixflowReactNativePackage.kt

@@ -6,10 +6,14 @@ import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.module.model.ReactModuleInfo
 import com.facebook.react.module.model.ReactModuleInfoProvider
 import com.facebook.react.uimanager.ViewManager
+import com.zixflow.reactnative.sdk.geofence.NativeGeofenceModule
+import com.zixflow.reactnative.sdk.liveactivities.NativeLiveActivitiesModule
 import com.zixflow.reactnative.sdk.location.NativeLocationModule
 import com.zixflow.reactnative.sdk.logging.NativeZixflowLoggingModule
 import com.zixflow.reactnative.sdk.messaginginapp.InlineInAppMessageViewManager
 import com.zixflow.reactnative.sdk.messaginginapp.NativeMessagingInAppModule
+import com.zixflow.reactnative.sdk.messaginginbox.NotificationInboxBellViewManager
+import com.zixflow.reactnative.sdk.messaginginbox.NotificationInboxViewManager
 import com.zixflow.reactnative.sdk.messagingpush.NativeMessagingPushModule
 import com.zixflow.reactnative.sdk.util.assertNotNull
 
@@ -22,7 +26,11 @@ class ZixflowReactNativePackage : BaseReactPackage() {
      * Creates the list of view managers for the Zixflow React Native SDK.
      */
     override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
-        return listOf(InlineInAppMessageViewManager())
+        return listOf(
+            InlineInAppMessageViewManager(),
+            NotificationInboxBellViewManager(),
+            NotificationInboxViewManager()
+        )
     }
 
     override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
@@ -31,11 +39,23 @@ class ZixflowReactNativePackage : BaseReactPackage() {
         // See: https://reactnative.dev/docs/fabric-native-components-introduction?platforms=android#4-write-the-reactwebviewpackage
         return when (name) {
             InlineInAppMessageViewManager.NAME -> InlineInAppMessageViewManager()
+            NotificationInboxBellViewManager.NAME -> NotificationInboxBellViewManager()
+            NotificationInboxViewManager.NAME -> NotificationInboxViewManager()
             NativeZixflowLoggingModule.NAME -> NativeZixflowLoggingModule(reactContext)
             NativeZixflowModule.NAME -> NativeZixflowModule(reactContext = reactContext)
+            // Unconditional on purpose, unlike Location below. Location has its own artifact
+            // (com.zixflow.android:location) that the flag switches between `api` and `compileOnly`,
+            // so gating it genuinely keeps a dependency off the consumer's classpath. Live
+            // Notifications ship inside messaging-push-fcm, already a hard dependency here, so a flag
+            // would remove nothing — and the module is inert until `liveNotifications` config enables
+            // a type. iOS gates its equivalent only because the subspec pulls in extra pods.
+            NativeLiveActivitiesModule.NAME -> NativeLiveActivitiesModule(reactContext)
             NativeLocationModule.NAME -> if (BuildConfig.ZIXFLOW_LOCATION_ENABLED) {
                 NativeLocationModule(reactContext)
             } else null
+            NativeGeofenceModule.NAME -> if (BuildConfig.ZIXFLOW_GEOFENCE_ENABLED) {
+                NativeGeofenceModule(reactContext)
+            } else null
             NativeMessagingInAppModule.NAME -> NativeMessagingInAppModule(reactContext)
             NativeMessagingPushModule.NAME -> NativeMessagingPushModule(reactContext)
             else -> assertNotNull<NativeModule>(value = null) { "Unknown module name: $name" }
@@ -69,9 +89,13 @@ class ZixflowReactNativePackage : BaseReactPackage() {
         // doesn't crash at import time. getModule() returns null when disabled.
         val moduleNames: List<String> = listOf(
             InlineInAppMessageViewManager.NAME,
+            NotificationInboxBellViewManager.NAME,
+            NotificationInboxViewManager.NAME,
             NativeZixflowLoggingModule.NAME,
             NativeZixflowModule.NAME,
+            NativeLiveActivitiesModule.NAME,
             NativeLocationModule.NAME,
+            NativeGeofenceModule.NAME,
             NativeMessagingInAppModule.NAME,
             NativeMessagingPushModule.NAME,
         )

package/android/src/main/java/com/zixflow/reactnative/sdk/constant/Keys.kt

@@ -12,6 +12,25 @@ internal object Keys {
         const val SCREEN_VIEW_USE = "screenViewUse"
         const val API_HOST = "apiHost"
         const val CDN_HOST = "cdnHost"
+        const val NOTIFICATION_INBOX_ACCESSIBILITY_LABELS = "notificationInboxAccessibilityLabels"
+        const val COLOR_SCHEME = "colorScheme"
+        // Push messaging
         const val PUSH_CLICK_BEHAVIOR = "pushClickBehavior"
     }
+
+    /**
+     * Keys of the `notificationInboxAccessibilityLabels` sub-map.
+     *
+     * [BELL_WITH_UNREAD_COUNT] carries a template string containing [COUNT_PLACEHOLDER] rather than
+     * a callback, because wrapper configuration crosses a bridge that carries data but not
+     * functions. The native SDK takes a `(Int) -> String`, so the template is converted to one when
+     * the module is configured.
+     */
+    object InboxAccessibilityLabels {
+        const val BELL = "bell"
+        const val BELL_WITH_UNREAD_COUNT = "bellWithUnreadCount"
+        const val LOADING_INDICATOR = "loadingIndicator"
+        const val EMPTY_STATE = "emptyState"
+        const val COUNT_PLACEHOLDER = "{count}"
+    }
 }

package/android/src/main/java/com/zixflow/reactnative/sdk/geofence/NativeGeofenceModule.kt

@@ -0,0 +1,65 @@
+package com.zixflow.reactnative.sdk.geofence
+
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.annotations.ReactModule
+import com.zixflow.geofence.GeofenceLocationMode
+import com.zixflow.geofence.GeofenceModuleConfig
+import com.zixflow.geofence.ModuleGeofence
+import com.zixflow.reactnative.sdk.NativeZixflowGeofenceSpec
+import com.zixflow.reactnative.sdk.extension.getTypedValue
+import com.zixflow.sdk.ZixflowBuilder
+import com.zixflow.sdk.core.di.SDKComponent
+import com.zixflow.sdk.core.util.Logger
+
+/**
+ * React Native module implementation for Zixflow Geofence Native SDK
+ * using TurboModules with new architecture.
+ *
+ * The reference to [ModuleGeofence] is isolated in this file so the geofence dependency is
+ * only loaded when the module is enabled and bundled. Geofence depends on the location
+ * module, which the caller registers alongside it.
+ */
+@ReactModule(name = NativeGeofenceModule.NAME)
+class NativeGeofenceModule(
+    private val reactContext: ReactApplicationContext,
+) : NativeZixflowGeofenceSpec(reactContext) {
+    private val logger: Logger
+        get() = SDKComponent.logger
+
+    private fun getModuleGeofence() = runCatching {
+        ModuleGeofence.instance()
+    }.onFailure {
+        logger.error("Geofence module is not initialized. Ensure geofence config is provided during SDK initialization.")
+    }.getOrNull()
+
+    override fun refreshFromCurrentLocation() {
+        getModuleGeofence()?.refreshFromCurrentLocation()
+    }
+
+    companion object {
+        const val NAME = "NativeZixflowGeofence"
+
+        /**
+         * Adds the geofence module to the native Android SDK based on the configuration
+         * provided by the customer app.
+         *
+         * @param builder instance of ZixflowBuilder to add the geofence module.
+         * @param config configuration provided by the customer app for the geofence module.
+         */
+        internal fun addNativeModuleFromConfig(
+            builder: ZixflowBuilder,
+            config: Map<String, Any>
+        ) {
+            val locationModeValue = config.getTypedValue<String>("locationMode")
+            // Uppercase before matching so casing can't diverge from iOS (which uppercases too);
+            // enumValueOf is case-sensitive. Unknown values fall back to the SDK default.
+            val locationMode = locationModeValue?.let { value ->
+                runCatching { enumValueOf<GeofenceLocationMode>(value.uppercase()) }.getOrNull()
+            }
+
+            val configBuilder = GeofenceModuleConfig.Builder()
+            locationMode?.let { configBuilder.setLocationMode(it) }
+            builder.addZixflowModule(ModuleGeofence(configBuilder.build()))
+        }
+    }
+}

package/android/src/main/java/com/zixflow/reactnative/sdk/liveactivities/NativeLiveActivitiesModule.kt

@@ -0,0 +1,310 @@
+package com.zixflow.reactnative.sdk.liveactivities
+
+import android.graphics.Color
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.module.annotations.ReactModule
+import com.zixflow.messagingpush.MessagingPushModuleConfig
+import com.zixflow.messagingpush.ModuleMessagingPushFCM
+import com.zixflow.messagingpush.data.communication.ZixflowLiveNotificationsCallback
+import com.zixflow.messagingpush.di.pushModuleConfig
+import com.zixflow.messagingpush.livenotification.LiveNotificationAsset
+import com.zixflow.messagingpush.livenotification.LiveNotificationBranding
+import com.zixflow.messagingpush.livenotification.LiveNotificationData
+import com.zixflow.messagingpush.livenotification.LiveNotificationType
+import com.zixflow.reactnative.sdk.NativeZixflowLiveActivitiesSpec
+import com.zixflow.reactnative.sdk.extension.getTypedValue
+import com.zixflow.sdk.core.di.SDKComponent
+import com.zixflow.sdk.core.util.Logger
+
+/**
+ * React Native module implementation for Zixflow Live Activities / Live Notifications
+ * using TurboModules with new architecture.
+ *
+ * Live Notifications live on the FCM push module ([ModuleMessagingPushFCM]); this bridge
+ * maps the wrapper's template payloads to [LiveNotificationData] and forwards them.
+ */
+@ReactModule(name = NativeLiveActivitiesModule.NAME)
+class NativeLiveActivitiesModule(
+    private val reactContext: ReactApplicationContext,
+) : NativeZixflowLiveActivitiesSpec(reactContext) {
+    private val logger: Logger
+        get() = SDKComponent.logger
+
+    // Live Notifications are hosted by the FCM push module. Reach it via the module registry
+    // (the wrapper can't reference the SDK-internal MODULE_NAME constant, so use the literal).
+    //
+    // Deliberately not runCatching: `as?` yields null instead of throwing, so a failure branch keyed
+    // on a thrown error would never run and the message below would never be logged.
+    private fun getPushModule(): ModuleMessagingPushFCM? {
+        val module = SDKComponent.modules[PUSH_FCM_MODULE_NAME] as? ModuleMessagingPushFCM
+        if (module == null) {
+            logger.error("Live Notifications: push module is not initialized. Ensure the SDK is initialized with live activity templates enabled.")
+        }
+        return module
+    }
+
+    override fun handleWidgetUrl(url: String?, promise: Promise?) {
+        // Zixflow Live Activity widget URLs are an iOS-only contract. Preserve every Android
+        // URL so a shared Expo Router redirectSystemPath implementation cannot suppress routing.
+        promise?.resolve(url)
+    }
+
+    override fun start(payload: ReadableMap?, promise: Promise?) {
+        val module = getPushModule() ?: return promise.rejectNotAvailable()
+        try {
+            val map = requireNotNull(payload) { "payload is required" }
+            // Custom types have no built-in template, so they take the SDK's untyped map path and are
+            // rendered by the app's own callback. Built-ins keep the typed path.
+            val isCustom = map.getString("type") == CUSTOM_TYPE_DISCRIMINATOR
+            val activityType = if (isCustom) {
+                requireCustomActivityType()
+            } else {
+                requireNotNull(map.getString("type")) { "payload.type is required" }
+            }
+            if (activityType !in enabledActivityTypes()) {
+                return promise.rejectNotRegistered(activityType)
+            }
+            val id = if (isCustom) {
+                module.startLiveNotification(activityType, customData(map))
+            } else {
+                module.startLiveNotification(parseData(map))
+            }
+            promise?.resolve(id)
+        } catch (ex: Throwable) {
+            promise?.reject("live_activity_start_failed", ex.message, ex)
+        }
+    }
+
+    override fun update(activityId: String?, payload: ReadableMap?, promise: Promise?) {
+        val module = getPushModule() ?: return promise.rejectNotAvailable()
+        try {
+            val id = requireNotNull(activityId) { "activityId is required" }
+            val map = requireNotNull(payload) { "payload is required" }
+            if (map.getString("type") == CUSTOM_TYPE_DISCRIMINATOR) {
+                module.updateLiveNotification(id, requireCustomActivityType(), customData(map))
+            } else {
+                module.updateLiveNotification(id, parseData(map))
+            }
+            promise?.resolve(null)
+        } catch (ex: Throwable) {
+            promise?.reject("live_activity_update_failed", ex.message, ex)
+        }
+    }
+
+    /**
+     * Ends a live notification. [payload] is accepted for signature parity with iOS, where a final
+     * content-state is what makes ActivityKit render a terminal state; Android renders its own
+     * terminal state (the notification simply stops being ongoing), so it is ignored here.
+     */
+    override fun end(activityId: String?, payload: ReadableMap?, promise: Promise?) {
+        val module = getPushModule() ?: return promise.rejectNotAvailable()
+        try {
+            module.endLiveNotification(requireNotNull(activityId) { "activityId is required" })
+            promise?.resolve(null)
+        } catch (ex: Throwable) {
+            promise?.reject("live_activity_end_failed", ex.message, ex)
+        }
+    }
+
+    /**
+     * The app's own identifier for the custom template. Absent means the app sent a custom payload
+     * without configuring `liveNotifications.customType` — say so, rather than starting a
+     * notification the allowlist would silently drop.
+     */
+    /**
+     * Identifiers the SDK currently has enabled. Read from the live module config rather than cached
+     * at wrapper init: the config can also be built by generated native code that never calls
+     * [applyLiveActivitiesConfig] — the Expo config plugin does exactly that — and a cached set would
+     * be empty there, rejecting every start.
+     */
+    private fun enabledActivityTypes(): Set<String> =
+        SDKComponent.pushModuleConfig.liveNotificationTypes
+
+    /**
+     * The custom identifier, preferring what the wrapper saw and otherwise deriving it from the live
+     * config: exactly one custom type is supported, so it is the single enabled identifier that no
+     * built-in [LiveNotificationType] claims.
+     */
+    private fun customActivityTypeOrNull(): String? = customActivityType
+        ?: enabledActivityTypes().firstOrNull { identifier ->
+            LiveNotificationType.entries.none { it.identifier == identifier }
+        }
+
+    private fun requireCustomActivityType(): String = requireNotNull(customActivityTypeOrNull()) {
+        "No custom Live Activity type is configured. Set `liveNotifications.customType` in your " +
+            "Zixflow SDK config to your own reverse-DNS identifier, and render it from your " +
+            "ZixflowLiveNotificationsCallback."
+    }
+
+    /** Flattens the payload's `data` map. Android stringifies every value downstream anyway. */
+    private fun customData(payload: ReadableMap): Map<String, Any?> =
+        payload.getMap("data")?.toHashMap() ?: emptyMap()
+
+    private fun parseData(payload: ReadableMap): LiveNotificationData {
+        return when (val type = payload.getString("type")) {
+            LiveNotificationType.SEGMENTS.identifier -> LiveNotificationData.Segments(
+                header = payload.requireString("header"),
+                status = payload.requireString("status"),
+                substatus = payload.optString("substatus"),
+                segmentsTotal = payload.requireDouble("segmentsTotal").toInt(),
+                segmentsComplete = payload.requireDouble("segmentsComplete").toInt(),
+                trailingText = payload.optString("trailingText"),
+            )
+
+            LiveNotificationType.COUNTDOWN_TIMER.identifier -> LiveNotificationData.CountdownTimer(
+                header = payload.requireString("header"),
+                title = payload.requireString("title"),
+                statusMessage = payload.optString("statusMessage"),
+                endTime = if (payload.hasKey("endTime") && !payload.isNull("endTime")) {
+                    payload.getDouble("endTime").toLong()
+                } else {
+                    null
+                },
+            )
+
+            // A newer native SDK may know this type even though this wrapper build doesn't.
+            // Reject softly (the caller turns this into a rejected promise) rather than crash.
+            else -> throw IllegalArgumentException("Unsupported Live Activity template: $type")
+        }
+    }
+
+    private fun ReadableMap.requireString(key: String): String =
+        requireNotNull(if (hasKey(key)) getString(key) else null) { "$key is required" }
+
+    private fun ReadableMap.optString(key: String): String? =
+        if (hasKey(key) && !isNull(key)) getString(key) else null
+
+    private fun ReadableMap.requireDouble(key: String): Double {
+        require(hasKey(key) && !isNull(key)) { "$key is required" }
+        return getDouble(key)
+    }
+
+    private fun Promise?.rejectNotAvailable() {
+        this?.reject(
+            "live_activity_module_unavailable",
+            "Live Notifications are unavailable. Enable live activity templates in the SDK config.",
+        )
+    }
+
+    /** Mirrors iOS's `live_activity_type_not_registered` so the same mistake reads the same way. */
+    private fun Promise?.rejectNotRegistered(activityType: String?) {
+        this?.reject(
+            "live_activity_type_not_registered",
+            "Live Activity type '$activityType' is not registered. Add it to " +
+                "`liveNotifications.types` in your Zixflow SDK config (or set " +
+                "`liveNotifications.customType` for a custom type).",
+        )
+    }
+
+    companion object {
+        const val NAME = "NativeZixflowLiveActivities"
+
+        // The SDK's ModuleMessagingPushFCM.MODULE_NAME is `internal`, so we mirror its value here.
+        private const val PUSH_FCM_MODULE_NAME = "MessagingPushFCM"
+
+        // Discriminator JavaScript sends for the custom template. Not a wire identifier — the
+        // notification is started under the app's own `liveNotifications.customType`.
+        private const val CUSTOM_TYPE_DISCRIMINATOR = "custom"
+
+        // The app's own identifier for the custom template, captured from config at SDK init.
+        @Volatile
+        private var customActivityType: String? = null
+
+        // Host-app callback used to render custom (app-defined) live notifications. The native SDK
+        // only accepts it at build time, so the app must register it before the SDK initializes
+        // (e.g. in Application.onCreate before React Native starts). Stored statically because the
+        // SDK config is applied in applyLiveActivitiesConfig, not on this module instance.
+        @Volatile
+        private var liveNotificationCallback: ZixflowLiveNotificationsCallback? = null
+
+        /**
+         * Register the host app's callback for rendering live notifications itself. Custom
+         * (app-defined) activity types have no built-in template, so the app must build the
+         * [android.app.Notification] in
+         * [ZixflowLiveNotificationsCallback.createLiveNotification]; returning `null` there
+         * falls back to the SDK's built-in template.
+         * Call this before the Zixflow SDK is initialized.
+         */
+        @JvmStatic
+        fun setLiveNotificationCallback(callback: ZixflowLiveNotificationsCallback) {
+            liveNotificationCallback = callback
+        }
+
+        /**
+         * Applies live activity configuration onto the FCM push module's config builder. Live
+         * Notifications are hosted by [ModuleMessagingPushFCM], so their config (enabled templates,
+         * custom types, branding) is set on the same [MessagingPushModuleConfig].
+         *
+         * @param builder the push module's config builder.
+         * @param config the `liveNotifications` config map from the customer app.
+         */
+        internal fun applyLiveActivitiesConfig(
+            builder: MessagingPushModuleConfig.Builder,
+            config: Map<String, Any>,
+        ) {
+            // Wire the host app's live-notification renderer, if one was registered.
+            liveNotificationCallback?.let { builder.setLiveNotificationCallback(it) }
+
+            // Unrecognized identifiers are ignored: a newer native SDK may ship types this
+            // wrapper build doesn't know, and that must never break the ones it does know.
+            val templateTypes = config.getTypedValue<List<*>>("types")
+                ?.mapNotNull { it as? String }
+                ?.mapNotNull { identifier ->
+                    LiveNotificationType.entries.firstOrNull { it.identifier == identifier }
+                }
+                .orEmpty()
+            if (templateTypes.isNotEmpty()) {
+                builder.enableLiveNotificationTypes(*templateTypes.toTypedArray())
+            }
+
+            // The custom template. Allowlisting the identifier is both necessary and sufficient:
+            // LiveNotificationHandler drops any push whose activityType isn't in this set, and a type
+            // with no built-in template falls through to the host app's render callback.
+            //
+            // Assigned unconditionally: a re-initialize that drops `customType` must clear it, or
+            // `start` would keep minting notifications under an identifier no longer allowlisted —
+            // which the handler then discards, leaving the caller with an id and nothing on screen.
+            val customType = config.getTypedValue<String>("customType")?.trim()?.takeIf { it.isNotEmpty() }
+            customActivityType = customType
+            if (customType != null) {
+                builder.enableCustomLiveNotificationTypes(customType)
+            }
+
+            val branding = config.getTypedValue<Map<String, Any>>("branding")
+            if (branding != null) {
+                val accentColor = branding.getTypedValue<String>("accentColorHex")
+                    ?.let { runCatching { Color.parseColor(it) }.getOrNull() }
+                    ?: Color.TRANSPARENT
+                // A bundled drawable is preferred over a remote URL: it renders without a network
+                // round-trip, so the logo is present on the very first frame.
+                val logo = branding.getTypedValue<String>("logoResource")
+                    ?.let { name -> drawableResId(name)?.let(LiveNotificationAsset::Drawable) }
+                    ?: branding.getTypedValue<String>("logoUrl")
+                        ?.let(LiveNotificationAsset::RemoteUrl)
+                val smallIcon = branding.getTypedValue<String>("smallIconResource")
+                    ?.let { name -> drawableResId(name) }
+                builder.setLiveNotificationBranding(
+                    LiveNotificationBranding(
+                        companyName = branding.getTypedValue<String>("companyName").orEmpty(),
+                        accentColor = accentColor,
+                        smallIcon = smallIcon,
+                        logo = logo,
+                    ),
+                )
+            }
+        }
+
+        /**
+         * Resolve a bundled drawable by name, or `null` when the host app doesn't ship one under
+         * that name — a missing asset must degrade to "no image", never crash rendering.
+         */
+        private fun drawableResId(name: String): Int? {
+            val context = SDKComponent.android().applicationContext
+            return context.resources
+                .getIdentifier(name, "drawable", context.packageName)
+                .takeIf { it != 0 }
+        }
+    }
+}