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

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."
+        ])
+      }
     }
   }
 

package/ios/Bridging/AttentiveSDKManager.swift

@@ -7,6 +7,7 @@
 //
 
 import Foundation
+import UIKit
 import UserNotifications
 
 /**
@@ -14,21 +15,21 @@ import UserNotifications
  * This allows AppDelegate and other native code to access the SDK instance
  * that was initialized from React Native.
  *
- * Usage in AppDelegate:
+ * ## Minimal Integration (recommended)
+ *
+ * In your AppDelegate's `userNotificationCenter(_:didReceive:withCompletionHandler:)`,
+ * add **one line** to enable push-open and foreground-push tracking:
+ *
  * ```swift
- * // In userNotificationCenter(_:didReceive:withCompletionHandler:)
- * UNUserNotificationCenter.current().getNotificationSettings { settings in
- *   let authStatus = settings.authorizationStatus
- *   DispatchQueue.main.async {
- *     switch UIApplication.shared.applicationState {
- *     case .active:
- *       AttentiveSDKManager.shared.handleForegroundPush(response: response, authorizationStatus: authStatus)
- *     case .background, .inactive:
- *       AttentiveSDKManager.shared.handlePushOpen(response: response, authorizationStatus: authStatus)
- *     @unknown default:
- *       AttentiveSDKManager.shared.handlePushOpen(response: response, authorizationStatus: authStatus)
- *     }
- *   }
+ * func userNotificationCenter(_ center: UNUserNotificationCenter,
+ *                             didReceive response: UNNotificationResponse,
+ *                             withCompletionHandler completionHandler: @escaping () -> Void) {
+ *     // Track push interaction with Attentive (handles app-state detection + auth status internally)
+ *     AttentiveSDKManager.shared.handleNotificationResponse(response)
+ *
+ *     // Forward to your push library (e.g. RNCPushNotificationIOS) for JS-side handling
+ *     RNCPushNotificationIOS.didReceive(response)
+ *     completionHandler()
  * }
  * ```
  */
@@ -36,10 +37,40 @@ import UserNotifications
     /// Shared singleton instance
     @objc public static let shared: AttentiveSDKManager = AttentiveSDKManager()
 
-    /// The Attentive SDK instance as AnyObject for Objective-C compatibility
-    /// This should be set when the SDK is initialized from React Native
-    /// Cast to ATTNNativeSDK in Swift code
-    @objc public var sdk: AnyObject?
+    /// The Attentive SDK instance as AnyObject for Objective-C compatibility.
+    /// When set, any pending (untracked) notification response is automatically flushed.
+    @objc public var sdk: AnyObject? {
+        didSet {
+            if sdk != nil {
+                flushPendingResponseIfNeeded()
+            }
+        }
+    }
+
+    // MARK: - Notification Response Cache
+
+    /// The most recent UNNotificationResponse, cached so the RN bridge can use it
+    /// when JS calls handlePushOpen / handleForegroundPush.
+    ///
+    /// **Known limitation:** This is a single-slot cache. If two notifications
+    /// arrive in rapid succession (e.g. a tap followed immediately by a
+    /// foreground delivery), the second call to `handleNotificationResponse`
+    /// overwrites the first before its async tracking completes. In practice
+    /// this is extremely rare because `didReceive` is serialized by the system.
+    private var pendingResponse: UNNotificationResponse?
+
+    /// Whether the pending response has already been tracked via `handleNotificationResponse`.
+    /// Prevents double-tracking when both the native convenience method and the JS bridge fire.
+    private var pendingResponseTracked: Bool = false
+
+    /// The app state captured at the moment `handleNotificationResponse` was called.
+    /// Stored so that cold-launch replays use the original state (typically `.inactive`
+    /// or `.background`) rather than `.active` which is what the app will be in by the
+    /// time the SDK finishes initializing.
+    private var pendingAppState: UIApplication.State = .inactive
+
+    /// Serialises access to the cache fields above.
+    private let responseLock = NSLock()
 
     private override init() {
         super.init()
@@ -55,29 +86,167 @@ import UserNotifications
         sdk = nativeSDK
     }
 
