appambit-push-notifications 0.3.0 → 1.0.0

package/AppAmbitSdkPushNotifications.podspec

@@ -13,10 +13,20 @@ Pod::Spec.new do |s|
   s.platforms    = { :ios => min_ios_version_supported }
   s.source       = { :git => "https://github.com/AppAmbit/appambit-sdk-react-native.git", :tag => "#{s.version}" }
 
-  s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
-  s.private_header_files = "ios/**/*.h"
+  s.default_subspec = 'Core'
 
-  s.dependency 'AppAmbitPushNotifications', '~> 0.5.0'
+  s.subspec 'Core' do |core|
+    core.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
+    core.exclude_files = "ios/AppAmbitRNNotificationService.swift"
+    core.private_header_files = "ios/**/*.h"
+    core.frameworks = 'Network'
+    core.dependency 'AppAmbitPushNotifications', '~> 1.0.0'
+    core.dependency 'AppAmbitSdk'
+    install_modules_dependencies(core)
+  end
 
-  install_modules_dependencies(s)
+  s.subspec 'Extension' do |ext|
+    ext.source_files = "ios/AppAmbitRNNotificationService.swift"
+    ext.dependency 'AppAmbitPushNotifications', '~> 1.0.0'
+  end
 end

package/README.md

@@ -2,7 +2,7 @@
 
 **Seamlessly integrate push notifications with your AppAmbit analytics.**
 
-This SDK is an extension of the core AppAmbit Android SDK, providing a simple and powerful way to handle Firebase Cloud Messaging (FCM) notifications.
+This SDK is an extension of the core AppAmbit SDK, providing a simple and powerful way to handle Firebase Cloud Messaging (FCM) notifications on both Android and iOS.
 
 ---
 
