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

package/README.md

@@ -68,12 +68,59 @@ See [DEBUGGING.md](./DEBUGGING.md) for detailed information about debugging feat
 
 ### Initialize the SDK
 
+> **Platform difference:** iOS and Android have different initialization requirements.
+
+#### iOS — Initialize from TypeScript
+
+On iOS, call `initialize` from TypeScript as early as possible (e.g. the root `App` component's `useEffect`):
+
 ```typescript
-// 'initialize' should be called as soon as possible after the app starts (see the example app for an example of initializing the SDK in the App element)
-// Note: 'initialize' should only be called once per app session - if you call it multiple times it will throw an exception
+// Called once per app session, before any other SDK operations.
 Attentive.initialize(config);
 ```
 
+#### Android — Initialize from Native Code
+
+On Android, `AttentiveSdk.initialize()` **must** be called from your `Application.onCreate()` in native Kotlin/Java code. This is required so that lifecycle observers (e.g. `AppLaunchTracker`) are registered before the React Native bridge is ready. Calling `initialize()` from TypeScript on Android is a **no-op** — the SDK will not be started and all subsequent event calls will fail.
+
+Add the following to your `MainApplication.kt` (or `MainApplication.java`):
+
+```kotlin
+import android.app.Application
+import com.attentive.androidsdk.AttentiveConfig
+import com.attentive.androidsdk.AttentiveSdk
+import com.attentive.androidsdk.AttentiveLogLevel
+import com.facebook.react.bridge.UiThreadUtil
+
+class MainApplication : Application(), ReactApplication {
+
+    override fun onCreate() {
+        super.onCreate()
+        // ... your existing setup ...
+        initAttentiveSDK()
+    }
+
+    private fun initAttentiveSDK() {
+        val config = AttentiveConfig.Builder()
+            .applicationContext(this)
+            .domain("YOUR_ATTENTIVE_DOMAIN")
+            .mode(AttentiveConfig.Mode.PRODUCTION) // or Mode.DEBUG for testing
+            .skipFatigueOnCreatives(false)
+            .logLevel(AttentiveLogLevel.VERBOSE)
+            .build()
+
+        // AttentiveSdk.initialize registers lifecycle observers and must run on the main thread.
+        UiThreadUtil.runOnUiThread {
+            AttentiveSdk.initialize(config)
+        }
+    }
+}
+```
+
+After the native initialization, all other SDK operations (`identify`, `recordAddToCartEvent`, `recordPurchaseEvent`, etc.) are called from TypeScript as normal on both platforms. The TypeScript `initialize()` call is still required on iOS but is safely ignored on Android.
+
+> **Tip:** If you see `[AttentiveSDK] recordAddToCartEvent failed — SDK may not be initialized` in your Android logcat, it means `AttentiveSdk.initialize()` was not called from native code before the event was recorded. Check your `Application.onCreate()` setup.
+
 ### Destroy the creative
 
 ```typescript
@@ -173,6 +220,25 @@ Attentive.identify({phone: '+15556667777'};)
 
 The SDK supports push notification integration on both iOS (APNs) and Android (runtime permission + optional FCM). The following sections cover iOS-specific flows and a full **App events on Android** implementation that mirrors the behavior of the [Bonni](https://github.com/attentive-mobile/attentive-react-native-sdk/tree/main/Bonni) example app.
 
+> **iOS — required setup:** Your AppDelegate **must** forward notification
+> responses to the SDK for push tracking to work. Add this single line to your
+> `userNotificationCenter(_:didReceive:withCompletionHandler:)`:
+>
+> ```swift
+> AttentiveSDKManager.shared.handleNotificationResponse(response)
+> ```
+>
+> Without this, push open and foreground push events **will not be tracked** on
+> iOS. See [iOS AppDelegate Integration](#ios-appdelegate-integration) for full
+> details.
+>
+> **Migrating from an earlier version?** If you previously called
+> `AttentiveSDKManager.shared.handleForegroundPush(response:authorizationStatus:)`
+> or `AttentiveSDKManager.shared.handlePushOpen(response:authorizationStatus:)`
+> directly from your AppDelegate, **replace** that code with the single
+> `handleNotificationResponse` call above. Using both will result in
+> double-tracked events. The old methods are now deprecated.
+
 ---
 
 ### App Events on Android
@@ -205,7 +271,7 @@ This section describes how to implement Attentive app events on Android so they
 </manifest>
 ```
 
-2. **Initialize and identify first** – In your app entry (e.g. root component `useEffect`), call `initialize(config)` and `identify(identifiers)` before any push or app-event logic.
+2. **Initialize and identify first** – The SDK must be initialized natively from `Application.onCreate()` on Android (see [Android Native Initialization](#android--initialize-from-native-code) above). Then, in your app entry (e.g. root component `useEffect`), call `identify(identifiers)` before any push or app-event logic.
 
 #### 1. On app launch (Android)
 
@@ -228,7 +294,13 @@ import {
 } from 'attentive-react-native-sdk';
 
 // Inside your root component (e.g. App.tsx useEffect):
-initialize(config);
+
+// iOS only: initialize from TypeScript.
+// Android: initialization must be done natively from Application.onCreate() — see README.
+if (Platform.OS === 'ios') {
+  initialize(config);
+}
+
 identify({ email: 'user@example.com', clientUserId: 'id-123' });
 
 if (Platform.OS === 'android') {
@@ -270,12 +342,13 @@ return () => subscription.remove();
 
 #### 3. Optional: Register FCM token (Android)
 
-If your app uses Firebase Cloud Messaging and you have an FCM token, register it with the Attentive backend and then call `handleRegularOpen` in the callback (same pattern as iOS):
+**Recommended:** This React Native SDK’s Android native module depends on Attentive Android SDK **2.1.1**, which exposes `AttentiveSdk.getPushTokenWithCallback`. Calling `registerForPushNotifications()` from JS triggers that API: the SDK requests permission (when needed), fetches the FCM token, and registers it with Attentive. No separate native code is required.
+
+**Alternative (token from JS):** If you obtain the FCM token elsewhere (e.g. Firebase Messaging), use `registerDeviceTokenWithCallback` and then call `handleRegularOpen` in the callback:
 
 ```typescript
 import { registerDeviceTokenWithCallback, handleRegularOpen } from 'attentive-react-native-sdk';
 
-// When you receive the FCM token (e.g. from Firebase Messaging):
 getPushAuthorizationStatus().then((authStatus) => {
   registerDeviceTokenWithCallback(
     fcmToken,
@@ -303,7 +376,7 @@ Get `authorizationStatus` via `getPushAuthorizationStatus()` when handling the e
 
 The [Bonni](https://github.com/attentive-mobile/attentive-react-native-sdk/tree/main/Bonni) example app ([App.tsx](https://github.com/attentive-mobile/attentive-react-native-sdk/blob/main/Bonni/App.tsx)) implements the full flow:
 
-1. **Launch:** `initialize` → `identify` → (Android) `getPushAuthorizationStatus()` → `handleRegularOpen(authStatus)` → `registerForPushNotifications()`.
+1. **Launch:** Native `AttentiveSdk.initialize(config)` (from `Application.onCreate()`) → TypeScript `identify` → `getPushAuthorizationStatus()` → `handleRegularOpen(authStatus)` → `registerForPushNotifications()`.
 2. **Foreground:** `AppState.addEventListener('change', …)` → when `active` and Android → `getPushAuthorizationStatus()` → `handleRegularOpen(authStatus)`.
 3. **Optional:** When FCM token is available → `registerDeviceTokenWithCallback(token, authStatus, callback)` → in callback call `handleRegularOpen(authStatus)`.
 4. **Optional:** When user opens a notification or receives one in foreground → `handlePushOpen` / `handleForegroundPush` with payload and status from `getPushAuthorizationStatus()`.
@@ -372,7 +445,40 @@ For proper push notification integration, your iOS AppDelegate needs to:
 
 1. Request notification permissions via the SDK
 2. Implement `application:didRegisterForRemoteNotificationsWithDeviceToken:` to register the token
-3. Implement `UNUserNotificationCenterDelegate` methods to handle notification events
+3. **Forward notification responses to the SDK for push-open tracking**
+
+##### Push Open Tracking (Required)
+
+Add **one line** to your AppDelegate's `didReceive` handler so the SDK can track
+push opens and foreground push events. Without this, `handlePushOpen()` and
+`handleForegroundPush()` called from JavaScript will not be able to track events
+on iOS (the native SDK requires a `UNNotificationResponse` which cannot cross the
+React Native bridge).
+
+```swift
+// In AppDelegate.swift — UNUserNotificationCenterDelegate
+func userNotificationCenter(
+    _ center: UNUserNotificationCenter,
+    didReceive response: UNNotificationResponse,
+    withCompletionHandler completionHandler: @escaping () -> Void
+) {
+    // Attentive push tracking (handles app-state + auth status automatically)
+    AttentiveSDKManager.shared.handleNotificationResponse(response)
+
+    // Forward to your push library (e.g. RNCPushNotificationIOS) for JS events
+    RNCPushNotificationIOS.didReceive(response)
+    completionHandler()
+}
+```
+
+`handleNotificationResponse` automatically:
+- Detects whether the app is in the foreground or background
+- Fetches the current authorization status
+- Calls the correct native SDK method (`handlePushOpen` or `handleForegroundPush`)
+- Caches the response so the JS-side `handlePushOpen()` / `handleForegroundPush()` calls
+  are fulfilled without double-tracking
+- **Cold-launch safe:** If the user taps a push while the app is killed, the
+  response is cached and automatically tracked once the SDK initializes
 
 ##### Callback-Based Registration (Recommended)
 
@@ -389,13 +495,13 @@ func application(
 ) {
     UNUserNotificationCenter.current().getNotificationSettings { settings in
         let authStatus = settings.authorizationStatus
-        
+
         // Get SDK instance with proper type
         guard let attentiveSdk = AttentiveSDKManager.shared.sdk as? ATTNNativeSDK else {
             print("[Attentive] SDK not initialized")
             return
         }
-        
+
         // Register device token with callback
         attentiveSdk.registerDeviceToken(
             deviceToken,
@@ -406,7 +512,7 @@ func application(
                     if let error = error {
                         print("[Attentive] Registration failed: \(error.localizedDescription)")
                     }
-                    
+
                     // Trigger regular open event after registration
                     attentiveSdk.handleRegularOpen(authorizationStatus: authStatus)
                 }

package/android/build.gradle

@@ -82,7 +82,10 @@ dependencies {
   // For > 0.71, this will be replaced by `com.facebook.react:react-android:$version` by react gradle plugin
   //noinspection GradleDynamicVersion
   implementation "com.facebook.react:react-native:+"
-  implementation 'com.attentive:attentive-android-sdk:1.0.1'
+  // Use `api` so that the Attentive Android SDK types (AttentiveSdk, CustomEvent, etc.)
+  // are visible to app-level code (e.g. Bonni's AttentiveFirebaseMessagingService) that
+  // depends on this library and needs to call the SDK directly from native components.
+  api 'com.attentive:attentive-android-sdk:2.1.3'
   implementation "org.jetbrains.kotlin:kotlin-stdlib:1.9.10"
   implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.9.10"))
   

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

@@ -0,0 +1,60 @@
+package com.attentivereactnativesdk
+
+/**
+ * In-process store for a pending initial push notification payload.
+ *
+ * When the user taps an FCM notification while the app is in the killed state,
+ * Android launches the app's main activity before the React Native bridge is
+ * initialised. The notification payload is written here by the host app's
+ * `MainActivity` and consumed exactly once by [AttentiveReactNativeSdkModule.getInitialPushNotification]
+ * after the JS layer is ready.
+ *
+ * ## Usage pattern
+ *
+ * ```kotlin
+ * // In host app's MainActivity.onCreate:
+ * intent?.extras?.let { extras ->
+ *     val payload = // … extract FCM data …
+ *     AttentiveNotificationStore.setPendingInitialNotification(payload)
+ * }
+ * ```
+ *
+ * ```typescript
+ * // In JS (App.tsx), after initialize():
+ * const initial = await getInitialPushNotification()
+ * if (initial) handlePushOpen(initial, authStatus)
+ * ```
+ *
+ * Thread-safety: the two public methods are `@Synchronized` so concurrent access
+ * from the main UI thread (writer) and the JS bridge thread (reader) is safe.
+ */
+object AttentiveNotificationStore {
+
+    @Volatile
+    private var pendingInitialNotification: Map<String, String>? = null
+
+    /**
+     * Stores [payload] as the pending initial push notification.
+     *
+     * Replaces any previously stored value (only one initial notification is tracked at a time).
+     *
+     * @param payload A map of string key-value pairs representing the notification data.
+     */
+    @Synchronized
+    fun setPendingInitialNotification(payload: Map<String, String>) {
+        pendingInitialNotification = payload
+    }
+
+    /**
+     * Returns the stored initial push notification payload and clears it atomically,
+     * ensuring the payload is delivered to the JS layer exactly once.
+     *
+     * @return The stored payload map, or `null` if no initial notification is pending.
+     */
+    @Synchronized
+    fun getAndClear(): Map<String, String>? {
+        val pending = pendingInitialNotification
+        pendingInitialNotification = null
+        return pending
+    }
+}

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

@@ -26,8 +26,8 @@ object AttentivePushHelper {
     /**
      * Authorization status values aligned with iOS push authorization for use in handleRegularOpen etc.
      * - "authorized" – user has granted notification permission (or API < 33)
-     * - "denied" – user denied or permission not granted
-     * - "notDetermined" – not yet requested (API 33+ only)
+     * - "denied" – user was asked and denied (API 33+, when determinable via activity)
+     * - "notDetermined" – not yet requested, or unable to distinguish (API 33+ only)
      */
     const val STATUS_AUTHORIZED = "authorized"
     const val STATUS_DENIED = "denied"
@@ -36,14 +36,18 @@ object AttentivePushHelper {
     /**
      * Returns the current push notification authorization status.
      *
-     * On API 33+: uses [android.permission.POST_NOTIFICATIONS].
+     * On API 33+: uses [android.permission.POST_NOTIFICATIONS]. When permission is not granted,
+     * uses [activity] (when provided) and [ActivityCompat.shouldShowRequestPermissionRationale]
+     * to distinguish "denied" (user was asked and declined) from "notDetermined" (not yet asked).
      * On API < 33: returns [STATUS_AUTHORIZED] (no runtime permission required).
      *
      * @param context Application or Activity context
+     * @param activity Current activity, or null. When non-null on API 33+, used to detect
+     *   "denied" vs "notDetermined" so downstream logic and analytics are correct for denied users.
      * @return One of [STATUS_AUTHORIZED], [STATUS_DENIED], or [STATUS_NOT_DETERMINED]
      */
     @JvmStatic
-    fun getAuthorizationStatus(context: Context): String {
+    fun getAuthorizationStatus(context: Context, activity: Activity? = null): String {
         if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
             // API 32 and below: notification permission not required at runtime
             return STATUS_AUTHORIZED
@@ -51,9 +55,13 @@ object AttentivePushHelper {
         return when (ContextCompat.checkSelfPermission(context, android.Manifest.permission.POST_NOTIFICATIONS)) {
             PackageManager.PERMISSION_GRANTED -> STATUS_AUTHORIZED
             else -> {
-                // Not granted. Without an Activity we cannot distinguish "denied" vs "not yet asked".
-                // Return notDetermined so the app can call registerForPushNotifications to request.
-                STATUS_NOT_DETERMINED
+                // Not granted. Use shouldShowRequestPermissionRationale when we have an Activity
+                // so we do not report "denied" users as "notDetermined" (fixes prompt-gating and analytics).
+                if (activity != null && ActivityCompat.shouldShowRequestPermissionRationale(activity, android.Manifest.permission.POST_NOTIFICATIONS)) {
+                    STATUS_DENIED
+                } else {
+                    STATUS_NOT_DETERMINED
+                }
             }
         }
     }