-    // MARK: - Push Notification Handlers (for AppDelegate)
+    // MARK: - Push Notification Convenience Method
+
+    /**
+     * Handle a push notification response in one call.
+     *
+     * This is the **recommended** way to track push interactions on iOS.
+     * It automatically determines the app state, fetches the current
+     * authorization status, and calls the appropriate native SDK method
+     * (`handlePushOpen` or `handleForegroundPush`).
+     *
+     * Call this from your AppDelegate's
+     * `userNotificationCenter(_:didReceive:withCompletionHandler:)`.
+     *
+     * The response is also cached so that if the JS layer later calls
+     * `handlePushOpen()` or `handleForegroundPush()` via the RN bridge,
+     * the bridge can fulfil the call using the real `UNNotificationResponse`
+     * without double-tracking.
+     *
+     * **Cold-launch safety:** If the SDK has not yet been initialized (e.g. the
+     * app was launched from a killed state via a push tap), the response is
+     * cached and will be automatically tracked once `sdk` is set during RN
+     * bridge initialization.
+     *
+     * @param response The `UNNotificationResponse` from the notification center delegate.
+     */
+    @objc public func handleNotificationResponse(_ response: UNNotificationResponse) {
+        // UIApplication.shared.applicationState is a UIKit property that must
+        // be read on the main thread. userNotificationCenter(_:didReceive:) is
+        // almost always delivered on main, but we guard defensively.
+        let cacheAndTrack = { [self] (appState: UIApplication.State) in
+            // Cache the response for the RN bridge (consumed by handlePushOpenFromRN /
+            // handleForegroundPushFromRN).
+            responseLock.lock()
+            pendingResponse = response
+            pendingResponseTracked = false
+            pendingAppState = appState
+            responseLock.unlock()
+
+            trackResponse(response, appState: appState)
+        }
+
+        if Thread.isMainThread {
+            cacheAndTrack(UIApplication.shared.applicationState)
+        } else {
+            DispatchQueue.main.async {
+                cacheAndTrack(UIApplication.shared.applicationState)
+            }
+        }
+    }
+
+    // MARK: - Push Notification Handlers (legacy — prefer handleNotificationResponse)
 
     /**
      * Handle a push notification when the app is in the foreground (active state).
-     * Call this from AppDelegate's userNotificationCenter(_:didReceive:withCompletionHandler:)
-     * when UIApplication.shared.applicationState == .active
      *
-     * @param response The UNNotificationResponse from the notification center delegate
-     * @param authorizationStatus Current push authorization status from notification settings
+     * - Important: Deprecated — use ``handleNotificationResponse(_:)`` instead,
+     *   which handles app-state detection and auth-status lookup automatically.
+     *   Do **not** call both methods for the same notification.
      */
+    @available(*, deprecated, message: "Use handleNotificationResponse(_:) instead")
     @objc public func handleForegroundPush(response: UNNotificationResponse, authorizationStatus: UNAuthorizationStatus) {
         nativeSDK?.handleForegroundPush(response: response, authorizationStatus: authorizationStatus)
     }
 
     /**
      * Handle when a push notification is opened by the user (app in background/inactive state).
-     * Call this from AppDelegate's userNotificationCenter(_:didReceive:withCompletionHandler:)
-     * when UIApplication.shared.applicationState == .background or .inactive
      *
-     * @param response The UNNotificationResponse from the notification center delegate
-     * @param authorizationStatus Current push authorization status from notification settings
+     * - Important: Deprecated — use ``handleNotificationResponse(_:)`` instead,
+     *   which handles app-state detection and auth-status lookup automatically.
+     *   Do **not** call both methods for the same notification.
      */
+    @available(*, deprecated, message: "Use handleNotificationResponse(_:) instead")
     @objc public func handlePushOpen(response: UNNotificationResponse, authorizationStatus: UNAuthorizationStatus) {
         nativeSDK?.handlePushOpen(response: response, authorizationStatus: authorizationStatus)
     }
