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

package/README.md

@@ -169,11 +169,149 @@ Attentive.identify({phone: '+15556667777'};)
 //   phone: '+15556667777'
 ```
 
-### Push Notifications (iOS Only)
+### Push Notifications (iOS and Android)
 
-The SDK supports push notification integration for iOS. Android support is planned for a future release.
+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.
 
-#### Request Push Permission
+---
+
+### 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.
+
+| 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.
+
+#### Prerequisites
+
+1. **AndroidManifest** – Declare the notification permission for Android 13+:
+
+```xml
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <!-- other permissions -->
+</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.
+
+#### 1. On app launch (Android)
+
+Right after `identify()`, do the following for the Android path:
+
+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+).
+
+```typescript
+import { Platform } from 'react-native';
+import {
+  initialize,
+  identify,
+  getPushAuthorizationStatus,
+  registerForPushNotifications,
+  handleRegularOpen,
+  type AttentiveSdkConfiguration,
+  type PushAuthorizationStatus,
+} from 'attentive-react-native-sdk';
+
+// Inside your root component (e.g. App.tsx useEffect):
+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)
+
+Subscribe to `AppState` and, when the app becomes `active`, get the current status and call `handleRegularOpen` again:
+
+```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();
+```
+
+#### 3. Optional: Register FCM token (Android)
+
+**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';
+
+getPushAuthorizationStatus().then((authStatus) => {
+  registerDeviceTokenWithCallback(
+    fcmToken,
+    authStatus,
+    (data, url, response, error) => {
+      if (error) {
+        console.error('Attentive token registration failed', error);
+      }
+      handleRegularOpen(authStatus);
+    }
+  );
+});
+```
+
+#### 4. Optional: Handle notification opens and foreground (Android)
+
+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:
+
+- **User opened notification (background/inactive):** `handlePushOpen(payload, authorizationStatus)`
+- **Notification received while app in foreground:** `handleForegroundPush(payload, authorizationStatus)`
+
+Get `authorizationStatus` via `getPushAuthorizationStatus()` when handling the event.
+
+#### Complete Android flow (reference)
+
+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()`.
+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()`.
+
+---
+
+#### Request Push Permission (iOS)
 
 ```typescript
 import { registerForPushNotifications } from 'attentive-react-native-sdk';
@@ -183,9 +321,9 @@ import { registerForPushNotifications } from 'attentive-react-native-sdk';
 registerForPushNotifications();
 ```
 
-#### Register Device Token
+#### Register Device Token (iOS: APNs / Android: FCM)
 
-When your app receives a device token from APNs, register it with the Attentive backend:
+When your app receives a device token (APNs on iOS, FCM on Android), register it with the Attentive backend:
 
 ```typescript
 import { registerDeviceToken } from 'attentive-react-native-sdk';
@@ -202,7 +340,7 @@ The `authorizationStatus` parameter should be one of:
 - `'provisional'` - Provisional authorization (quiet notifications)
 - `'ephemeral'` - App Clip notifications
 
-#### Handle Push Notification Opens
+#### Handle Push Notification Opens (iOS and Android)
 
 When a user taps on a push notification, track the event:
 
@@ -218,7 +356,7 @@ handlePushOpened(
 );
 ```
 
-#### Handle Foreground Notifications
+#### Handle Foreground Notifications (iOS and Android)
 
 When a notification arrives while the app is in the foreground:
 
@@ -285,6 +423,4 @@ func application(
 - [Push Notifications Setup](./PUSH_NOTIFICATIONS_SETUP.md) - General push notification setup
 - [iOS Native SDK documentation](https://github.com/attentive-mobile/attentive-ios-sdk) - Native SDK reference
 
-#### Android Support
-
-Android push notification support is not yet implemented. The push notification methods will be no-ops on Android. FCM (Firebase Cloud Messaging) integration is planned for a future release.
+For a full Android implementation (app launch, foreground, permission, and optional FCM), see the **[App Events on Android](#app-events-on-android)** section above.

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-beta.1'
   implementation "org.jetbrains.kotlin:kotlin-stdlib:1.9.10"
   implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.9.10"))
   

package/android/src/main/AndroidManifest.xml

@@ -1,4 +1,6 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
           package="com.attentivereactnativesdk">
 
+    <!-- Required for push notification permission prompt on Android 13+ (API 33+) -->
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
 </manifest>

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

@@ -0,0 +1,101 @@
+package com.attentivereactnativesdk
+
+import android.app.Activity
+import android.content.Context
+import android.content.pm.PackageManager
+import android.os.Build
+import android.util.Log
+import androidx.core.app.ActivityCompat
+import androidx.core.content.ContextCompat
+
+/**
+ * Android push notification permission helper for the Attentive SDK.
+ *
+ * On Android 13+ (API 33+), push notifications require the runtime permission
+ * [android.permission.POST_NOTIFICATIONS]. On older versions, notifications
+ * are allowed by default (no runtime permission).
+ *
+ * This helper provides:
+ * - [getAuthorizationStatus] – current permission status for parity with iOS
+ * - [requestPermission] – request POST_NOTIFICATIONS when needed (used by registerForPushNotifications)
+ */
+object AttentivePushHelper {
+
+    private const val TAG = "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 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"
+    const val STATUS_NOT_DETERMINED = "notDetermined"
+
+    /**
+     * Returns the current push notification authorization status.
+     *
+     * 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, 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
+        }
+        return when (ContextCompat.checkSelfPermission(context, android.Manifest.permission.POST_NOTIFICATIONS)) {
+            PackageManager.PERMISSION_GRANTED -> STATUS_AUTHORIZED
+            else -> {
+                // 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
+                }
+            }
+        }
+    }
+
+    /**
+     * Requests the push notification permission (POST_NOTIFICATIONS) if needed.
+     * Must be called from an [Activity] (e.g. [reactApplicationContext.currentActivity]).
+     *
+     * On API < 33 this is a no-op and returns immediately.
+     *
+     * @param activity Current activity (required for requestPermissions)
+     * @param requestCode Request code for [Activity.onRequestPermissionsResult]
+     * @return true if the permission request was started or already granted, false if activity is null or permission not applicable
+     */
+    @JvmStatic
+    fun requestPermissionIfNeeded(activity: Activity?, requestCode: Int): Boolean {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
+            Log.d(TAG, "requestPermissionIfNeeded: API < 33, no runtime permission needed")
+            return true
+        }
+        if (activity == null) {
+            Log.w(TAG, "requestPermissionIfNeeded: activity is null, cannot request permission")
+            return false
+        }
+        if (ContextCompat.checkSelfPermission(activity, android.Manifest.permission.POST_NOTIFICATIONS) == PackageManager.PERMISSION_GRANTED) {
+            Log.d(TAG, "requestPermissionIfNeeded: POST_NOTIFICATIONS already granted")
+            return true
+        }
+        Log.i(TAG, "requestPermissionIfNeeded: requesting POST_NOTIFICATIONS")
+        ActivityCompat.requestPermissions(
+            activity,
+            arrayOf(android.Manifest.permission.POST_NOTIFICATIONS),
+            requestCode
+        )
+        return true
+    }
+}