react-native-notify-sphere 1.1.0 → 1.2.1

package/README.md

@@ -1,178 +1,92 @@
-# NotifySphere Push Notifications Implementation Guide
+# react-native-notify-sphere
 
-Complete implementation guide for integrating **react-native-notify-sphere** push notifications in React Native Android/iOS applications.
+A React Native push notification SDK built on Firebase Cloud Messaging (FCM) and Notifee. Handles delivery tracking, press tracking, user segmentation via tags, and rich notifications — with full Android and iOS support.
 
 ---
 
 ## Table of Contents
 
-1. [Overview](#overview)
+1. [Features](#features)
 2. [Prerequisites](#prerequisites)
 3. [Installation](#installation)
 4. [Android Setup](#android-setup)
 5. [iOS Setup](#ios-setup)
-6. [Implementation](#implementation)
-7. [NotifySphere Admin Panel](#notifysphere-admin-panel)
-8. [Testing](#testing)
+6. [Usage](#usage)
+7. [API Reference](#api-reference)
+8. [FCM Payload Format](#fcm-payload-format)
 9. [Troubleshooting](#troubleshooting)
-10. [Advanced Features](#advanced-features)
+10. [Version History](#version-history)
 
 ---
 
-## Overview
+## Features
 
-### What is NotifySphere?
-
-NotifySphere is a custom push notification solution built on top of Firebase Cloud Messaging (FCM) and Notifee, providing:
-
-- **Centralized Management**: Admin panel for sending notifications
-- **User Segmentation**: Target users with custom tags
-- **Analytics**: Track delivery, opens, and engagement
-- **Rich Notifications**: Support for images, sounds, and custom actions
-- **Cross-Platform**: Works on both Android and iOS
-
-### Architecture
-
-```
-┌─────────────────────────────────────────────┐
-│ NotifySphere Admin Panel                    │
-│ • Send Notifications                        │
-│ • Manage User Segments                      │
-│ • View Analytics & Reports                  │
-└──────────────┬──────────────────────────────┘
-               │
-               ▼
-┌─────────────────────────────────────────────┐
-│ NotifySphere Backend API                    │
-│ (notifysphere.dothejob.in:3008)            │
-│ • User Registration & Token Management      │
-│ • Tag-based Segmentation                    │
-│ • Notification Delivery via Firebase        │
-└──────────────┬──────────────────────────────┘
-               │
-               ▼
-┌─────────────────────────────────────────────┐
-│ Firebase Cloud Messaging (FCM)              │
-│ • Push Notification Delivery                │
-│ • Device Token Management                   │
-└──────────────┬──────────────────────────────┘
-               │
-               ▼
-┌─────────────────────────────────────────────┐
-│ Your React Native App                       │
-│ • react-native-notify-sphere               │
-│ • @react-native-firebase/messaging         │
-│ • @notifee/react-native                    │
-└─────────────────────────────────────────────┘
-```
+- ✅ Foreground, background, and terminated-state notification handling
+- ✅ Delivery confirmation API — fires in all three app states
+- ✅ Press / click tracking API
+- ✅ Smart re-registration — only calls the API when FCM token or user details change
+- ✅ Automatic FCM token refresh handling
+- ✅ User segmentation via custom tags
+- ✅ Rich notifications — images, custom sounds, action buttons
+- ✅ Bearer token authentication on all API calls
+- ✅ Full TypeScript support
+- ✅ Android & iOS
 
 ---
 
 ## Prerequisites
 
-### Required Tools
-
-- **Node.js**: v16 or higher
-- **React Native**: v0.70+
-- **Android Studio**: Latest version (for Android development)
-- **Xcode**: Latest version (for iOS development)
-- **CocoaPods**: Latest version (for iOS dependencies)
-
-### Firebase Project
-
-1. Create/Select project at [Firebase Console](https://console.firebase.google.com)
-2. Enable **Cloud Messaging**
-3. Download configuration files:
-   - **Android**: `google-services.json`
-   - **iOS**: `GoogleService-Info.plist`
-4. Get **Firebase Server Key**:
-   - Firebase Console → Project Settings → Cloud Messaging → Server Key
-
-### NotifySphere Account
-
-1. Access NotifySphere Admin Panel (contact provider for credentials)
-2. Create new application
-3. Obtain **App ID** (UUID format, e.g., `123b13cc-7dcb-2dcc-8dde-565433ec8d40`)
+- React Native `0.70+`
+- A Firebase project with Cloud Messaging enabled
+- A **NotifySphere account** with an App ID and API Token
 
 ---
 
 ## Installation
 
-### Step 1: Install Packages
+### Step 1 — Install the package and peer dependencies
 
 ```bash
-# Core NotifySphere package
 npm install react-native-notify-sphere
 
-# Required Firebase packages
-npm install @react-native-firebase/app@22.4.0
-npm install @react-native-firebase/messaging@22.4.0
-
-# Notifee for local notifications
-npm install @notifee/react-native@9.1.8
-
-# Additional dependencies
-npm install react-native-localize
-npm install react-native-device-info
-npm install axios
+# Peer dependencies (native — must be installed in your app)
+npm install @react-native-firebase/app
+npm install @react-native-firebase/messaging
+npm install @notifee/react-native
+npm install @react-native-async-storage/async-storage
 ```
 
-### Step 2: Link Native Dependencies
+### Step 2 — iOS: install pods
 
 ```bash
-# iOS only - Install pods
 cd ios && pod install && cd ..
 ```
 
-### Step 3: Verify Installation
-
-```bash
-# Check if packages are installed
-npm list react-native-notify-sphere @react-native-firebase/messaging @notifee/react-native
-```
-
 ---
 
 ## Android Setup
 
-### Step 1: Add Firebase Configuration
-
-**File Location**: `android/app/google-services.json`
-
-1. Download `google-services.json` from Firebase Console
-2. Place file in `android/app/` directory
+### 1. Add `google-services.json`
 
-### Step 2: Configure Gradle Files
+Download from the Firebase Console and place it at `android/app/google-services.json`.
 
-#### Root build.gradle
-
-**File**: `android/build.gradle`
+### 2. Configure `android/build.gradle`
 
 ```gradle
 buildscript {
     dependencies {
-        // ... other dependencies
-        
-        // Add Google Services plugin
         classpath 'com.google.gms:google-services:4.4.0'
     }
 }
 ```
 
-#### App build.gradle
-
-**File**: `android/app/build.gradle`
+### 3. Configure `android/app/build.gradle`
 
 ```gradle
 apply plugin: "com.android.application"
 apply plugin: "com.facebook.react"
 
-// ... other configurations
-
 android {
-    // ... android config
-    
-    // Add packaging options to avoid conflicts
     packagingOptions {
         pickFirst 'lib/x86/libc++_shared.so'
         pickFirst 'lib/x86_64/libc++_shared.so'
@@ -181,922 +95,377 @@ android {
     }
 }
 
-dependencies {
-    // ... dependencies
-}
-
-// IMPORTANT: Apply Google Services plugin at the very bottom (last line)
+// Must be the last line in the file
 apply plugin: 'com.google.gms.google-services'
 ```
 
-### Step 3: Update AndroidManifest.xml
-
-**File**: `android/app/src/main/AndroidManifest.xml`
+### 4. Update `AndroidManifest.xml`
 
 ```xml
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    xmlns:tools="http://schemas.android.com/tools"
-    package="com.yourapp.package">
-
-    <!-- Notification Permissions -->
-    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
-    <uses-permission android:name="android.permission.INTERNET" />
-    <uses-permission android:name="android.permission.VIBRATE" />
-    
-    <application
-        android:name=".MainApplication"
-        android:allowBackup="false"
-        android:theme="@style/AppTheme">
-
-        <!-- Firebase Notification Icon -->
-        <meta-data
-            android:name="com.google.firebase.messaging.default_notification_icon"
-            android:resource="@drawable/ic_stat_notification"
-            tools:replace="android:resource" />
-
-        <!-- Notification Color -->
-        <meta-data
-            android:name="com.google.firebase.messaging.default_notification_color"
-            android:resource="@color/notification_color"
-            tools:replace="android:resource" />
-
-        <!-- Default Notification Channel -->
-        <meta-data
-            android:name="com.google.firebase.messaging.default_notification_channel_id"
-            android:value="default_notification_channel"
-            tools:replace="android:value" />
-
-        <!-- Your Activities -->
-        <activity
-            android:name=".MainActivity"
-            android:exported="true">
-            <!-- ... intent filters ... -->
-        </activity>
-
-    </application>
-</manifest>
-```
+<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+<uses-permission android:name="android.permission.INTERNET" />
+<uses-permission android:name="android.permission.VIBRATE" />
 
-### Step 4: Create Resource Files
+<application ...>
+    <!-- Default notification icon -->
+    <meta-data
+        android:name="com.google.firebase.messaging.default_notification_icon"
+        android:resource="@drawable/ic_stat_onesignal_default"
+        tools:replace="android:resource" />
 
-#### Colors
-
-**File**: `android/app/src/main/res/values/colors.xml`
-
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<resources>
-    <color name="notification_color">#FF6B6B</color>
-    <color name="ic_launcher_background">#FFFFFF</color>
-    <color name="white">#FFFFFF</color>
-    <color name="black">#000000</color>
-</resources>
+    <!-- Default notification channel -->
+    <meta-data
+        android:name="com.google.firebase.messaging.default_notification_channel_id"
+        android:value="channel_default"
+        tools:replace="android:value" />
+</application>
 ```
 
-#### Strings
+### 5. Add notification icon
 
-**File**: `android/app/src/main/res/values/strings.xml`
-
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<resources>
-    <string name="app_name">Your App Name</string>
-</resources>
+Place your notification icon at:
 ```
-
-#### Styles
-
-**File**: `android/app/src/main/res/values/styles.xml`
-
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<resources>
-    <style name="AppTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
-        <item name="android:textColor">#000000</item>
-    </style>
-</resources>
+android/app/src/main/res/drawable/ic_stat_onesignal_default.png
 ```
 
-### Step 5: Add Notification Icon
-
-Create a notification icon and place it in:
-- `android/app/src/main/res/drawable/ic_stat_notification.png`
-
-Or use an existing icon in your project.
-
 ---
 
 ## iOS Setup
 
-### Step 1: Add Firebase Configuration
-
-1. Download `GoogleService-Info.plist` from Firebase Console
-2. Open Xcode: `open ios/YourApp.xcworkspace`
-3. Drag and drop `GoogleService-Info.plist` into Xcode project
-4. Ensure "Copy items if needed" is checked
-5. Add to all targets
-
-### Step 2: Install CocoaPods
-
-```bash
-cd ios
-pod install
-cd ..
-```
-
-### Step 3: Enable Capabilities in Xcode
+### 1. Add `GoogleService-Info.plist`
 
-1. Open `ios/YourApp.xcworkspace` in Xcode
-2. Select Project → Target → **Signing & Capabilities**
-3. Click **+ Capability**
-4. Add **"Push Notifications"**
-5. Click **+ Capability** again
-6. Add **"Background Modes"**
-   - Check: ☑️ **Remote notifications**
+Download from the Firebase Console, open Xcode, and drag the file into your project root. Make sure "Copy items if needed" is checked and it is added to all targets.
 
-### Step 4: Update AppDelegate
+### 2. Enable capabilities in Xcode
 
-**File**: `ios/YourApp/AppDelegate.mm` (or `AppDelegate.m`)
+Go to **Target → Signing & Capabilities → + Capability** and add:
+- `Push Notifications`
+- `Background Modes` → check **Remote notifications**
 
-#### Add Imports
+### 3. Update `AppDelegate.mm`
 
 ```objc
 #import <Firebase.h>
 #import <UserNotifications/UserNotifications.h>
-```
-
-#### Update didFinishLaunchingWithOptions
 
-```objc
-- (BOOL)application:(UIApplication *)application 
+- (BOOL)application:(UIApplication *)application
     didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
 {
-  // Initialize Firebase
   if ([FIRApp defaultApp] == nil) {
     [FIRApp configure];
   }
-  
-  // Set up notification center
   UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
   center.delegate = self;
-  
-  // ... rest of your existing code
-  
   return YES;
 }
-```
 
-#### Add Notification Handler Methods
-
-```objc
-// Handle foreground notifications
 - (void)userNotificationCenter:(UNUserNotificationCenter *)center
        willPresentNotification:(UNNotification *)notification
-         withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler
-{
-  completionHandler(UNNotificationPresentationOptionSound | 
-                   UNNotificationPresentationOptionAlert | 
-                   UNNotificationPresentationOptionBadge);
-}
-
-// Handle notification tap
-- (void)userNotificationCenter:(UNUserNotificationCenter *)center
-didReceiveNotificationResponse:(UNNotificationResponse *)response
-         withCompletionHandler:(void(^)(void))completionHandler
+         withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler
 {
-  completionHandler();
+  completionHandler(UNNotificationPresentationOptionSound |
+                    UNNotificationPresentationOptionAlert |
+                    UNNotificationPresentationOptionBadge);
 }
 ```
 
 ---
 
-## Implementation
+## Usage
 
-### Step 1: Create NotificationHelper Component
+You need two things from your NotifySphere dashboard before you start:
+- **App ID** — identifies your application
+- **API Token** — authenticates all requests to the NotifySphere API
 
-**File**: `src/utils/NotificationHelper.tsx`
+### `index.js` — register the background handler
 
-```typescript
-import { useEffect, useCallback } from 'react';
-import { Platform } from 'react-native';
-import NotifySphere from 'react-native-notify-sphere';
-import { useNavigation } from '@react-navigation/native';
-
-interface Props {
-  navigationRef?: any;
-}
+This **must** be called before `AppRegistry.registerComponent()` so the handler is in place when the app is woken from a terminated state to handle a background notification.
 
-export let deviceInfo: any = {};
-
-const NotificationHelper: React.FC<Props> = (props) => {
-  const navigation = useNavigation();
-
-  // Handle notification click
-  const onClickNotification = useCallback(
-    (notificationData: any, type?: string) => {
-      console.log('📬 Notification Clicked');
-      console.log('Type:', type);
-      console.log('Data:', notificationData);
-
-      const data = notificationData?.data || {};
-      const action = data?.redirect_action;
-
-      // Navigate based on action
-      switch (action) {
-        case 'home':
-          navigation.navigate('Home');
-          break;
-        
-        case 'profile':
-          navigation.navigate('Profile');
-          break;
-        
-        case 'details':
-          if (data?.itemId) {
-            navigation.navigate('Details', { id: data.itemId });
-          }
-          break;
-        
-        default:
-          // Default navigation
-          console.log('No specific action, staying on current screen');
-          break;
-      }
-    },
-    [navigation]
-  );
-
-  useEffect(() => {
-    const initializeNotifications = async () => {
-      try {
-        console.log('🔥 Initializing NotifySphere...');
-
-        // Get user information (replace with your actual user data)
-        const userId = 12345; // Your user ID
-        const userName = 'John Doe';
-        const userEmail = 'john@example.com';
-        const userPhone = 9876543210;
-
-        // Initialize NotifySphere
-        const subscriptionId = await NotifySphere.initialize({
-          applicationUserId: userId,
-          type: Platform.OS === 'android' ? 'AndroidPush' : 'IOSPush',
-          name: userName,
-          email: userEmail,
-          appId: 'YOUR_NOTIFYSPHERE_APP_ID', // Replace with your App ID
-          phone: userPhone,
-          lat: '26.9124', // Optional: User latitude
-          long: '75.7873', // Optional: User longitude
-          city: 'Jaipur', // Optional: User city
-          state: 'Rajasthan', // Optional: User state
-          tags: {
-            userType: 'customer',
-            premium: 'true',
-            // Add your custom tags
-          },
-        });
-
-        console.log('✅ NotifySphere Initialized!');
-        console.log('Subscription ID:', subscriptionId);
-
-        // Store subscription ID
-        deviceInfo.userId = subscriptionId;
-
-        // Update tags (optional - for better targeting)
-        NotifySphere.updateTags({
-          appId: 'YOUR_NOTIFYSPHERE_APP_ID',
-          applicationUserId: userId,
-          type: Platform.OS === 'android' ? 'AndroidPush' : 'IOSPush',
-          tags: {
-            lastLogin: new Date().toISOString(),
-            appVersion: '1.0.0',
-            // Add more tags as needed
-          },
-        });
-
-        // Set notification callback
-        NotifySphere.onNotification((notification, type) => {
-          console.log('🔔 Notification Callback Triggered');
-          console.log('Type:', type); // 'opened', 'initial', 'press'
-          
-          // Handle notification
-          onClickNotification(notification, type);
-        });
-
-        console.log('✅ Notification handlers registered!');
-        
-      } catch (error) {
-        console.error('❌ NotifySphere Error:', error);
-      }
-    };
-
-    initializeNotifications();
-  }, [onClickNotification]);
-
-  return null;
-};
-
-export default NotificationHelper;
-```
-
-### Step 2: Add to Your App
-
-**File**: `App.tsx`
-
-```typescript
-import React from 'react';
-import { NavigationContainer } from '@react-navigation/native';
-import { Provider } from 'react-redux';
-import NotificationHelper from './src/utils/NotificationHelper';
-import store from './src/redux/store';
-
-const App = () => {
-  return (
-    <Provider store={store}>
-      <NavigationContainer>
-        {/* Your navigation stack */}
-        <YourNavigationStack />
-        
-        {/* Add NotificationHelper */}
-        <NotificationHelper />
-      </NavigationContainer>
-    </Provider>
-  );
-};
-
-export default App;
-```
-
-### Step 3: Replace App ID
-
-In `NotificationHelper.tsx`, replace:
-```typescript
-appId: 'YOUR_NOTIFYSPHERE_APP_ID'
-```
-
-With your actual NotifySphere App ID from the admin panel.
-
----
-
-## NotifySphere Admin Panel
-
-### Step 1: Create Application
-
-1. **Login** to NotifySphere Admin Panel
-2. Click **"Create New App"**
-3. Fill in details:
-   - **App Name**: Your application name
-   - **Platform**: Select Android and/or iOS
-   - **Package Name**: Your app's package name
-4. Click **Save**
-5. **Copy the App ID** (UUID format)
-
-### Step 2: Configure Firebase
-
-1. Go to your app's settings in NotifySphere Admin
-2. Click **"Firebase Configuration"**
-3. Add **Firebase Server Key**:
-   - Get from: Firebase Console → Project Settings → Cloud Messaging → Server Key
-4. Save configuration
-
-### Step 3: Test Setup
-
-1. Go to **"Send Notification"** in admin panel
-2. Select your app
-3. Fill in basic details:
-   - **Title**: Test Notification
-   - **Body**: This is a test message
-4. Click **Send**
-
----
-
-## Testing
-
-### Method 1: Via NotifySphere Admin Panel
+```js
+import { AppRegistry } from 'react-native';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import App from './src/App';
+import { name as appName } from './app.json';
+import NotifySphere from 'react-native-notify-sphere';
+import { API_TOKEN } from './src/App';
 
-**Recommended for production testing**
+const STORAGE_KEY = '@notifysphere_subscription_id';
 
-1. Login to NotifySphere Admin Panel
-2. Navigate to **"Send Notification"**
-3. Select your application
-4. Configure notification:
+// Load the persisted subscription_id so delivery receipts include it
+// even when the app starts from a terminated state.
+AsyncStorage.getItem(STORAGE_KEY).then((subscriptionId) => {
+  NotifySphere.setBackgroundHandler({
+    apiKey: API_TOKEN,
+    subscriptionId: subscriptionId ?? undefined,
+  });
+});
 
-```json
-{
-  "title": "New Message",
-  "body": "You have received a new message!",
-  "data": {
-    "redirect_action": "details",
-    "itemId": "123",
-    "type": "message"
-  }
-}
+AppRegistry.registerComponent(appName, () => App);
 ```
 
-5. Target:
-   - **All Users**: Send to everyone
-   - **By Tags**: Target specific user segments
-   - **Specific Users**: Enter user IDs
-
-6. Click **Send**
+### `App.tsx` — initialize and listen
 
-### Method 2: Via Firebase Console
-
-**Good for quick testing**
+```tsx
+import { useEffect } from 'react';
+import { Platform } from 'react-native';
+import NotifySphere from 'react-native-notify-sphere';
 
-1. Go to [Firebase Console](https://console.firebase.google.com)
-2. Select your project
-3. Navigate to **Cloud Messaging** → **Send your first message**
-4. Click **"Send test message"**
-5. Get FCM token from app logs:
+const APP_ID = 'your-notifysphere-app-id';
+export const API_TOKEN = 'your-api-token'; // Get this from your NotifySphere dashboard
+const PUSH_TYPE = Platform.OS === 'android' ? 'AndroidPush' : 'IOSPush';
 
-```bash
-# Android
-npx react-native log-android | grep "fcmToken"
-
-# iOS
-npx react-native log-ios | grep "fcmToken"
-```
+export default function App() {
+  useEffect(() => {
+    const init = async () => {
+      // Safe to call on every app open — only hits the registration API
+      // when the FCM token or user details have changed.
+      const subscriptionId = await NotifySphere.initialize({
+        applicationUserId: 123,   // your internal user ID
+        type: PUSH_TYPE,
+        appId: APP_ID,
+        apiKey: API_TOKEN,
+        name: 'John Doe',
+        email: 'john@example.com',
+        phone: '9876543210',      // string — preserves leading zeros
+        lat: '26.9124',
+        long: '75.7873',
+        city: 'Jaipur',
+        state: 'Rajasthan',
+        tags: {
+          userType: 'customer',
+          premium: 'true',
+        },
+        debug: __DEV__,           // enable verbose logs in development
+      });
+
+      console.log('NotifySphere subscriptionId:', subscriptionId);
+
+      // Optionally update tags without re-registering the device
+      await NotifySphere.updateTags({
+        applicationUserId: 123,
+        type: PUSH_TYPE,
+        tags: { lastLogin: new Date().toISOString() },
+      });
+    };
 
-6. Paste token and click **Test**
+    init();
 
-### Method 3: Via Postman/API
+    // Listen for all notification events
+    NotifySphere.onNotification((notification, type) => {
+      console.log('Notification event:', type, notification);
 
-**For automated testing**
+      if (type === 'press' || type === 'opened' || type === 'initial') {
+        // User tapped the notification — navigate, show modal, etc.
+      }
 
-```http
-POST https://fcm.googleapis.com/fcm/send
-Content-Type: application/json
-Authorization: key=YOUR_FIREBASE_SERVER_KEY
+      if (type === 'received') {
+        // Notification arrived while the app was in the foreground
+      }
+    });
 
-{
-  "to": "DEVICE_FCM_TOKEN",
-  "notification": {
-    "title": "Test Notification",
-    "body": "Testing push notifications"
-  },
-  "data": {
-    "redirect_action": "home",
-    "customKey": "customValue"
-  },
-  "android": {
-    "priority": "high"
-  },
-  "apns": {
-    "headers": {
-      "apns-priority": "10"
-    }
-  }
+    // Clean up listeners on unmount / logout
+    return () => NotifySphere.destroy();
+  }, []);
 }
 ```
 
-### Test Scenarios
-
-#### ✅ Foreground Testing (App Open)
-
-**Expected Behavior:**
-- Notification displays as banner/head-up notification
-- Sound plays (if configured)
-- Vibration occurs (if configured)
-- Tapping navigates to specified screen
-
-**Verification:**
-```bash
-npx react-native log-android | grep "displayLocalNotification"
-# Should see: "✅ NOTIFICATION DISPLAYED SUCCESSFULLY!"
-```
-
-#### ✅ Background Testing (App Minimized)
-
-**Expected Behavior:**
-- Notification appears in notification tray
-- Tapping opens app
-- Navigation occurs after app opens
-
-#### ✅ Killed State Testing (App Closed)
-
-**Expected Behavior:**
-- Notification appears in notification tray
-- Tapping launches app
-- Navigation occurs after app launches
-
-**Verification:**
-```bash
-npx react-native log-android | grep "Notification Callback"
-# Should see: Type: 'initial' or 'opened'
-```
+> **Security note:** Never commit your `API_TOKEN` to source control. In production, read it from a secure config file or environment variable (e.g. via `react-native-config`).
 
 ---
 
-## Troubleshooting
-
-### Common Issues
-
-#### Issue: "No FCM Token Received"
-
-**Symptoms:**
-- No token in logs
-- Notifications not received
-
-**Solutions:**
-
-1. **Check Firebase Configuration:**
-```bash
-# Android
-ls -la android/app/google-services.json
-
-# iOS
-ls -la ios/GoogleService-Info.plist
-```
+## API Reference
+
+### `NotifySphere.initialize(config)`
+
+Initialises the SDK, registers the device with the NotifySphere server, and sets up notification listeners. Safe to call on every app open — the registration API is only called when the FCM token or user details have changed since the last run.
+
+**Returns:** `Promise<string | undefined>` — the `subscription_id` assigned by the server.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `applicationUserId` | `number` | ✅ | Your internal user ID for this device |
+| `type` | `string` | ✅ | `'AndroidPush'` or `'IOSPush'` |
+| `appId` | `string` | ✅ | Your NotifySphere App ID |
+| `apiKey` | `string` | ✅ | Bearer token from your NotifySphere dashboard |
+| `name` | `string` | | User display name |
+| `email` | `string` | | User email address |
+| `phone` | `string` | | User phone number (string to preserve leading zeros) |
+| `lat` | `string` | | User latitude |
+| `long` | `string` | | User longitude |
+| `city` | `string` | | User city |
+| `state` | `string` | | User state / region |
+| `tags` | `Record<string, string>` | | Custom key-value segmentation tags |
+| `baseUrl` | `string` | | Override the API base URL (defaults to hosted service) |
+| `trackingUrl` | `string` | | Override the press-tracking endpoint |
+| `deliveryUrl` | `string` | | Override the delivery-confirmation endpoint |
+| `debug` | `boolean` | | Enable verbose `[NotifySphere]` console logs (default: `false`) |
 
-2. **Verify Google Services Plugin:**
-```bash
-cat android/app/build.gradle | grep "google-services"
-# Should be at the very bottom of the file
-```
-
-3. **Check Permissions:**
-```bash
-# Android - Check if permission granted
-adb shell dumpsys package com.yourapp.package | grep "POST_NOTIFICATIONS"
-```
-
-#### Issue: "Foreground Notifications Not Displaying"
-
-**Error in logs:**
-```
-❌ ERROR in displayLocalNotification
-Error: largeIcon expected a valid string URL
-```
-
-**Solution:**
-
-The package has a known issue with empty `largeIcon` field. Fix by editing package:
-
-```bash
-code node_modules/react-native-notify-sphere/src/index.tsx
-```
-
-Find `displayLocalNotification` function and update:
-
-```typescript
-// Validate largeIcon before using
-const largeIconRaw = remoteMessage.data?.largeIcon;
-const validLargeIcon = largeIconRaw && largeIconRaw.trim() !== '' 
-  ? largeIconRaw 
-  : undefined;
-
-// Only add if valid
-if (validLargeIcon) {
-  notificationConfig.android.largeIcon = validLargeIcon;
-}
-```
-
-#### Issue: "App Crashes on Notification"
-
-**Symptoms:**
-- App crashes when notification received
-- No error in React Native logs
-
-**Solutions:**
+---
 
-1. **Check Native Logs:**
-```bash
-# Android
-adb logcat | grep -i "error\|exception"
+### `NotifySphere.setBackgroundHandler(config?)`
 
-# iOS
-# View in Xcode console
-```
-
-2. **Verify Channel Creation:**
-```bash
-npx react-native log-android | grep "Channel created"
-```
+Registers Firebase and Notifee background/terminated-state handlers. **Must be called in `index.js`** before `AppRegistry.registerComponent()`.
 
-3. **Check Sound Files:**
-- Ensure custom sound files exist in `android/app/src/main/res/raw/`
-- Use `default` sound if custom sound missing
+When the app is **terminated**, `initialize()` never runs, so any config you passed there is not available. Pass `apiKey` and `subscriptionId` here directly so delivery receipts still work.
 
-#### Issue: "iOS Notifications Not Working"
+| Field | Type | Description |
+|---|---|---|
+| `apiKey` | `string` | Bearer token — required for authenticated delivery receipts in terminated state |
+| `subscriptionId` | `string` | Persisted subscription ID — include it so receipts are linked to the correct device |
+| `deliveryUrl` | `string` | Override the delivery URL for terminated state (optional) |
 
-**Common Causes:**
+---
 
-1. **Testing on Simulator:**
-   - Push notifications **DO NOT work** on iOS Simulator
-   - Must test on real device
+### `NotifySphere.onNotification(callback)`
 
-2. **Missing Capabilities:**
-   - Xcode → Target → Signing & Capabilities
-   - Verify "Push Notifications" is enabled
-   - Verify "Background Modes" → "Remote notifications" is checked
+Register a callback to receive all notification events.
 
-3. **Firebase Not Initialized:**
-```objc
-// Check AppDelegate.mm
-if ([FIRApp defaultApp] == nil) {
-  [FIRApp configure]; // Must be present
-}
+```ts
+NotifySphere.onNotification((notification, type) => {
+  // notification: { title, body, data, image, sound }
+  // type: 'received' | 'press' | 'opened' | 'initial'
+});
 ```
 
-4. **Provisioning Profile:**
-   - Ensure push notifications are enabled in Apple Developer Portal
-   - Regenerate provisioning profile if needed
+| Event type | When it fires |
+|---|---|
+| `received` | Notification arrived while the app was in the foreground |
+| `press` | A Notifee background notification was tapped |
+| `opened` | App brought from background via notification tap |
+| `initial` | App launched from a quit state via notification tap |
 
-#### Issue: "Notification Data Not Received in Callback"
-
-**Symptoms:**
-- Notification displays
-- Callback triggered
-- But `data` object is empty
+---
 
-**Solution:**
+### `NotifySphere.updateTags(params)`
 
-Check notification payload structure:
+Updates user tags without re-registering the device. `appId` is optional — falls back to the value passed in `initialize()`.
 
-```json
-{
-  "notification": {
-    "title": "Title",
-    "body": "Body"
-  },
-  "data": {
-    "redirect_action": "home",
-    "itemId": "123"
-  }
-}
+```ts
+await NotifySphere.updateTags({
+  applicationUserId: 123,
+  type: 'AndroidPush',
+  tags: { premium: 'true', age: '33' },
+});
 ```
 
-Ensure `data` is separate from `notification` object.
-
-### Debug Commands
-
-```bash
-# Android - View all logs
-npx react-native log-android
-
-# Android - Filter notification logs
-npx react-native log-android | grep -E "NotifySphere|fcm|notification"
-
-# iOS - View all logs
-npx react-native log-ios
-
-# iOS - Filter notification logs
-npx react-native log-ios | grep -E "NotifySphere|Firebase|notification"
-
-# Check app processes
-adb shell ps | grep com.yourapp.package
-
-# Kill app (Android)
-adb shell am force-stop com.yourapp.package
-
-# Clear app data (Android)
-adb shell pm clear com.yourapp.package
-```
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `applicationUserId` | `number` | ✅ | Your internal user ID |
+| `type` | `string` | ✅ | `'AndroidPush'` or `'IOSPush'` |
+| `tags` | `Record<string, string>` | ✅ | Tags to update |
+| `appId` | `string` | | Defaults to the `appId` passed in `initialize()` |
 
 ---
 
-## Advanced Features
-
-### Custom Tags for User Segmentation
-
-```typescript
-NotifySphere.updateTags({
-  appId: 'YOUR_APP_ID',
-  applicationUserId: userId,
-  type: Platform.OS === 'android' ? 'AndroidPush' : 'IOSPush',
-  tags: {
-    // Demographic
-    age: '25-34',
-    gender: 'male',
-    location: 'New York',
-    
-    // Behavioral
-    purchaseFrequency: 'high',
-    lastPurchase: '2024-01-01',
-    totalSpent: '5000',
-    
-    // Engagement
-    appVersion: '2.1.0',
-    lastLogin: new Date().toISOString(),
-    notificationsEnabled: 'true',
-    
-    // Custom
-    interests: 'sports,technology',
-    membershipLevel: 'premium',
-  },
-});
-```
+### `NotifySphere.destroy()`
 
-### Rich Notifications with Images
+Unsubscribes all active listeners and resets internal state. Call this on logout or when you no longer need notifications.
 
-Send from admin panel or API:
-
-```json
-{
-  "notification": {
-    "title": "New Product Launch",
-    "body": "Check out our latest collection!",
-    "image": "https://example.com/image.jpg"
-  },
-  "data": {
-    "redirect_action": "product_details",
-    "productId": "P123"
-  }
-}
+```ts
+NotifySphere.destroy();
 ```
 
-### Custom Sounds
-
-**Android:**
+---
 
-1. Add sound file: `android/app/src/main/res/raw/custom_sound.mp3`
-2. Send notification with sound:
+### `NotifySphere.checkApplicationPermission()`
 
-```json
-{
-  "data": {
-    "sound": "custom_sound"
-  }
-}
-```
+Requests notification permission from the OS and returns `true` if granted. Called automatically by `initialize()` — you only need to call this directly if you want to check permission status before initialising.
 
-**iOS:**
+---
 
-1. Add sound file to Xcode project
-2. Ensure file is added to target
-3. Send notification with sound in payload
+## FCM Payload Format
 
-### Action Buttons
+NotifySphere expects **data-only** FCM messages (no `notification` field). This is required for delivery confirmation to work in the terminated state.
 
 ```json
 {
+  "to": "<device-fcm-token>",
   "data": {
-    "actionButtons": "[{\"title\":\"View\",\"pressAction\":{\"id\":\"view\"}},{\"title\":\"Dismiss\",\"pressAction\":{\"id\":\"dismiss\"}}]"
+    "title": "Hello!",
+    "body": "You have a new message.",
+    "notification_id": "uuid-here",
+    "sound": "default",
+    "imageUrl": "https://example.com/image.jpg",
+    "smallIcon": "ic_stat_onesignal_default",
+    "redirect_action": "home"
   }
 }
 ```
 
-### Notification Scheduling
-
-Currently, NotifySphere handles immediate delivery. For scheduled notifications, use the admin panel's scheduling feature or implement server-side scheduling.
+> **Why data-only?** If a `notification` field is present in the FCM payload, the OS handles display silently — your JavaScript never runs and delivery receipts cannot fire in the terminated state.
 
-### Analytics Tracking
+### Supported `data` fields
 
-NotifySphere automatically tracks:
-- Notification delivery
-- Open rates
-- Click rates
-- Device information
-
-View in admin panel: **Analytics → Notification Reports**
+| Field | Description |
+|---|---|
+| `title` | Notification title |
+| `body` | Notification body text |
+| `notification_id` | ID used for delivery and press tracking |
+| `sound` | Sound file name without extension, or `'default'` |
+| `imageUrl` | URL for a big-picture style notification image |
+| `smallIcon` | Android small icon resource name (falls back to `ic_stat_onesignal_default`) |
+| `actionButtons` | JSON string of Notifee action button definitions |
 
 ---
 
-## Best Practices
-
-### 1. User Privacy
-
-```typescript
-// Request permission gracefully
-const hasPermission = await NotifySphere.checkApplicationPermission();
-
-if (!hasPermission) {
-  // Show explanation UI
-  showPermissionExplanation();
-  // Then request
-  await requestPermission();
-}
-```
-
-### 2. Tag Management
-
-```typescript
-// Update tags when relevant data changes
-useEffect(() => {
-  if (user.profileUpdated) {
-    NotifySphere.updateTags({
-      appId: APP_ID,
-      applicationUserId: user.id,
-      type: Platform.OS === 'android' ? 'AndroidPush' : 'IOSPush',
-      tags: {
-        profileComplete: 'true',
-        lastUpdated: new Date().toISOString(),
-      },
-    });
-  }
-}, [user.profileUpdated]);
-```
-
-### 3. Error Handling
-
-```typescript
-try {
-  const subscriptionId = await NotifySphere.initialize({...});
-  
-  if (!subscriptionId) {
-    // Handle initialization failure
-    logError('NotifySphere initialization failed');
-    // Retry or fallback
-  }
-} catch (error) {
-  // Handle error gracefully
-  logError('NotifySphere error:', error);
-  // Show user-friendly message if needed
-}
-```
-
-### 4. Testing Checklist
-
-- [ ] Test on real devices (iOS especially)
-- [ ] Test all notification states (foreground, background, killed)
-- [ ] Test navigation for each `redirect_action`
-- [ ] Test with different payload structures
-- [ ] Test with images
-- [ ] Test with custom sounds
-- [ ] Test user segmentation with tags
-- [ ] Verify analytics tracking
-- [ ] Test opt-out functionality
-
----
-
-## Package Information
+## Troubleshooting
 
-### Dependencies
+### API calls returning 401 Unauthorized
 
-```json
-{
-  "react-native-notify-sphere": "^1.0.0",
-  "@react-native-firebase/app": "22.4.0",
-  "@react-native-firebase/messaging": "22.4.0",
-  "@notifee/react-native": "9.1.8",
-  "react-native-device-info": "latest",
-  "react-native-localize": "latest",
-  "axios": "latest"
-}
-```
+Make sure you are passing `apiKey` in both `initialize()` and `setBackgroundHandler()`. The API Token can be found in your NotifySphere dashboard under your app settings.
 
-### Package Features
+### Notifications not displaying on Android
 
-- ✅ Automatic foreground notification display
-- ✅ Background notification handling
-- ✅ Notification tap handling
-- ✅ Custom tags for segmentation
-- ✅ Image support in notifications
-- ✅ Custom sound support
-- ✅ Analytics tracking
-- ✅ Action buttons support
-- ✅ Cross-platform (Android & iOS)
+Check that `ic_stat_onesignal_default.png` exists at `android/app/src/main/res/drawable/`. Android silently drops notifications with a missing or invalid small icon.
 
----
+### Delivery receipt not firing in terminated state
 
-## Resources
+Make sure you are sending a **data-only** FCM message (no `notification` field in the payload). Also confirm that `setBackgroundHandler()` is called in `index.js` before `AppRegistry.registerComponent()`, and that you are passing both `apiKey` and `subscriptionId` to it.
 
-### Documentation
+### `async-storage` build error
 
-- [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging)
-- [Notifee Documentation](https://notifee.app/react-native/docs/overview)
-- [React Native Firebase](https://rnfirebase.io/)
+Use `@react-native-async-storage/async-storage@^1.23.1`. Version 2+ requires a custom Maven repository that is not configured by default in most React Native projects.
 
-### Useful Commands
+### iOS notifications not working
 
-```bash
-# Clean build
-cd android && ./gradlew clean && cd ..
-rm -rf node_modules && npm install
+Push notifications do not work on the iOS Simulator. Test on a physical device with a push-enabled provisioning profile.
 
-# iOS clean
-cd ios && pod deintegrate && pod install && cd ..
+### Debug logging
 
-# Run app
-npm run android
-npm run ios
+Pass `debug: true` (or `debug: __DEV__`) to `initialize()` to see verbose `[NotifySphere]` logs in the Metro console:
 
-# View logs
-npx react-native log-android
-npx react-native log-ios
+```ts
+await NotifySphere.initialize({ ..., debug: __DEV__ });
 ```
 
 ---
 
-## Support
+## Version History
 
-For issues or questions:
+### v1.2.0 (March 2026)
 
-1. Check logs for error messages
-2. Verify all configuration steps
-3. Test on real devices (especially iOS)
-4. Check Firebase and NotifySphere admin panels
-5. Contact NotifySphere support if needed
+- **Bearer token authentication** — all API endpoints now require an `apiKey` (Bearer token); added to `initialize()`, `registerDevice`, and `setBackgroundHandler()`
+- **Updated API URL structure** — endpoints now follow `client/{appId}/...` path pattern
+- **Fixed `registerDevice` URL** — corrected a template literal bug that was constructing an invalid URL
+- **Fixed `updateTags` URL** — removed incorrect `/apps/` path segment
+- **Dynamic tracking / delivery URLs** — `trackingUrl` and `deliveryUrl` are now built with `appId` at runtime rather than using static defaults
 
----
+### v1.1.0 (January 2026)
 
-## Version History
+- **Delivery confirmation API** — fires in foreground, background, and terminated state
+- **Smart re-registration** — registration API only called when FCM token or user details change
+- **Automatic token refresh** — `onTokenRefresh` watcher re-registers without requiring another `initialize()` call
+- **`destroy()` method** — clean listener unsubscription on logout
+- **Configurable endpoints** — `baseUrl`, `trackingUrl`, `deliveryUrl` in `initialize()`
+- **`phone` changed to `string`** — prevents corruption of numbers with leading zeros
+- **`appId` stored internally** — `updateTags` no longer requires passing `appId` again
+- **`debug` flag** — all `console.log` calls gated behind `debug: true`
+- **Removed unused dependencies** — `react-native-device-info`, `react-native-localize`
+
+### v1.0.1 (October 2025)
 
-- **v1.0.0** (January 2026) - Initial implementation guide
+- Initial release
 
 ---
 
-**Created:** January 7, 2026  
-**Status:** ✅ Production Ready  
 **Platform Support:** Android ✅ | iOS ✅