+
+    // MARK: - Response Cache (internal, used by RN bridge)
+
+    /**
+     * Consume the cached notification response.
+     *
+     * Returns the cached `UNNotificationResponse` and whether it was already
+     * tracked by `handleNotificationResponse`. The bridge uses this to decide
+     * whether to call the native SDK again.
+     *
+     * After this call the cache is cleared.
+     */
+    func consumePendingResponse() -> (response: UNNotificationResponse, alreadyTracked: Bool)? {
+        responseLock.lock()
+        defer { responseLock.unlock() }
+
+        guard let response = pendingResponse else { return nil }
+        let tracked = pendingResponseTracked
+        pendingResponse = nil
+        pendingResponseTracked = false
+        return (response, tracked)
+    }
+
+    // MARK: - Private
+
+    /// Attempt to track a cached response via the native SDK.
+    /// If nativeSDK is nil (cold launch), returns without marking tracked;
+    /// the `sdk` didSet will call `flushPendingResponseIfNeeded` later.
+    ///
+    /// Uses the supplied `appState` (captured at `handleNotificationResponse` time)
+    /// rather than the current app state, so cold-launch replays classify the
+    /// event correctly.
+    private func trackResponse(_ response: UNNotificationResponse, appState: UIApplication.State) {
+        UNUserNotificationCenter.current().getNotificationSettings { [weak self] settings in
+            guard let self = self else { return }
+            let authStatus = settings.authorizationStatus
+            DispatchQueue.main.async {
+                // Check that this response is still pending and untracked, then
+                // mark tracked optimistically *before* releasing the lock. This
+                // closes the window where consumePendingResponse() could run on
+                // another thread, see alreadyTracked: false, and also call the
+                // native SDK — resulting in double-tracking.
+                self.responseLock.lock()
+                guard self.pendingResponse === response, !self.pendingResponseTracked else {
+                    self.responseLock.unlock()
+                    return
+                }
+
+                guard self.nativeSDK != nil else {
+                    // SDK not yet initialized (cold launch). Leave
+                    // pendingResponseTracked = false so the didSet observer
+                    // on `sdk` can flush later.
+                    self.responseLock.unlock()
+                    return
+                }
+
+                // Mark tracked while still holding the lock, before the SDK call.
+                self.pendingResponseTracked = true
+                self.responseLock.unlock()
+
+                // Safe to call outside the lock — we've already claimed ownership.
+                switch appState {
+                case .active:
+                    self.nativeSDK?.handleForegroundPush(response: response, authorizationStatus: authStatus)
+                case .background, .inactive:
+                    self.nativeSDK?.handlePushOpen(response: response, authorizationStatus: authStatus)
+                @unknown default:
+                    self.nativeSDK?.handlePushOpen(response: response, authorizationStatus: authStatus)
+                }
+            }
+        }
+    }
+
+    /// Called from `sdk` didSet when the SDK becomes available.
+    /// If there is a pending untracked response (cold-launch scenario),
+    /// track it now using the app state captured at the original
+    /// `handleNotificationResponse` call.
+    private func flushPendingResponseIfNeeded() {
+        responseLock.lock()
+        guard let response = pendingResponse, !pendingResponseTracked else {
+            responseLock.unlock()
+            return
+        }
+        let appState = pendingAppState
+        responseLock.unlock()
+
+        trackResponse(response, appState: appState)
+    }
 }

package/ios/Podfile

@@ -20,7 +20,7 @@ target 'AttentiveReactNativeSdk' do
   flags = get_default_flags()
 
   # Ensure Swift support