@@ -13,203 +13,282 @@ This SDK is an extension of the core AppAmbit Android SDK, providing a simple an
 * [Install](#install)
 * [Quickstart](#quickstart)
 * [Usage](#usage)
-* [Customization](#customization)
+* [Native Implementation Setup](#native-implementation-setup)
+  * [Android Setup](#android-setup)
+  * [iOS Setup](#ios-setup)
+  * [iOS Notification Service Extension (Rich Notifications)](#ios-notification-service-extension-rich-notifications)
 
 ---
 
 ## Features
 
+* **Zero-Config iOS**: No AppDelegate changes required — the SDK wires itself up automatically via method swizzling.
 * **Simple Setup**: Integrates in minutes.
 * **Enable/Disable Notifications**: Easily manage user preferences at both the business and FCM level.
-* **Automatic Field Handling**: Automatically uses standard fields from the FCM payload like `color`, `icon`, `channel_id`, and `click_action`.
-* **Smart Icon Selection**: Automatically uses your app's icon, with a safe fallback.
-* **Advanced Customization**: Provides a powerful hook to modify notifications for advanced use cases.
-* **Permission Helper**: Includes a simple utility to request the `POST_NOTIFICATIONS` permission.
+* **Robust Event Listeners**: Separate callbacks for Foreground and Opened (tapped) notifications on both platforms, Background listener is Android-only.
+* **Android Headless JS Support**: Handle background notifications via React Native Headless JS tasks even when the app is completely closed.
+* **Automatic Field Handling**: Automatically uses standard FCM payload fields like `color`, `icon`, `channel_id`, `click_action`, and rich images.
+* **Rich Media Support**: Full iOS Notification Service Extension support for rich payloads, badges, and media attachments.
+* **Permission Helpers**: Utilities to request and check the `POST_NOTIFICATIONS` permission.
 
 ---
 
 ## Requirements
 
-* **AppAmbit Core SDK**: This SDK is an extension and requires the core `appambit-sdk` to be installed and configured.
-* **Firebase Project**: A configured Firebase project and a `google-services.json` file in your application module.
-* Android API level 21 (Lollipop) or newer.
+* **AppAmbit Core SDK**: Requires the core `appambit` SDK to be installed and configured.
+* **Firebase Project**: A configured Firebase project with `google-services.json` (Android) and `GoogleService-Info.plist` (iOS) in your application.
+* **OS Versions**: Android API level 21 (Lollipop) or newer / iOS 13.0 or newer.
 
 ---
 
 ## Install
-To install the library from NPM, run the following commands in your project directory:
 
 ```bash
 npm install appambit
-&
 npm install appambit-push-notifications
 ```
 
-Add the following dependencies to your app's `build.gradle` file. Your app is still responsible for providing the Firebase Bill of Materials (BOM) and Firebase Messaging to ensure version compatibility.
+### Android Dependencies
 
-**Kotlin DSL**
+Add the following to your Gradle files. Your app is responsible for providing the Firebase BOM and Firebase Messaging to ensure version compatibility.
 
-**`android/app/build.gradle.kts`**
+**`android/app/build.gradle`** (Groovy)
 ```groovy
 apply plugin: "com.google.gms.google-services"
 
 dependencies {
-    // The Firebase BOM and Messaging are required to align Firebase library versions.
-    implementation(platform("com.google.firebase:firebase-bom:33.1.2"))
-    implementation ("com.google.firebase:firebase-messaging:23.4.0")
+    implementation platform('com.google.firebase:firebase-bom:33.1.2')
+    implementation 'com.google.firebase:firebase-messaging:23.4.0'
 }
 ```
-**`android/build.gradle.kts`**
+
+**`android/build.gradle`** (Groovy)
 ```groovy
 dependencies {
     classpath("com.google.gms:google-services:4.3.15")
 }
 ```
 
-**Groovy**
-**`android/app/build.gradle`**
-```groovy
-apply plugin: "com.google.gms.google-services"
+<details>
+<summary>Kotlin DSL</summary>
+
+**`android/app/build.gradle.kts`**
+```kotlin
+apply(plugin = "com.google.gms.google-services")
 
 dependencies {
-    // The Firebase BOM and Messaging are required to align Firebase library versions.
-    implementation platform('com.google.firebase:firebase-bom:33.1.2')
-    implementation 'com.google.firebase:firebase-messaging:23.4.0'
+    implementation(platform("com.google.firebase:firebase-bom:33.1.2"))
+    implementation("com.google.firebase:firebase-messaging:23.4.0")
 }
 ```
 
-**`android/build.gradle`**
-```groovy
+**`android/build.gradle.kts`**
+```kotlin
 dependencies {
     classpath("com.google.gms:google-services:4.3.15")
 }
 ```
+</details>
 
-Also, ensure you have the Google Services plugin configured in your project.
+### iOS Dependencies
+
+After installing the npm package, run:
+
+```bash
+cd ios && pod install
+```
 
 ---
 
 ## Quickstart
 
-**Import the SDKs**: In your `App.tsx` file, import both the AppAmbit SDK and the Push Notifications SDK.
+In your `App.tsx` (or application entry point), initialize both SDKs in order:
 
 ```javascript
-    import * as AppAmbit from "appambit";
-```
-```javascript
-    import * as PushNotifications from "appambit-push-notifications";
+import * as AppAmbit from "appambit";
+import * as PushNotifications from "appambit-push-notifications";
+
+AppAmbit.start("<YOUR-APPKEY>");
+PushNotifications.start();
+PushNotifications.requestNotificationPermission();
 ```
 
+---
+
+## Usage
 
-1.  **Initialize the Core SDK**: In your `App.tsx` class, initialize the core AppAmbit SDK with your App Key.
+### Event Listeners
 
-    ```javascript
-    AppAmbit.start("<YOUR-APPKEY>");
-    ```
+All listeners hold a single subscription — calling them again silently replaces the previous one. Each returns a cleanup function to call on unmount (e.g. in `useEffect`'s return).
 
-2.  **Initialize the Push SDK**: Immediately after, start the Push Notifications SDK.
+#### Foreground Listener
+Fires when a notification arrives while the app is active and open.
 
-    ```javascript
-    PushNotifications.start();
-    ```
+```javascript
+useEffect(() => {
+  const unsubscribe = PushNotifications.setForegroundListener((payload) => {
+    console.log("Foreground notification:", payload);
+  });
+  return () => unsubscribe();
+}, []);
+```
 
-3.  **Request Permissions**: In your main activity, request the required notification permission.
+#### Background Listener
+Fires when a notification arrives while the app is backgrounded or (on Android) killed.
 
-    ```javascript
-    PushNotifications.requestNotificationPermission();
-    ```
+> **Android only**: To handle notifications when the app is completely killed, you must also register a Headless JS task — see [Android Setup](#android-setup).
 
-**That's it!** Your app is now ready to receive and display push notifications.
+```javascript
+useEffect(() => {
+  const unsubscribe = PushNotifications.Android.setBackgroundListener(async (payload) => {
+    console.log("Background notification:", payload);
+    // The SDK automatically signals the OS when your Promise resolves
+  });
+  return () => unsubscribe();
+}, []);
+```
 
----
+#### Opened Listener
+Fires when the user taps a notification. Works regardless of whether the app was in the foreground, background, or killed.
 
-## Usage
+```javascript
+useEffect(() => {
+  const unsubscribe = PushNotifications.setOpenedListener((payload) => {
+    console.log("Notification tapped:", payload);
+  });
+  return () => unsubscribe();
+}, []);
+```
 
-### Enabling and Disabling Notifications
+### Notification Payload
+
+```typescript
+interface NotificationPayload {
+  title: string | null;
+  body: string | null;
+  imageUrl: string | null;
+  data: Record<string, string>;
+  android: {
+    color: string | null;
+    smallIconName: string | null;
+    ticker: string | null;
+    sticky: boolean | null;
+    visibility: string | null;
+    channelId: string | null;
+    tag: string | null;
+    sound: string | null;
+    clickAction: string | null;
+  } | null;
+  ios: {
+    badge: number | null;
+    sound: string | null;
+    category: string | null;
+    threadId: string | null;
+  } | null;
+}
+```
 
-By default, notifications are enabled when you first call `start()`. To manage user preferences afterward, use `setNotificationsEnabled`.
+### Permission Helpers
 
 ```javascript
-// To disable all future notifications
-PushNotifications.setNotificationsEnabled(false)
+// Fire-and-forget — shows the system permission dialog
+PushNotifications.requestNotificationPermission();
+
+// Returns Promise<boolean> with the user's decision
+const granted = await PushNotifications.requestNotificationPermissionWithResult();
 
-// To re-enable them
-PushNotifications.setNotificationsEnabled(true)
+// Check current permission status without prompting the user
+const hasPermission = await PushNotifications.hasNotificationPermission();
 ```
 
-This method updates the opt-out status on the AppAmbit dashboard and stops the device from receiving FCM messages. You can check the current setting at any time:
+### Enable / Disable Notifications
 
 ```javascript
-const isEnabled = PushNotifications.isNotificationsEnabled()
+PushNotifications.setNotificationsEnabled(false);  // opt out
+PushNotifications.setNotificationsEnabled(true);   // opt back in
+
+const isEnabled = await PushNotifications.isNotificationsEnabled();
 ```
 
-### Permission Listener (Optional)
+---
+
+## Native Implementation Setup
 
-To know if the user granted or denied the notification permission, you can provide an optional listener.
+### Android Setup
+
+The SDK's `AndroidManifest.xml` automatically merges the required permissions (`POST_NOTIFICATIONS`, `RECEIVE_BOOT_COMPLETED`), `AppAmbitInitProvider`, and `AppAmbitHeadlessService` into your app — no manifest changes needed.
+
+To handle notifications when the app is completely killed, register a Headless JS task in your `index.js`:
 
 ```javascript
-PushNotifications.requestNotificationPermissionWithResult().then(
-    (granted: boolean) => {
-        if(granted) {
-            console.log("Notification permission granted");
-        } else {
-            console.log("Notification permission denied");
-        }
+import { AppRegistry, Platform } from 'react-native';
+import * as PushNotifications from 'appambit-push-notifications';
+import App from './src/App';
+import { name as appName } from './app.json';
+
+if (Platform.OS === 'android') {
+  AppRegistry.registerHeadlessTask(
+    PushNotifications.BACKGROUND_NOTIFICATION_TASK,
+    () => async (payload) => {
+      console.log('Background notification (killed state):', payload);
     }
-);
+  );
+}
+
+AppRegistry.registerComponent(appName, () => App);
 ```
 
----
+> Use `AppRegistry.registerHeadlessTask` with `BACKGROUND_NOTIFICATION_TASK` — not `BackgroundFetch` or any other API.
 
-## Customization
+---
 
-The SDK is designed to be highly customizable, automatically adapting to the data you send in your FCM payload, while also offering a powerful hook for advanced modifications.
+### iOS Setup
 
-### Automatic Customization
+#### Push Notifications Capability & APNs Entitlement
 
-The SDK automatically configures the notification by reading standard fields from your FCM message. **For most use cases, you won't need to write any custom code.**
+Enable **Push Notifications** in Xcode under your target's *Signing & Capabilities* tab. This automatically injects the `aps-environment` entitlement into your `.entitlements` file.
 
-**`notification` object:**
+If you manage `Runner.entitlements` manually (e.g. via version control or CI), make sure this key is present — without it APNs will reject device registration and no token will ever be delivered:
 
-The SDK uses the standard keys from the FCM `notification` object.
+```xml
+<!-- ios/Runner/Runner.entitlements -->
+<key>aps-environment</key>
+<string>development</string>   <!-- use "production" for App Store builds -->
+```
 
-- **`title`**: The notification's title.
-- **`body`**: The notification's main text.
+---
 
-**`data` object:**
+### iOS Notification Service Extension (Rich Notifications)
 
-The `data` object is a free-form container for any custom key-value pairs you wish to send (e.g., `{"your_key": "your_value", "another_key": 123}`). Its sole purpose is to pass custom data to your application, which you can then access using the `NotificationCustomizer` to implement any advanced logic you require.
+To display rich notifications with image attachments, create a Notification Service Extension in Xcode.
 
-### Advanced Customization with `NotificationCustomizer`
+1. **Create the extension**: Go to **File > New > Target**, select **Notification Service Extension**, and give it a name (e.g. `NotificationService`).
 
-The `data` payload is a **free-form key-value map**. You are not limited to any specific keys; you can send any data you need and use it to build your custom notification.
+2. **Add the pod** to your `Podfile` outside the main target:
+   ```ruby
+   target 'NotificationService' do
+     pod 'AppAmbitPushNotificationsExtension', '~> 1.0.0'
+   end
+   ```
+   Then run `pod install` under `ios/`.
 
-**Example: Building a Custom Notification**
+3. **Subclass `AppAmbitNotificationService`** in `NotificationService.swift`:
 
-The following example shows how to read custom fields from the `data` payload to add a custom action button. This is just one of many possibilities.
+   ```swift
+   import UserNotifications
+   import AppAmbitPushNotificationsExtension
 
-1.  **Send any custom data** you need. The keys and values are completely up to you. For example:
+   class NotificationService: AppAmbitNotificationService {
+     override func didReceive(
+       _ request: UNNotificationRequest,
+       withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
+     ) {
+       // Base class handles rich media download and attachment automatically.
+       super.didReceive(request, withContentHandler: contentHandler)
+     }
 
-    ```json
-    {
-      "title": "New Message",
-      "body": "You have a new message from a friend.",
-      "data": {
-        "key1": "Mark as Read",
-        "key2": "MARK_AS_READ_ACTION",
-        "any_other_key": "any_value"
-      }
-    }
-    ```
-
-2.  **Register the `NotificationCustomizer`** and use your custom keys:
-
-    ```javascript
-    PushNotifications.setNotificationCustomizer((payload: PushNotifications.NotificationPayload) => {
-        console.log("Payload:", payload);
-        console.log("Data:", payload.data);
-        console.log("Title:", payload.title);
-        console.log("Body:", payload.body);
-    });
-    PushNotifications.start();
-    ```
+     override func serviceExtensionTimeWillExpire() {
+       super.serviceExtensionTimeWillExpire()
+     }
+   }
+   ```

package/android/build.gradle

@@ -15,10 +15,8 @@ buildscript {
   }
 }
 
-
 apply plugin: "com.android.library"
 apply plugin: "kotlin-android"
-
 apply plugin: "com.facebook.react"
 
 def getExtOrIntegerDefault(name) {
@@ -72,7 +70,27 @@ repositories {
 def kotlin_version = getExtOrDefault("kotlinVersion")
 
 dependencies {
-  implementation "com.appambit:appambit.push.notifications:0.5.0"
+  // ─── Remote Push SDK Dependency ─────────────────────────────────────────────
+  // 'api' (not 'implementation') is required so that classes like PushNotifications
+  // are visible at compile time to the consuming app (e.g. MainActivity.kt).
+  api 'com.appambit:appambit.push.notifications:1.0.0'
+
+  // ─── Core SDK (compile-time only) ───────────────────────────────────────────
+  // The Push SDK depends on the AppAmbit Core SDK. We reference Core's `AppAmbit`
+  // class (e.g. AppAmbit.isInitialized()) at compile time, but it is provided at
+  // runtime by the consuming app's Core SDK dependency, so use `compileOnly` to
+  // avoid bundling a second copy and risking duplicate-class conflicts.
+  compileOnly 'com.appambit:appambit:1.0.0'
+
+  // ─── Firebase (required transitively by the push AAR) ──────────────────────
+  implementation platform('com.google.firebase:firebase-bom:33.6.0')
+  implementation 'com.google.firebase:firebase-messaging'
+
+  // ─── AndroidX transitive deps ───────────────────────────────────────────────
+  implementation 'androidx.appcompat:appcompat:1.7.0'
+  implementation 'androidx.activity:activity:1.9.0'
+
+  // ─── React Native ─────────────────────────────────────────────────────────────
   implementation "com.facebook.react:react-android"
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
 }

package/android/src/main/AndroidManifest.xml

@@ -1,2 +1,108 @@
-<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+
+    <!--
+        AppAmbit Push Notifications — React Native Bridge Manifest
+
+        This manifest is MERGED into the consuming application's manifest.
+        It registers:
+          1. AppAmbitInitProvider       — ContentProvider that seeds AppAmbitContextHolder
+                                          before Application.onCreate() runs, enabling the SDK
+                                          to function even when the process is started solely
+                                          to handle an FCM message (killed state).
+          2. AppAmbitMessagingService   — Subclasses com.appambit.sdk.MessagingService to
+                                          capture the full RemoteMessage (including all
+                                          RemoteMessage.Notification fields) before the AppAmbit
+                                          SDK strips them into its own AppAmbitNotification model.
+          3. AppAmbitHeadlessService    — Starts Headless JS for background/killed notifications.
+          4. NotificationServiceExtension meta-data — tells MessagingService which extension class to load.
+
+        The consuming app must also declare:
+          - INTERNET permission
+          - POST_NOTIFICATIONS permission (Android 13+)
+          - google-services plugin and google-services.json
+    -->
+
+    <!-- ── Permissions (merged into host app) ───────────────────────────── -->
+    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+    <application>
+
+        <!--
+            AppAmbitInitProvider
+            Initialises AppAmbitContextHolder at the very first moment of process startup,
+            before Application.onCreate(). This is required so that the Headless JS service
+            can obtain a valid Context even in killed state (when the React Native bridge
+            has not started yet).
+
+            authorities uses ${applicationId} to avoid clashes between apps.
+            initOrder="100" makes it run before other providers with lower values.
+        -->
+        <provider
+            android:name="com.appambitpushnotifications.AppAmbitInitProvider"
+            android:authorities="${applicationId}.appambit-init-provider"
+            android:exported="false"
+            android:initOrder="100" />
+
+        <!--
+            Remove the base AppAmbit SDK's FirebaseMessagingService declaration so our
+            subclass (AppAmbitMessagingService) is the only handler for FCM events.
+            This library has higher manifest-merge priority than the AppAmbit SDK AAR,
+            so tools:node="remove" takes effect before the final manifest is assembled.
+        -->
+        <service
+            android:name="com.appambit.sdk.MessagingService"
+            tools:node="remove" />
+
+        <!--
+            AppAmbitMessagingService
+            Extends com.appambit.sdk.MessagingService (which extends FirebaseMessagingService).
+            Captures the full RemoteMessage in onMessageReceived, stores it in
+            AppAmbitRemoteMessageStore, then delegates to the AppAmbit SDK via super.onMessageReceived().
+
+            AppAmbitNotificationSerializer and AppAmbitHeadlessService read from the store
+            to populate notification fields not surfaced by AppAmbitNotification (e.g.
+            channelId, sound, tag, ticker, visibility, notificationPriority, vibrateTimings, etc.).
+        -->
+        <service
+            android:name="com.appambitpushnotifications.AppAmbitMessagingService"
+            android:exported="false">
+            <intent-filter>
+                <action android:name="com.google.firebase.MESSAGING_EVENT" />
+            </intent-filter>
+        </service>
+
+        <!--
+            AppAmbitHeadlessService
+            Runs the registered Headless JS task ("AppAmbitBackgroundNotification")
+            when a push notification arrives in background / killed state.
+
+            exported="false"  — only started internally, not from other apps.
+
+            Note: we do NOT declare android:foregroundServiceType because
+            HeadlessJsTaskService does not require foreground-service privileges.
+            Starting it with startService() is sufficient and avoids the strict
+            ForegroundServiceStartNotAllowedException on Android 12+ (API 31+).
+        -->
+        <service
+            android:name="com.appambitpushnotifications.AppAmbitHeadlessService"
+            android:exported="false" />
+
+        <!--
+            NotificationServiceExtension meta-data
+            Tells MessagingService which class to reflectively load as the
+            IAppAmbitNotificationServiceExtension implementation.
+
+            If the consuming app provides its OWN extension, they must
+            override this meta-data entry in their app's AndroidManifest.xml
+            with tools:replace="android:value".
+        -->
+        <meta-data
+            android:name="com.appambit.sdk.NotificationServiceExtension"
+            android:value="com.appambitpushnotifications.AppAmbitRNServiceExtension" />
+
+    </application>
+
 </manifest>

package/android/src/main/java/com/appambitpushnotifications/AppAmbitContextHolder.kt

@@ -0,0 +1,22 @@
+package com.appambitpushnotifications
+
+import android.content.Context
+import com.facebook.react.bridge.ReactApplicationContext
+
+/**
+ * Holds a reference to the Application context so that the
+ * [AppAmbitHeadlessService] can start itself even when no Activity is alive
+ * (killed state / background).
+ *
+ * Set once in [AppambitPushNotificationsModule.initialize] via the
+ * ReactApplicationContext, which outlives individual activities.
+ */
+internal object AppAmbitContextHolder {
+    @Volatile
+    var applicationContext: Context? = null
+        private set
+
+    fun set(context: Context) {
+        applicationContext = context.applicationContext
+    }
+}