@attentive-mobile/attentive-react-native-sdk 2.0.0-beta.6 → 2.0.0-beta.8

package/android/src/main/kotlin/com/attentivereactnativesdk/AttentiveReactNativeSdkModule.kt

@@ -57,10 +57,28 @@ class AttentiveReactNativeSdkModule(reactContext: ReactApplicationContext) :
     }
 
     /**
-     * Initialize the Attentive SDK. Called only from the TypeScript layer (e.g. Bonni App.tsx);
-     * this module must not auto-initialize in Application.onCreate or elsewhere.
-     * This is operation is a no-op on Android. Initialization should happen directly through
-     * native Kotlin for Android builds to enable subscriptions.
+     * TypeScript-facing initialize() — intentionally a no-op on Android.
+     *
+     * On Android, AttentiveSdk.initialize() MUST be called from your Application.onCreate()
+     * (native code) so that lifecycle observers (AppLaunchTracker, etc.) are registered
+     * before the React Native bridge is ready. Calling this from TypeScript on Android has
+     * no effect and will not initialize the SDK.
+     *
+     * Required native setup in your Application class:
+     * ```kotlin
+     * override fun onCreate() {
+     *     super.onCreate()
+     *     val config = AttentiveConfig.Builder()
+     *         .applicationContext(this)
+     *         .domain("YOUR_ATTENTIVE_DOMAIN")
+     *         .mode(AttentiveConfig.Mode.PRODUCTION)
+     *         .build()
+     *     AttentiveSdk.initialize(config)
+     * }
+     * ```
+     *
+     * See the README.md "Android Native Initialization" section for the full guide.
+     * All other SDK operations (identify, recordEvent, push) are handled from TypeScript as normal.
      */
     override fun initialize(
         attentiveDomain: String,
@@ -68,8 +86,15 @@ class AttentiveReactNativeSdkModule(reactContext: ReactApplicationContext) :
         skipFatigueOnCreatives: Boolean,
         enableDebugger: Boolean
     ) {
-        // Initialize debug helper
         debugHelper.initialize(enableDebugger)
+
+        Log.d(
+            TAG,
+            "[AttentiveSDK] initialize() called from TypeScript is a NO-OP on Android. " +
+            "You must call AttentiveSdk.initialize(config) from your Application.onCreate() " +
+            "so that lifecycle observers are registered before the React Native bridge is ready. " +
+            "See README.md § 'Android Native Initialization' for the required setup."
+        )
     }
 
     override fun triggerCreative(creativeId: String?) {
@@ -157,15 +182,19 @@ class AttentiveReactNativeSdkModule(reactContext: ReactApplicationContext) :
     override fun recordProductViewEvent(items: ReadableArray, deeplink: String?) {
         Log.i(TAG, "Sending product viewed event")
 
+        val itemsDebugData = if (debugHelper.isDebuggingEnabled()) extractItemsDebugData(items) else emptyList()
+
         val itemsList = buildItems(items)
         val productViewEvent = ProductViewEvent.Builder().items(itemsList).deeplink(deeplink).build()
 
-        AttentiveSdk.recordEvent(productViewEvent)
+        if (!recordEventSafely("recordProductViewEvent") { AttentiveSdk.recordEvent(productViewEvent) }) return
 
         if (debugHelper.isDebuggingEnabled()) {
             val debugData = mutableMapOf<String, Any>()
             debugData["items_count"] = itemsList.size.toString()
             debugData["deeplink"] = deeplink ?: ""
+            debugData["all_items"] = itemsDebugData
+            itemsDebugData.firstOrNull()?.let { debugData["first_item"] = it }
             debugHelper.showDebugInfo("Product View Event", debugData)
         }
     }
@@ -177,6 +206,9 @@ class AttentiveReactNativeSdkModule(reactContext: ReactApplicationContext) :
         cartCoupon: String?
     ) {
         Log.i(TAG, "Sending purchase event")
+
+        val itemsDebugData = if (debugHelper.isDebuggingEnabled()) extractItemsDebugData(items) else emptyList()
+
         val order = Order.Builder().orderId(orderId).build()
         val itemsList = buildItems(items)
         val purchaseBuilder = PurchaseEvent.Builder(itemsList, order)
@@ -185,14 +217,16 @@ class AttentiveReactNativeSdkModule(reactContext: ReactApplicationContext) :
         }
         val purchaseEvent = purchaseBuilder.build()
 