-  pod 'attentive-ios-sdk', '2.0.8'
+  pod 'attentive-ios-sdk', '2.0.13'
 
   use_react_native!(
     :path => config[:reactNativePath],

package/lib/commonjs/index.js

@@ -338,17 +338,16 @@ function handleForegroundNotification(userInfo) {
 
 /**
  * Handle a push notification when the app is in the foreground (active state).
- * This is the React Native equivalent of the native iOS handleForegroundPush method.
  *
  * Call this when you receive a notification response and the app state is 'active'.
- * This is part of implementing the native iOS pattern:
- * ```swift
- * case .active:
- *   self.attentiveSdk?.handleForegroundPush(response: response, authorizationStatus: authStatus)
- * ```
  *
- * On iOS, this properly tracks foreground push notifications.
- * On Android, registers the FCM token when provided by the host app.
+ * **iOS prerequisite:** Your AppDelegate's
+ * `userNotificationCenter(_:didReceive:withCompletionHandler:)` must call
+ * `AttentiveSDKManager.shared.handleNotificationResponse(response)` so that
+ * the SDK can cache the `UNNotificationResponse` required by the native iOS SDK.
+ * Without that one line of native code, this function cannot track the event.
+ *
+ * On Android, this tracks the foreground push as a custom event.
  *
  * @param userInfo - The notification payload from the push notification
  * @param authorizationStatus - Current push authorization status
@@ -371,17 +370,16 @@ function handleForegroundPush(userInfo, authorizationStatus) {
 
 /**
  * Handle when a push notification is opened by the user (app in background/inactive state).
- * This is the React Native equivalent of the native iOS handlePushOpen method.
  *
  * Call this when you receive a notification response and the app state is 'background' or 'inactive'.
- * This is part of implementing the native iOS pattern:
- * ```swift
- * case .background, .inactive:
- *   self.attentiveSdk?.handlePushOpen(response: response, authorizationStatus: authStatus)
- * ```
  *
- * On iOS, this properly tracks push notification opens.
- * On Android, registers the FCM token when provided by the host app.
+ * **iOS prerequisite:** Your AppDelegate's
+ * `userNotificationCenter(_:didReceive:withCompletionHandler:)` must call
+ * `AttentiveSDKManager.shared.handleNotificationResponse(response)` so that
+ * the SDK can cache the `UNNotificationResponse` required by the native iOS SDK.
+ * Without that one line of native code, this function cannot track the event.
+ *
+ * On Android, this tracks the push open as a custom event.
  *
  * @param userInfo - The notification payload from the push notification
  * @param authorizationStatus - Current push authorization status

package/lib/commonjs/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["_reactNative","require","_NativeAttentiveReactNativeSdk","_interopRequireDefault","obj","__esModule","default","LINKING_ERROR","Platform","select","ios","AttentiveReactNativeSdk","NativeAttentiveReactNativeSdkModule","Proxy","get","Error","initialize","configuration","attentiveDomain","mode","skipFatigueOnCreatives","enableDebugger","triggerCreative","creativeId","destroyCreative","updateDomain","domain","identify","identifiers","phone","email","klaviyoId","shopifyId","clientUserId","customIdentifiers","clearUser","recordAddToCartEvent","attrs","items","deeplink","recordProductViewEvent","recordPurchaseEvent","orderId","cartId","cartCoupon","recordCustomEvent","type","properties","invokeAttentiveDebugHelper","exportDebugLogs","registerForPushNotifications","getPushAuthorizationStatus","registerDeviceToken","token","authorizationStatus","registerDeviceTokenWithCallback","callback","handleRegularOpen","console","log","handlePushOpened","userInfo","applicationState","handleForegroundNotification","handleForegroundPush","handlePushOpen","getInitialPushNotification","result"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":"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BAA0B,CAAC,CAAC;AAC7D;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASC,mBAAmBA,CAC1BC,KAAa,EACbC,mBAA4C,EACtC;EACN3C,uBAAuB,CAACyC,mBAAmB,CAACC,KAAK,EAAEC,mBAAmB,CAAC;AACzE;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASC,+BAA+BA,CACtCF,KAAa,EACbC,mBAA4C,EAC5CE,QAKS,EACH;EACN7C,uBAAuB,CAAC4C,+BAA+B,CACrDF,KAAK,EACLC,mBAAmB,EACnBE,QACF,CAAC;AACH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASC,iBAAiBA,CAACH,mBAA4C,EAAQ;EAC7EI,OAAO,CAACC,GAAG,CAAC,6DAA6D,CAAC;EAC1ED,OAAO,CAACC,GAAG,CAAC,4BAA4BL,mBAAmB,EAAE,CAAC;EAC9DI,OAAO,CAACC,GAAG,CACT,mEACF,CAAC;EAEDhD,uBAAuB,CAAC8C,iBAAiB,CAACH,mBAAmB,CAAC;EAE9DI,OAAO,CAACC,GAAG,CAAC,mDAAmD,CAAC;AAClE;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASC,gBAAgBA,CACvBC,QAAkC,EAClCC,gBAAkC,EAClCR,mBAA4C,EACtC;EACN3C,uBAAuB,CAACiD,gBAAgB,CACtCC,QAAQ,EACRC,gBAAgB,EAChBR,mBACF,CAAC;AACH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASS,4BAA4BA,CACnCF,QAAkC,EAC5B;EACNlD,uBAAuB,CAACoD,4BAA4B,CAACF,QAAkB,CAAC;AAC1E;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASG,oBAAoBA,CAC3BH,QAAkC,EAClCP,mBAA4C,EACtC;EACN3C,uBAAuB,CAACqD,oBAAoB,CAC1CH,QAAQ,EACRP,mBACF,CAAC;AACH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASW,cAAcA,CACrBJ,QAAkC,EAClCP,mBAA4C,EACtC;EACN3C,uBAAuB,CAACsD,cAAc,CACpCJ,QAAQ,EACRP,mBACF,CAAC;AACH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,eAAeY,0BAA0BA,CAAA,EAA2C;EAClF,MAAMC,MAAM,GAAG,MAAMxD,uBAAuB,CAACuD,0BAA0B,CAAC,CAAC;EACzE,OAAOC,MAAM;AACf","ignoreList":[]}
+{"version":3,"names":["_reactNative","require","_NativeAttentiveReactNativeSdk","_interopRequireDefault","obj","__esModule","default","LINKING_ERROR","Platform","select","ios","AttentiveReactNativeSdk","NativeAttentiveReactNativeSdkModule","Proxy","get","Error","initialize","configuration","attentiveDomain","mode","skipFatigueOnCreatives","enableDebugger","triggerCreative","creativeId","destroyCreative","updateDomain","domain","identify","identifiers","phone","email","klaviyoId","shopifyId","clientUserId","customIdentifiers","clearUser","recordAddToCartEvent","attrs","items","deeplink","recordProductViewEvent","recordPurchaseEvent","orderId","cartId","cartCoupon","recordCustomEvent","type","properties","invokeAttentiveDebugHelper","exportDebugLogs","registerForPushNotifications","getPushAuthorizationStatus","registerDeviceToken","token","authorizationStatus","registerDeviceTokenWithCallback","callback","handleRegularOpen","console","log","handlePushOpened","userInfo","applicationState","handleForegroundNotification","handleForegroundPush","handlePushOpen","getInitialPushNotification","result"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":"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BAA0B,CAAC,CAAC;AAC7D;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASC,mBAAmBA,CAC1BC,KAAa,EACbC,mBAA4C,EACtC;EACN3C,uBAAuB,CAACyC,mBAAmB,CAACC,KAAK,EAAEC,mBAAmB,CAAC;AACzE;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASC,+BAA+BA,CACtCF,KAAa,EACbC,mBAA4C,EAC5CE,QAKS,EACH;EACN7C,uBAAuB,CAAC4C,+BAA+B,CACrDF,KAAK,EACLC,mBAAmB,EACnBE,QACF,CAAC;AACH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASC,iBAAiBA,CAACH,mBAA4C,EAAQ;EAC7EI,OAAO,CAACC,GAAG,CAAC,6DAA6D,CAAC;EAC1ED,OAAO,CAACC,GAAG,CAAC,4BAA4BL,mBAAmB,EAAE,CAAC;EAC9DI,OAAO,CAACC,GAAG,CACT,mEACF,CAAC;EAEDhD,uBAAuB,CAAC8C,iBAAiB,CAACH,mBAAmB,CAAC;EAE9DI,OAAO,CAACC,GAAG,CAAC,mDAAmD,CAAC;AAClE;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASC,gBAAgBA,CACvBC,QAAkC,EAClCC,gBAAkC,EAClCR,mBAA4C,EACtC;EACN3C,uBAAuB,CAACiD,gBAAgB,CACtCC,QAAQ,EACRC,gBAAgB,EAChBR,mBACF,CAAC;AACH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASS,4BAA4BA,CACnCF,QAAkC,EAC5B;EACNlD,uBAAuB,CAACoD,4BAA4B,CAACF,QAAkB,CAAC;AAC1E;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASG,oBAAoBA,CAC3BH,QAAkC,EAClCP,mBAA4C,EACtC;EACN3C,uBAAuB,CAACqD,oBAAoB,CAC1CH,QAAQ,EACRP,mBACF,CAAC;AACH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASW,cAAcA,CACrBJ,QAAkC,EAClCP,mBAA4C,EACtC;EACN3C,uBAAuB,CAACsD,cAAc,CACpCJ,QAAQ,EACRP,mBACF,CAAC;AACH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,eAAeY,0BAA0BA,CAAA,EAG/B;EACR,MAAMC,MAAM,GAAG,MAAMxD,uBAAuB,CAACuD,0BAA0B,CAAC,CAAC;EACzE,OAAOC,MAAM;AACf","ignoreList":[]}

package/lib/module/index.js

@@ -310,17 +310,16 @@ function handleForegroundNotification(userInfo) {
 
 /**
  * Handle a push notification when the app is in the foreground (active state).
- * This is the React Native equivalent of the native iOS handleForegroundPush method.
  *
  * Call this when you receive a notification response and the app state is 'active'.
- * This is part of implementing the native iOS pattern:
- * ```swift
- * case .active:
- *   self.attentiveSdk?.handleForegroundPush(response: response, authorizationStatus: authStatus)
- * ```
  *
- * On iOS, this properly tracks foreground push notifications.
- * On Android, registers the FCM token when provided by the host app.
+ * **iOS prerequisite:** Your AppDelegate's
+ * `userNotificationCenter(_:didReceive:withCompletionHandler:)` must call
+ * `AttentiveSDKManager.shared.handleNotificationResponse(response)` so that
+ * the SDK can cache the `UNNotificationResponse` required by the native iOS SDK.
+ * Without that one line of native code, this function cannot track the event.
+ *
+ * On Android, this tracks the foreground push as a custom event.
  *
  * @param userInfo - The notification payload from the push notification
  * @param authorizationStatus - Current push authorization status
@@ -343,17 +342,16 @@ function handleForegroundPush(userInfo, authorizationStatus) {
 
 /**
  * Handle when a push notification is opened by the user (app in background/inactive state).
- * This is the React Native equivalent of the native iOS handlePushOpen method.
  *
  * Call this when you receive a notification response and the app state is 'background' or 'inactive'.
- * This is part of implementing the native iOS pattern:
- * ```swift
- * case .background, .inactive:
- *   self.attentiveSdk?.handlePushOpen(response: response, authorizationStatus: authStatus)
- * ```
  *
- * On iOS, this properly tracks push notification opens.
- * On Android, registers the FCM token when provided by the host app.
+ * **iOS prerequisite:** Your AppDelegate's
+ * `userNotificationCenter(_:didReceive:withCompletionHandler:)` must call
+ * `AttentiveSDKManager.shared.handleNotificationResponse(response)` so that
+ * the SDK can cache the `UNNotificationResponse` required by the native iOS SDK.
+ * Without that one line of native code, this function cannot track the event.
+ *
+ * On Android, this tracks the push open as a custom event.
  *
  * @param userInfo - The notification payload from the push notification
  * @param authorizationStatus - Current push authorization status