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

package/README.md

@@ -81,7 +81,12 @@ 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.
+On Android, `AttentiveSdk.initialize()` **must** be called from your `Application.onCreate()` in native Kotlin/Java code. There are two reasons for this:
+
+1. **Lifecycle observers must be registered before the React Native bridge is ready.** Internally, the SDK creates an `AppLaunchTracker` that calls `lifecycle.addObserver()` on the `ProcessLifecycleOwner`. If initialization happens after the bridge starts, early app-launch events can be missed.
+2. **`lifecycle.addObserver()` requires the main thread.** AndroidX enforces this with an `IllegalStateException` if called from a background thread. `Application.onCreate()` is guaranteed by the Android system to run on the main thread, so calling `initialize` there satisfies this requirement automatically — no extra threading machinery needed.
+
+> **Do not** call `AttentiveSdk.initialize()` from a background thread or a coroutine dispatcher other than `Dispatchers.Main`. Doing so will throw an `IllegalStateException` from inside the AndroidX Lifecycle library.
 
 Add the following to your `MainApplication.kt` (or `MainApplication.java`):
 
@@ -90,7 +95,6 @@ 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 {
 
@@ -109,15 +113,14 @@ class MainApplication : Application(), ReactApplication {
             .logLevel(AttentiveLogLevel.VERBOSE)
             .build()
 
-        // AttentiveSdk.initialize registers lifecycle observers and must run on the main thread.
-        UiThreadUtil.runOnUiThread {
-            AttentiveSdk.initialize(config)
-        }
+        // Application.onCreate() is always called on the main thread by the Android system,
+        // so no thread-switching wrapper is needed here.
+        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.
+After the native initialization, all other SDK operations (`identify`, `recordAddToCartEvent`, `recordPurchaseEvent`, etc.) are called from TypeScript as normal on both platforms.
 
 > **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.
 
@@ -218,7 +221,7 @@ Attentive.identify({phone: '+15556667777'};)
 
 ### Push Notifications (iOS and Android)
 
-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.
+The SDK supports push notification integration on both iOS (APNs) and Android (FCM). The following sections cover iOS-specific setup flows. On Android, push notification integration is handled entirely in native Kotlin/Java code — see [App Events on Android](#app-events-on-android) for details.
 
 > **iOS — required setup:** Your AppDelegate **must** forward notification
 > responses to the SDK for push tracking to work. Add this single line to your
@@ -243,22 +246,9 @@ The SDK supports push notification integration on both iOS (APNs) and Android (r
 
 ### App Events on Android
 
-This section describes how to implement Attentive app events on Android so they behave like the iOS flow: **regular app opens** (launch and resume from background) and **notification permission** are handled using the SDK’s native Android APIs. You can add FCM token registration and push open handling when your app uses Firebase Cloud Messaging.
+On Android, **regular app open and foreground events are handled automatically** by the native Android SDK once `AttentiveSdk.initialize()` is called from `Application.onCreate()` (see [Android Native Initialization](#android--initialize-from-native-code)). The lifecycle observers registered during initialization (e.g. `AppLaunchTracker`) take care of this transparently — there is no need to manually call `handleRegularOpen` or subscribe to `AppState` changes.
 
-| SDK method | Purpose on Android |
-|------------|--------------------|
-| `getPushAuthorizationStatus()` | Returns `authorized`, `denied`, or `notDetermined` (uses `POST_NOTIFICATIONS` on API 33+). Use before `handleRegularOpen` so tracking uses the correct status. |
-| `registerForPushNotifications()` | Requests `POST_NOTIFICATIONS` on Android 13+; no-op on older versions. |
-| `handleRegularOpen(authStatus)` | Tracks a regular app open (launch or return to foreground). Call after `identify()` and pass the result of `getPushAuthorizationStatus()`. |
-| `registerDeviceToken` / `registerDeviceTokenWithCallback` | Optional. Register your FCM token when using Firebase Cloud Messaging. |
-| `handlePushOpen` / `handleForegroundPush` | Optional. Call when the user opens a notification or receives one in the foreground. |
-
-#### Overview
-
-- **Regular app open** – Call `handleRegularOpen(authorizationStatus)` when the app is opened (launch or returning to foreground). The SDK uses this for tracking and the `/mtctrl` endpoint.
-- **Permission status** – On Android 13+ (API 33+), notification permission is `POST_NOTIFICATIONS`. The SDK exposes `getPushAuthorizationStatus()` so you can pass the correct status into `handleRegularOpen`.
-- **Requesting permission** – Call `registerForPushNotifications()` to trigger the system permission dialog on Android 13+; it is a no-op on older versions.
-- **Order of operations** – Always call `identify()` before any `handleRegularOpen()` so the SDK has user context for network requests.
+The only TypeScript-side step required on Android is calling `identify()` with any available user identifiers as early as possible in your app’s lifecycle (e.g. in the root component `useEffect`).
 
 #### Prerequisites
 
@@ -271,115 +261,78 @@ This section describes how to implement Attentive app events on Android so they
 </manifest>
 ```
 
-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)
+2. **Native initialization** – The SDK must be initialized from `Application.onCreate()` on Android (see [Android Native Initialization](#android--initialize-from-native-code) above). App open and lifecycle events are then tracked automatically.
 
-Right after `identify()`, do the following for the Android path:
+#### TypeScript setup (Android)
 
-1. Get the current notification authorization status with `getPushAuthorizationStatus()`.
-2. Call `handleRegularOpen(authStatus)` with that status.
-3. Optionally call `registerForPushNotifications()` to prompt for permission (Android 13+).
+After native initialization, the only required TypeScript call is `identify()`:
 
 ```typescript
 import { Platform } from 'react-native';
-import {
-  initialize,
-  identify,
-  getPushAuthorizationStatus,
-  registerForPushNotifications,
-  handleRegularOpen,
-  type AttentiveSdkConfiguration,
-  type PushAuthorizationStatus,
-} from 'attentive-react-native-sdk';
+import { initialize, identify } from 'attentive-react-native-sdk';
 
 // Inside your root component (e.g. App.tsx useEffect):
-
-// 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') {
-  getPushAuthorizationStatus()
-    .then((authStatus: PushAuthorizationStatus) => {
-      handleRegularOpen(authStatus);
-    })
-    .catch(() => {
-      handleRegularOpen('authorized'); // fallback
-    });
-  registerForPushNotifications(); // Shows permission dialog on Android 13+
-}
 ```
 
-#### 2. When app returns to foreground (Android)
+#### Push notifications on Android (FCM)
 
-Subscribe to `AppState` and, when the app becomes `active`, get the current status and call `handleRegularOpen` again:
+On Android, FCM token registration and push notification handling are managed natively in Kotlin/Java. This gives you full control over the Firebase Messaging lifecycle and ensures events are tracked before the React Native bridge initialises.
 
-```typescript
-import { AppState } from 'react-native';
-import { getPushAuthorizationStatus, handleRegularOpen } from 'attentive-react-native-sdk';
-import type { PushAuthorizationStatus } from 'attentive-react-native-sdk';
-
-const subscription = AppState.addEventListener('change', (nextAppState) => {
-  if (nextAppState === 'active' && Platform.OS === 'android') {
-    getPushAuthorizationStatus()
-      .then((authStatus: PushAuthorizationStatus) => {
-        handleRegularOpen(authStatus);
-      })
-      .catch(() => {
-        handleRegularOpen('authorized');
-      });
-  }
-});
-
-// Cleanup on unmount:
-return () => subscription.remove();
-```
+Add Firebase Cloud Messaging to your app following the [Firebase Android setup guide](https://firebase.google.com/docs/cloud-messaging/android/client), then handle token registration and notification events in your native `FirebaseMessagingService`:
 
-#### 3. Optional: Register FCM token (Android)
+```kotlin
+import com.attentive.androidsdk.AttentiveSdk
+import com.google.firebase.messaging.FirebaseMessagingService
+import com.google.firebase.messaging.RemoteMessage
 
-**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.
+class AttentiveMessagingService : FirebaseMessagingService() {
 
-**Alternative (token from JS):** If you obtain the FCM token elsewhere (e.g. Firebase Messaging), use `registerDeviceTokenWithCallback` and then call `handleRegularOpen` in the callback:
+    override fun onNewToken(token: String) {
+        super.onNewToken(token)
+        // Register the FCM token with the Attentive SDK
+        AttentiveSdk.registerDeviceToken(token)
+    }
 
-```typescript
-import { registerDeviceTokenWithCallback, handleRegularOpen } from 'attentive-react-native-sdk';
-
-getPushAuthorizationStatus().then((authStatus) => {
-  registerDeviceTokenWithCallback(
-    fcmToken,
-    authStatus,
-    (data, url, response, error) => {
-      if (error) {
-        console.error('Attentive token registration failed', error);
-      }
-      handleRegularOpen(authStatus);
+    override fun onMessageReceived(remoteMessage: RemoteMessage) {
+        super.onMessageReceived(remoteMessage)
+        // Handle foreground push delivery
+        AttentiveSdk.handleForegroundPush(remoteMessage.data)
     }
-  );
-});
+}
 ```
 
-#### 4. Optional: Handle notification opens and foreground (Android)
+For notification opens (when the user taps a push notification), handle the intent in your main `Activity`:
 
-If you handle FCM messages (e.g. with `@react-native-firebase/messaging`), you can report notification opens and foreground receives the same way as on iOS:
+```kotlin
+import com.attentive.androidsdk.AttentiveSdk
 
-- **User opened notification (background/inactive):** `handlePushOpen(payload, authorizationStatus)`
-- **Notification received while app in foreground:** `handleForegroundPush(payload, authorizationStatus)`
+class MainActivity : ReactActivity() {
 
-Get `authorizationStatus` via `getPushAuthorizationStatus()` when handling the event.
+    override fun onResume() {
+        super.onResume()
+        intent?.let { AttentiveSdk.handlePushOpen(it) }
+    }
+}
+```
 
-#### Complete Android flow (reference)
+Declare the service in your `AndroidManifest.xml`:
 
-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:
+```xml
+<service
+    android:name=".AttentiveMessagingService"
+    android:exported="false">
+    <intent-filter>
+        <action android:name="com.google.firebase.MESSAGING_EVENT" />
+    </intent-filter>
+</service>
+```
 
-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()`.
+Refer to the [Attentive Android SDK documentation](https://github.com/attentive-mobile/attentive-android-sdk) for the full list of native APIs available for push notification integration.
 
 ---
 
@@ -393,9 +346,9 @@ import { registerForPushNotifications } from 'attentive-react-native-sdk';
 registerForPushNotifications();
 ```
 
-#### Register Device Token (iOS: APNs / Android: FCM)
+#### Register Device Token (iOS)
 
-When your app receives a device token (APNs on iOS, FCM on Android), register it with the Attentive backend:
+When your iOS app receives an APNs device token, register it with the Attentive backend:
 
 ```typescript
 import { registerDeviceToken } from 'attentive-react-native-sdk';
@@ -412,7 +365,7 @@ The `authorizationStatus` parameter should be one of:
 - `'provisional'` - Provisional authorization (quiet notifications)
 - `'ephemeral'` - App Clip notifications
 
-#### Handle Push Notification Opens (iOS and Android)
+#### Handle Push Notification Opens (iOS)
 
 When a user taps on a push notification, track the event:
 
@@ -428,7 +381,7 @@ handlePushOpened(
 );
 ```
 
-#### Handle Foreground Notifications (iOS and Android)
+#### Handle Foreground Notifications (iOS)
 
 When a notification arrives while the app is in the foreground:
 
@@ -523,9 +476,8 @@ func application(
 ```
 
 **Documentation:**
-- [Push Token Registration Guide](./PUSH_TOKEN_REGISTRATION_GUIDE.md) - Detailed guide for callback-based registration
-- [AppDelegate Callback Example](./APPDELEGATE_CALLBACK_EXAMPLE.md) - Complete AppDelegate implementation
-- [Push Notifications Setup](./PUSH_NOTIFICATIONS_SETUP.md) - General push notification setup
+- [Push Notifications Integration Guide](./docs/PUSH_NOTIFICATIONS_INTEGRATION.md) - Callback-based registration, complete AppDelegate implementation, Android and iOS token flow
+- [Push Notifications Setup](./docs/PUSH_NOTIFICATIONS_SETUP.md) - Apple Developer Portal, APNs certificates, and TestFlight configuration
 - [iOS Native SDK documentation](https://github.com/attentive-mobile/attentive-ios-sdk) - Native SDK reference
 
-For a full Android implementation (app launch, foreground, permission, and optional FCM), see the **[App Events on Android](#app-events-on-android)** section above.
+For Android push notification integration, see the **[App Events on Android](#app-events-on-android)** section above.

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

@@ -88,7 +88,7 @@ class AttentiveReactNativeSdkModule(reactContext: ReactApplicationContext) :
     ) {
         debugHelper.initialize(enableDebugger)
 
-        Log.w(
+        Log.d(
             TAG,
             "[AttentiveSDK] initialize() called from TypeScript is a NO-OP on Android. " +
             "You must call AttentiveSdk.initialize(config) from your Application.onCreate() " +
@@ -187,17 +187,7 @@ class AttentiveReactNativeSdkModule(reactContext: ReactApplicationContext) :
         val itemsList = buildItems(items)
         val productViewEvent = ProductViewEvent.Builder().items(itemsList).deeplink(deeplink).build()
 
-        try {
-            AttentiveSdk.recordEvent(productViewEvent)
-        } catch (e: Exception) {
-            Log.e(
-                TAG,
-                "[AttentiveSDK] recordProductViewEvent failed — SDK may not be initialized. " +
-                "On Android, call AttentiveSdk.initialize(config) from Application.onCreate() " +
-                "before recording events. Error: ${e.message}"
-            )
-            return
-        }
+        if (!recordEventSafely("recordProductViewEvent") { AttentiveSdk.recordEvent(productViewEvent) }) return
 
         if (debugHelper.isDebuggingEnabled()) {
             val debugData = mutableMapOf<String, Any>()
@@ -227,17 +217,7 @@ class AttentiveReactNativeSdkModule(reactContext: ReactApplicationContext) :
         }
         val purchaseEvent = purchaseBuilder.build()
 
-        try {
-            AttentiveSdk.recordEvent(purchaseEvent)
-        } catch (e: Exception) {
-            Log.e(
-                TAG,
-                "[AttentiveSDK] recordPurchaseEvent failed — SDK may not be initialized. " +
-                "On Android, call AttentiveSdk.initialize(config) from Application.onCreate() " +
-                "before recording events. Error: ${e.message}"
-            )
-            return
-        }
+        if (!recordEventSafely("recordPurchaseEvent") { AttentiveSdk.recordEvent(purchaseEvent) }) return
 
         if (debugHelper.isDebuggingEnabled()) {
             val debugData = mutableMapOf<String, Any>()
@@ -260,17 +240,7 @@ class AttentiveReactNativeSdkModule(reactContext: ReactApplicationContext) :
         val itemsList = buildItems(items)
         val addToCartEvent = AddToCartEvent.Builder().items(itemsList).deeplink(deeplink).build()
 
-        try {
-            AttentiveSdk.recordEvent(addToCartEvent)
-        } catch (e: Exception) {
-            Log.e(
-                TAG,
-                "[AttentiveSDK] recordAddToCartEvent failed — SDK may not be initialized. " +
-                "On Android, call AttentiveSdk.initialize(config) from Application.onCreate() " +
-                "before recording events. Error: ${e.message}"
-            )
-            return
-        }
+        if (!recordEventSafely("recordAddToCartEvent") { AttentiveSdk.recordEvent(addToCartEvent) }) return
 
         if (debugHelper.isDebuggingEnabled()) {
             val debugData = mutableMapOf<String, Any>()
@@ -290,17 +260,7 @@ class AttentiveReactNativeSdkModule(reactContext: ReactApplicationContext) :
         val propertiesMap = convertToStringMap(properties.toHashMap())
         val customEvent = CustomEvent.Builder().type(type).properties(propertiesMap).build()
 
-        try {
-            AttentiveSdk.recordEvent(customEvent)
-        } catch (e: Exception) {
-            Log.e(
-                TAG,
-                "[AttentiveSDK] recordCustomEvent failed — SDK may not be initialized. " +
-                "On Android, call AttentiveSdk.initialize(config) from Application.onCreate() " +
-                "before recording events. Error: ${e.message}"
-            )
-            return
-        }
+        if (!recordEventSafely("recordCustomEvent") { AttentiveSdk.recordEvent(customEvent) }) return
 
         if (debugHelper.isDebuggingEnabled()) {
             val debugData = mutableMapOf<String, Any>()
@@ -844,6 +804,36 @@ class AttentiveReactNativeSdkModule(reactContext: ReactApplicationContext) :
      * @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()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attentive-mobile/attentive-react-native-sdk",
-  "version": "2.0.0-beta.7",
+  "version": "2.0.0-beta.8",
   "description": "React Native Module for the Attentive SDK",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",

package/ios/AttentiveReactNativeSdk.xcodeproj/project.xcworkspace/contents.xcworkspacedata

@@ -1,7 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<Workspace
-   version = "1.0">
-   <FileRef
-      location = "self:">
-   </FileRef>
-</Workspace>

package/ios/AttentiveReactNativeSdk.xcodeproj/xcuserdata/zheref.xcuserdatad/xcschemes/xcschememanagement.plist

@@ -1,14 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-	<key>SchemeUserState</key>
-	<dict>
-		<key>AttentiveReactNativeSdk.xcscheme_^#shared#^_</key>
-		<dict>
-			<key>orderHint</key>
-			<integer>0</integer>
-		</dict>
-	</dict>
-</dict>
-</plist>