-        AttentiveSdk.recordEvent(purchaseEvent)
+        if (!recordEventSafely("recordPurchaseEvent") { AttentiveSdk.recordEvent(purchaseEvent) }) return
 
         if (debugHelper.isDebuggingEnabled()) {
             val debugData = mutableMapOf<String, Any>()
             debugData["items_count"] = itemsList.size.toString()
             debugData["order_id"] = orderId
-            if (cartId != null) debugData["cart_id"] = cartId
-            if (cartCoupon != null) debugData["cart_coupon"] = cartCoupon
+            if (!cartId.isNullOrEmpty()) debugData["cart_id"] = cartId!!
+            if (!cartCoupon.isNullOrEmpty()) debugData["cart_coupon"] = cartCoupon!!
+            debugData["all_items"] = itemsDebugData
+            itemsDebugData.firstOrNull()?.let { debugData["first_item"] = it }
             debugHelper.showDebugInfo("Purchase Event", debugData)
         }
     }
@@ -200,15 +234,20 @@ class AttentiveReactNativeSdkModule(reactContext: ReactApplicationContext) :
     override fun recordAddToCartEvent(items: ReadableArray, deeplink: String?) {
         Log.i(TAG, "Sending add to cart event")
 
+        // Extract raw debug data before building items so all bridge fields are preserved
+        val itemsDebugData = if (debugHelper.isDebuggingEnabled()) extractItemsDebugData(items) else emptyList()
+
         val itemsList = buildItems(items)
         val addToCartEvent = AddToCartEvent.Builder().items(itemsList).deeplink(deeplink).build()
 
-        AttentiveSdk.recordEvent(addToCartEvent)
+        if (!recordEventSafely("recordAddToCartEvent") { AttentiveSdk.recordEvent(addToCartEvent) }) return
 
         if (debugHelper.isDebuggingEnabled()) {
             val debugData = mutableMapOf<String, Any>()
             debugData["items_count"] = itemsList.size.toString()
             debugData["deeplink"] = deeplink ?: ""
+            debugData["all_items"] = itemsDebugData
+            itemsDebugData.firstOrNull()?.let { debugData["first_item"] = it }
             debugHelper.showDebugInfo("Add To Cart Event", debugData)
         }
     }
@@ -221,7 +260,7 @@ class AttentiveReactNativeSdkModule(reactContext: ReactApplicationContext) :
         val propertiesMap = convertToStringMap(properties.toHashMap())
         val customEvent = CustomEvent.Builder().type(type).properties(propertiesMap).build()
 
-        AttentiveSdk.recordEvent(customEvent)
+        if (!recordEventSafely("recordCustomEvent") { AttentiveSdk.recordEvent(customEvent) }) return
 
         if (debugHelper.isDebuggingEnabled()) {
             val debugData = mutableMapOf<String, Any>()
@@ -457,14 +496,66 @@ class AttentiveReactNativeSdkModule(reactContext: ReactApplicationContext) :
      * Handle regular/direct app open (not from a push notification).
      *
      * This tracks app open events using the Attentive SDK's event tracking system.
-     * This operation is iOS only. Android version is handled directly by native SDK upon
-     * TypeScript initialization.
      *
      * @param authorizationStatus Current push authorization status
      */
     override fun handleRegularOpen(authorizationStatus: String) {  // Meant to be NOOP
         Log.i(TAG, "🌉 [AttentiveSDK] handleRegularOpen called (Android)")
         Log.i(TAG, "   Authorization status: $authorizationStatus")
+        // Log.i(TAG, "   Tracking regular app open event...")
+
+        // try {
+        //     // Attentive Android SDK 1.0.1 doesn't have a built-in handleRegularOpen method
+        //     // Track app open as custom event
+
+        //     // Option 1: Track as custom event
+
+        //     Log.i(TAG, "   Tracking regular open as custom event 'app_open' with properties")
+
+        //     val properties = mapOf(
+        //         "event_type" to "app_open",
+        //         "authorization_status" to authorizationStatus,
+        //         "platform" to "Android"
+        //     )
+
+        //     try {
+        //         Log.i(TAG, "   Attempting to track custom event for regular app open")
+
+
+        //         val customEvent = CustomEvent.Builder()
+        //             .type("app_open")
+        //             .properties(properties)
+        //             .build()
+
+        //         Log.i(TAG, "   Custom event built successfully, recording event...")
+
+        //         AttentiveSdk.recordEvent(customEvent)
+
+        //         Log.i(TAG, "✅ [AttentiveSDK] handleRegularOpen completed (tracked as custom event)")
+        //         Log.i(TAG, "   Event sent to Attentive backend")
+        //     } catch (e: Exception) {
+        //         Log.w(TAG, "⚠️  [AttentiveSDK] Could not track app open as custom event: ${e.message}")
+        //         Log.i(TAG, "   App open tracking requires manual implementation or SDK upgrade")
+        //     }
+
+        //     if (debugHelper.isDebuggingEnabled()) {
+        //         val debugData = mutableMapOf<String, Any>()
+        //         debugData["authorization_status"] = authorizationStatus
+        //         debugData["event_type"] = "regular_open"
+        //         debugData["platform"] = "Android"
+        //         debugData["sdk_version"] = "2.1.1"
+        //         debugHelper.showDebugInfo("Regular Open Event", debugData)
+        //     }
+        // } catch (e: Exception) {
+        //     Log.e(TAG, "❌ [AttentiveSDK] Error in handleRegularOpen: ${e.message}", e)
+
+        //     if (debugHelper.isDebuggingEnabled()) {
+        //         val debugData = mutableMapOf<String, Any>()
+        //         debugData["error"] = e.message ?: "Unknown error"
+        //         debugData["error_type"] = e.javaClass.simpleName
+        //         debugHelper.showDebugInfo("Regular Open Error", debugData)
+        //     }
+        // }
     }
 
     /**
@@ -668,6 +759,23 @@ class AttentiveReactNativeSdkModule(reactContext: ReactApplicationContext) :
      */
     override fun getInitialPushNotification(promise: Promise) {
       Log.d(TAG, "getInitialPushNotification called!")
+
+//        try {
+//            val payload = AttentiveNotificationStore.getAndClear()
+//            if (payload == null) {
+//                Log.d(TAG, "getInitialPushNotification: no pending initial notification")
+//                promise.resolve(null)
+//                return
+//            }
+//
+//            Log.i(TAG, "getInitialPushNotification: returning stored notification with keys=${payload.keys}")
+//            val result = Arguments.createMap()
+//            payload.forEach { (key, value) -> result.putString(key, value) }
+//            promise.resolve(result)
+//        } catch (e: Exception) {
+//            Log.e(TAG, "getInitialPushNotification: error — ${e.message}", e)
+//            promise.reject("INITIAL_PUSH_ERROR", "Failed to retrieve initial push notification: ${e.message}", e)
+//        }
     }
 
     // ==========================================================================
@@ -686,6 +794,68 @@ class AttentiveReactNativeSdkModule(reactContext: ReactApplicationContext) :
         // No-op: listener bookkeeping is handled by the JS NativeEventEmitter.
     }
 
+    /**
+     * Extracts a human-readable list of item maps from the raw bridge array for debug display.
+     *
+     * This intentionally reads all fields from the original [ReadableArray] rather than from
+     * the built [Item] objects so that every field sent from TypeScript (including optional ones)
+     * is visible in the debugger — even fields that may be skipped during SDK item construction.
+     *
+     * @param rawItems The raw item array as received from the React Native bridge.
+     * @return A list of maps, one per item, containing all present fields.
+     */
+    /**
+     * Executes [block] (which calls [AttentiveSdk.recordEvent]) and catches any [Exception].
+     *
+     * When an exception is caught the log always includes the exception's simple class name so
+     * callers can distinguish an uninitialized-SDK error (typically [IllegalStateException]) from
+     * a programming mistake such as [NullPointerException] or [IllegalArgumentException] in event
+     * construction — both of which would have been silently misattributed to initialization
+     * failure under the previous broad catch-and-blame pattern.
+     *
+     * @param callerName Method name to include in the log for quick triage (e.g. "recordPurchaseEvent").
+     * @param block Lambda that performs the [AttentiveSdk.recordEvent] call.
+     * @return `true` if [block] completed without throwing, `false` if an exception was caught.
+     */
+    private fun recordEventSafely(callerName: String, block: () -> Unit): Boolean {
+        return try {
+            block()
+            true
+        } catch (e: Exception) {
+            // Include the exception class so the developer can tell apart an uninitialized SDK
+            // (IllegalStateException) from a malformed-event bug (NullPointerException, etc.)
+            Log.e(
+                TAG,
+                "[AttentiveSDK] $callerName failed with ${e.javaClass.simpleName}: ${e.message}. " +
+                "If the SDK was not initialized via AttentiveSdk.initialize() in Application.onCreate(), " +
+                "that is the most likely cause. Otherwise, inspect the exception type above."
+            )
+            false
+        }
+    }
+
+    private fun extractItemsDebugData(rawItems: ReadableArray): List<Map<String, Any>> {
+        val result = mutableListOf<Map<String, Any>>()
+        for (i in 0 until rawItems.size()) {
+            val rawItem = rawItems.getMap(i) ?: continue
+            val itemData = mutableMapOf<String, Any>()
+
+            rawItem.getString("productId")?.let { itemData["productId"] = it }
+            rawItem.getString("productVariantId")?.let { itemData["productVariantId"] = it }
+            rawItem.getString("price")?.let { itemData["price"] = it }
+            rawItem.getString("currency")?.let { itemData["currency"] = it }
+            rawItem.getString("name")?.let { itemData["name"] = it }
+            rawItem.getString("productImage")?.let { itemData["productImage"] = it }
+            rawItem.getString("category")?.let { itemData["category"] = it }
+            if (rawItem.hasKey("quantity")) {
+                itemData["quantity"] = rawItem.getDouble("quantity").toInt()
+            }
+
+            result.add(itemData)
+        }
+        return result
+    }
+
     private fun convertToStringMap(inputMap: Map<String, Any?>): Map<String, String> {
         val outputMap = mutableMapOf<String, String>()
         for ((key, value) in inputMap) {
@@ -702,19 +872,37 @@ class AttentiveReactNativeSdkModule(reactContext: ReactApplicationContext) :
     private fun buildItems(rawItems: ReadableArray): List<Item> {
         Log.i(TAG, "buildItems method called with rawItems: $rawItems")
         val items = mutableListOf<Item>()
+
         for (i in 0 until rawItems.size()) {
             val rawItem = rawItems.getMap(i) ?: continue
 
-            // Price and currency are now flattened, not nested
+            // Required scalar fields
             val priceValue = rawItem.getString("price") ?: continue
             val currencyCode = rawItem.getString("currency") ?: continue
+            val productId = rawItem.getString("productId") ?: continue
+            val productVariantId = rawItem.getString("productVariantId") ?: continue
+
+            // Parse price amount — skip item on malformed value rather than crash
+            val priceDecimal = try {
+                BigDecimal(priceValue)
+            } catch (e: NumberFormatException) {
+                Log.w(TAG, "buildItems: invalid price value '$priceValue' at index $i — skipping item")
+                continue
+            }
+
+            // Parse currency — skip item on unrecognised ISO 4217 code rather than crash
+            val currency = try {
+                Currency.getInstance(currencyCode)
+            } catch (e: IllegalArgumentException) {
+                Log.w(TAG, "buildItems: invalid currency code '$currencyCode' at index $i — skipping item")
+                continue
+            }
+
             val price = Price.Builder()
-                .price(BigDecimal(priceValue))
-                .currency(Currency.getInstance(currencyCode))
+                .price(priceDecimal)
+                .currency(currency)
                 .build()
 
-            val productId = rawItem.getString("productId") ?: continue
-            val productVariantId = rawItem.getString("productVariantId") ?: continue
             val builder = Item.Builder(productId, productVariantId, price)
 
             if (rawItem.hasKey("productImage")) {
@@ -725,16 +913,16 @@ class AttentiveReactNativeSdkModule(reactContext: ReactApplicationContext) :
                 builder.name(rawItem.getString("name"))
             }
 
+            // JS numbers are doubles on the bridge; use getDouble().toInt() to avoid ClassCastException
             if (rawItem.hasKey("quantity")) {
-                builder.quantity(rawItem.getInt("quantity"))
+                builder.quantity(rawItem.getDouble("quantity").toInt())
             }
 
             if (rawItem.hasKey("category")) {
                 builder.category(rawItem.getString("category"))
             }
 
-            val item = builder.build()
-            items.add(item)
+            items.add(builder.build())
         }
 
         return items

package/attentive-react-native-sdk.podspec

@@ -16,7 +16,7 @@ Pod::Spec.new do |s|
 
   s.source_files = "ios/**/*.{h,m,mm,swift}"
 
-  s.dependency 'attentive-ios-sdk', '2.0.8'
+  s.dependency 'attentive-ios-sdk', '2.0.13'
   s.swift_versions = ['5']
   s.dependency "React-Core"
 

package/ios/Bridging/ATTNNativeSDK.swift

@@ -280,7 +280,7 @@ struct DebugEvent {
 
   /**
    * Handle when a push notification is opened by the user.
-   * Note: SDK 2.0.8 changed the API to require UNNotificationResponse instead of userInfo dictionary.
+   * Note: The SDK requires UNNotificationResponse instead of a plain userInfo dictionary.
    * This method is kept for backward compatibility but has limited functionality.
    * For full functionality, handle push notifications natively in AppDelegate.
    *
@@ -290,11 +290,11 @@ struct DebugEvent {
    */
   @objc(handlePushOpened:applicationState:authorizationStatus:)
   public func handlePushOpened(_ userInfo: [String: Any], applicationState: String, authorizationStatus: String) {
-    // Note: SDK 2.0.8 changed the API to require UNNotificationResponse
+    // Note: The native SDK requires UNNotificationResponse for push tracking.
     // Since React Native doesn't provide direct access to UNNotificationResponse,
-    // apps should handle push notifications natively in AppDelegate for full functionality
-    print("[AttentiveSDK] Warning: Push notification handling from React Native is limited in SDK 2.0.8")
-    print("[AttentiveSDK] The native SDK now requires UNNotificationResponse for push tracking")
+    // apps should handle push notifications natively in AppDelegate for full functionality.
+    print("[AttentiveSDK] Warning: Push notification handling from React Native is limited")
+    print("[AttentiveSDK] The native SDK requires UNNotificationResponse for push tracking")
     print("[AttentiveSDK] Please implement push handling in AppDelegate for full functionality")
 
     if debuggingEnabled {
@@ -302,7 +302,7 @@ struct DebugEvent {
         "applicationState": applicationState,
         "authorizationStatus": authorizationStatus,
         "userInfo": userInfo,
-        "warning": "SDK 2.0.8 requires native UNNotificationResponse handling in AppDelegate"
+        "warning": "Native SDK requires UNNotificationResponse handling in AppDelegate"
       ])
     }
   }
@@ -313,15 +313,15 @@ struct DebugEvent {
    */
   @objc(handleForegroundNotification:)
   public func handleForegroundNotification(_ userInfo: [String: Any]) {
-    // Note: SDK 2.0.8 changed the API to require UNNotificationResponse
-    // Since React Native doesn't provide this, we'll log a warning
-    print("[AttentiveSDK] Warning: Foreground notification handling from React Native is limited in SDK 2.0.8")
+    // Note: The native SDK requires UNNotificationResponse for push tracking.
+    // Since React Native doesn't provide this, we'll log a warning.
+    print("[AttentiveSDK] Warning: Foreground notification handling from React Native is limited")
     print("[AttentiveSDK] Please handle foreground notifications natively in AppDelegate for full functionality")
 
     if debuggingEnabled {
       showDebugInfo(event: "Foreground Notification", data: [
         "userInfo": userInfo,
-        "warning": "SDK 2.0.8 requires native UNNotificationResponse handling"
+        "warning": "Native SDK requires UNNotificationResponse handling"
       ])
     }
   }
@@ -383,63 +383,126 @@ struct DebugEvent {
   /**
    * React Native bridge entry point for foreground push tracking.
    *
-   * **Important — iOS limitation**: The Attentive iOS SDK requires a `UNNotificationResponse`
-   * object for `handleForegroundPush`, which is an opaque system type that cannot be
-   * serialised across the React Native bridge. Calling this method from JS therefore
-   * **cannot invoke the native SDK** and is a no-op.
+   * The Attentive iOS SDK requires a `UNNotificationResponse` which cannot be
+   * serialised across the React Native bridge. To work around this, the method
+   * checks `AttentiveSDKManager.shared` for a cached response (set by the
+   * recommended `handleNotificationResponse(_:)` call in AppDelegate).
    *
-   * The correct solution for iOS is to call
-   * `AttentiveSDKManager.shared.handleForegroundPush(response:authorizationStatus:)`
-   * directly from the host app's `UNUserNotificationCenterDelegate` implementation
-   * (i.e. `AppDelegate.userNotificationCenter(_:didReceive:withCompletionHandler:)`).
-   * Bonni's `AppDelegate.swift` already does this, so foreground push events are tracked
-   * correctly via the native path — this RN bridge variant is intentionally unused on iOS.
+   * - If a cached response exists **and was already tracked**, this is a no-op
+   *   (prevents double-tracking).
+   * - If a cached response exists **but was not yet tracked**, it is used to
+   *   call the real native SDK method.
+   * - If no cached response is available, a warning is logged instructing the
+   *   developer to add `AttentiveSDKManager.shared.handleNotificationResponse(response)`
+   *   to their AppDelegate.
    *
-   * @param userInfo The notification payload dictionary (unused on iOS).
-   * @param authorizationStatus Current push authorization status string (unused on iOS).
+   * @param userInfo The notification payload dictionary.
+   * @param authorizationStatus Current push authorization status string.
    */
   @objc(handleForegroundPushFromRN:authorizationStatus:)
   public func handleForegroundPushFromRN(_ userInfo: [String: Any], authorizationStatus: String) {
-    // iOS: no-op — tracking is performed natively via AttentiveSDKManager in AppDelegate.
-    // The UNNotificationResponse required by the iOS SDK cannot cross the RN bridge.
-    print("[AttentiveSDK] handleForegroundPushFromRN: iOS push tracking is handled natively via AttentiveSDKManager in AppDelegate. This RN bridge call is a no-op on iOS.")
+    if let pending = AttentiveSDKManager.shared.consumePendingResponse() {
+      if pending.alreadyTracked {
+        // Already tracked by handleNotificationResponse — nothing to do.
+        if debuggingEnabled {
+          showDebugInfo(event: "Foreground Push (already tracked natively)", data: [
+            "authorizationStatus": authorizationStatus,
+            "note": "Push was already tracked via AttentiveSDKManager.handleNotificationResponse."
+          ])
+        }
+        return
+      }
 
-    if debuggingEnabled {
-      showDebugInfo(event: "Foreground Push (RN bridge — iOS no-op)", data: [
-        "authorizationStatus": authorizationStatus,
-        "userInfo": userInfo,
-        "note": "iOS: tracked via AppDelegate → AttentiveSDKManager. UNNotificationResponse not available from RN bridge."
-      ])
+      // Cached response exists but wasn't tracked yet — track it now.
+      let authStatus = mapAuthorizationStatus(authorizationStatus)
+      sdk.handleForegroundPush(response: pending.response, authorizationStatus: authStatus)
+
+      if debuggingEnabled {
+        let cachedUserInfo = pending.response.notification.request.content.userInfo
+        showDebugInfo(event: "Foreground Push (tracked via cached response)", data: [
+          "authorizationStatus": authorizationStatus,
+          "userInfo": cachedUserInfo as? [String: Any] ?? [:],
+          "actionIdentifier": pending.response.actionIdentifier
+        ])
+      }
+    } else {
+      // No cached response. Either:
+      //   (a) The client's AppDelegate is missing handleNotificationResponse, or
+      //   (b) A prior bridge call (handlePushOpen / handleForegroundPush) already consumed it.
+      print("[AttentiveSDK] handleForegroundPushFromRN: No cached UNNotificationResponse available.")
+      print("[AttentiveSDK] If push tracking is not working, add this line to your AppDelegate's didReceive handler:")
+      print("[AttentiveSDK]   AttentiveSDKManager.shared.handleNotificationResponse(response)")
+
+      if debuggingEnabled {
+        showDebugInfo(event: "Foreground Push (no cached response)", data: [
+          "authorizationStatus": authorizationStatus,
+          "userInfo": userInfo,
+          "note": "No cached response — either already consumed by a prior call or AppDelegate setup missing."
+        ])
+      }
     }
   }
 
   /**
    * React Native bridge entry point for push-open tracking (background/inactive tap).
    *
-   * **Important — iOS limitation**: The Attentive iOS SDK requires a `UNNotificationResponse`
-   * object for `handlePushOpen`, which cannot be serialised across the React Native bridge.
-   * Calling this method from JS is therefore a **no-op on iOS**.
+   * The Attentive iOS SDK requires a `UNNotificationResponse` which cannot be
+   * serialised across the React Native bridge. To work around this, the method
+   * checks `AttentiveSDKManager.shared` for a cached response (set by the
+   * recommended `handleNotificationResponse(_:)` call in AppDelegate).
    *
-   * The correct solution is to call
-   * `AttentiveSDKManager.shared.handlePushOpen(response:authorizationStatus:)` directly
-   * from `AppDelegate.userNotificationCenter(_:didReceive:withCompletionHandler:)`.
-   * Bonni's `AppDelegate.swift` already does this via the native path.
+   * - If a cached response exists **and was already tracked**, this is a no-op
+   *   (prevents double-tracking).
+   * - If a cached response exists **but was not yet tracked**, it is used to
+   *   call the real native SDK method.
+   * - If no cached response is available, a warning is logged instructing the
+   *   developer to add `AttentiveSDKManager.shared.handleNotificationResponse(response)`
+   *   to their AppDelegate.
    *
-   * @param userInfo The notification payload dictionary (unused on iOS).
-   * @param authorizationStatus Current push authorization status string (unused on iOS).
+   * @param userInfo The notification payload dictionary.
+   * @param authorizationStatus Current push authorization status string.
    */
   @objc(handlePushOpenFromRN:authorizationStatus:)
   public func handlePushOpenFromRN(_ userInfo: [String: Any], authorizationStatus: String) {
-    // iOS: no-op — tracking is performed natively via AttentiveSDKManager in AppDelegate.
-    // The UNNotificationResponse required by the iOS SDK cannot cross the RN bridge.
-    print("[AttentiveSDK] handlePushOpenFromRN: iOS push tracking is handled natively via AttentiveSDKManager in AppDelegate. This RN bridge call is a no-op on iOS.")
+    if let pending = AttentiveSDKManager.shared.consumePendingResponse() {
+      if pending.alreadyTracked {
+        // Already tracked by handleNotificationResponse — nothing to do.
+        if debuggingEnabled {
+          showDebugInfo(event: "Push Open (already tracked natively)", data: [
+            "authorizationStatus": authorizationStatus,
+            "note": "Push was already tracked via AttentiveSDKManager.handleNotificationResponse."
+          ])
+        }
+        return
+      }
 
-    if debuggingEnabled {
-      showDebugInfo(event: "Push Open (RN bridge — iOS no-op)", data: [
-        "authorizationStatus": authorizationStatus,
-        "userInfo": userInfo,
-        "note": "iOS: tracked via AppDelegate → AttentiveSDKManager. UNNotificationResponse not available from RN bridge."
-      ])
+      // Cached response exists but wasn't tracked yet — track it now.
+      let authStatus = mapAuthorizationStatus(authorizationStatus)
+      sdk.handlePushOpen(response: pending.response, authorizationStatus: authStatus)
+
+      if debuggingEnabled {
+        let cachedUserInfo = pending.response.notification.request.content.userInfo
+        showDebugInfo(event: "Push Open (tracked via cached response)", data: [
+          "authorizationStatus": authorizationStatus,
+          "userInfo": cachedUserInfo as? [String: Any] ?? [:],
+          "actionIdentifier": pending.response.actionIdentifier
+        ])
+      }
+    } else {
+      // No cached response. Either:
+      //   (a) The client's AppDelegate is missing handleNotificationResponse, or
+      //   (b) A prior bridge call (handlePushOpen / handleForegroundPush) already consumed it.
+      print("[AttentiveSDK] handlePushOpenFromRN: No cached UNNotificationResponse available.")
+      print("[AttentiveSDK] If push tracking is not working, add this line to your AppDelegate's didReceive handler:")
+      print("[AttentiveSDK]   AttentiveSDKManager.shared.handleNotificationResponse(response)")
+
+      if debuggingEnabled {
+        showDebugInfo(event: "Push Open (no cached response)", data: [
+          "authorizationStatus": authorizationStatus,
+          "userInfo": userInfo,
+          "note": "No cached response — either already consumed by a prior call or AppDelegate setup missing."
+        ])
+      }
     }
   }