Implement token refresh functionality

Author: erkie

CHANGELOG.md

@@ -1,4 +1,37 @@
 # Changelog
+
+# Unreleased
+
+## Fixed
+### Android
+* **Fixed FCM token refresh not being handled** - Added missing `onNewToken()` handler to `FcmInstanceIdListenerService`. Previously, when FCM automatically refreshed a device's push token (which can happen after extended inactivity, security updates, or OS updates), the app would not be notified of the new token. This caused push notifications to silently stop working for affected users because the backend was still sending to the old, invalid token.
+
+## Added
+### Android
+* **Added `isRefresh` property to token registration event** - The `Registered` event now includes an `isRefresh` boolean property (Android only) that indicates whether the token was received due to an FCM-initiated refresh (`true`) or from app initialization/manual refresh (`false`). This allows your backend to distinguish between initial registrations and token refreshes for analytics or debugging purposes.
+
+  **Important for client apps:** Ensure you register the `remoteNotificationsRegistered` event listener early in your app lifecycle (ideally in your root component constructor or `useEffect`). This listener will now be called whenever FCM refreshes the token, not just on initial registration. Your app should sync the new token to your backend each time this event fires.
+
+  ```jsx
+  // In your root component
+  useEffect(() => {
+    const subscription = Notifications.events().registerRemoteNotificationsRegistered((event) => {
+      console.log("Device Token Received", event.deviceToken);
+      
+      if (event.isRefresh) {
+        console.log("This is an FCM-initiated token refresh - old token is now invalid");
+      }
+      
+      // Always sync the token to your backend
+      syncTokenToBackend(event.deviceToken, { isRefresh: event.isRefresh });
+    });
+    
+    Notifications.registerRemoteNotifications();
+    
+    return () => subscription.remove();
+  }, []);
+  ```
+
 # 2.1.0
 ## Added
 * react-native 0.60 Support

lib/android/app/src/main/java/com/wix/reactnativenotifications/fcm/FcmInstanceIdListenerService.java

@@ -1,8 +1,12 @@
 package com.wix.reactnativenotifications.fcm;
 
+import android.content.Context;
+import android.content.Intent;
 import android.os.Bundle;
 import android.util.Log;
 
+import androidx.annotation.NonNull;
+
 import com.google.firebase.messaging.FirebaseMessagingService;
 import com.google.firebase.messaging.RemoteMessage;
 import com.wix.reactnativenotifications.BuildConfig;
@@ -22,6 +26,31 @@
 public class FcmInstanceIdListenerService extends FirebaseMessagingService {
     private final IntercomPushClient intercomPushClient = new IntercomPushClient();
 
+    /**
+     * Called when FCM refreshes the registration token. This can happen when:
+     * - The app is restored on a new device
+     * - The user uninstalls/reinstalls the app
+     * - The user clears app data
+     * - FCM determines that the token needs to be refreshed
+     *
+     * When this happens, we need to fetch the new token and notify the JS side
+     * so the app can sync the new token with its backend server.
+     *
+     * @param token The new FCM registration token
+     */
+    @Override
+    public void onNewToken(@NonNull String token) {
+        super.onNewToken(token);
+        if (BuildConfig.DEBUG) Log.d(LOGTAG, "FCM token refreshed by Firebase: " + token);
+
+        // Trigger the token refresh handler to notify JS and any app-level listeners
+        final Context appContext = getApplicationContext();
+        final Intent tokenFetchIntent = new Intent(appContext, FcmInstanceIdRefreshHandlerService.class);
+        // Don't set EXTRA_IS_APP_INIT or EXTRA_MANUAL_REFRESH - this uses the default path
+        // which calls onNewTokenReady() to handle the automatic token refresh
+        FcmInstanceIdRefreshHandlerService.enqueueWork(appContext, tokenFetchIntent);
+    }
+
     @Override
     public void onMessageReceived(RemoteMessage message){
         Bundle bundle = message.toIntent().getExtras();

lib/android/app/src/main/java/com/wix/reactnativenotifications/fcm/FcmToken.java

@@ -20,6 +20,10 @@ public class FcmToken implements IFcmToken {
     final protected JsIOHelper mJsIOHelper;
 
     protected static String sToken;
+    
+    // Tracks whether the current token event is from an FCM-initiated refresh
+    // (as opposed to app init or manual refresh)
+    protected boolean mIsTokenRefresh = false;
 
     protected FcmToken(Context appContext) {
         if (!(appContext instanceof ReactApplication)) {
@@ -40,13 +44,17 @@ public static IFcmToken get(Context context) {
     @Override
     public void onNewTokenReady() {
         synchronized (mAppContext) {
+            // This is called when FCM has refreshed the token automatically
+            mIsTokenRefresh = true;
             refreshToken();
         }
     }
 
     @Override
     public void onManualRefresh() {
         synchronized (mAppContext) {
+            // Manual refresh is user-initiated, not an FCM-triggered refresh
+            mIsTokenRefresh = false;
             if (sToken == null) {
                 if(BuildConfig.DEBUG) Log.i(LOGTAG, "Manual token refresh => asking for new token");
                 refreshToken();
@@ -60,6 +68,8 @@ public void onManualRefresh() {
     @Override
     public void onAppReady() {
         synchronized (mAppContext) {
+            // App initialization is not considered a refresh
+            mIsTokenRefresh = false;
             if (sToken == null) {
                 if(BuildConfig.DEBUG) Log.i(LOGTAG, "App initialized => asking for new token");
                 refreshToken();
@@ -99,8 +109,13 @@ protected void sendTokenToJS() {
         if (reactContext != null && reactContext.hasActiveReactInstance()) {
             Bundle tokenMap = new Bundle();
             tokenMap.putString("deviceToken", sToken);
+            // Indicates whether this token was received due to an FCM-initiated refresh
+            // (true) or from app initialization/manual refresh (false)
+            tokenMap.putBoolean("isRefresh", mIsTokenRefresh);
             mJsIOHelper.sendEventToJS(TOKEN_RECEIVED_EVENT_NAME, tokenMap, reactContext);
         }
+        // Reset the refresh flag after sending
+        mIsTokenRefresh = false;
     }
 
 }

lib/src/interfaces/NotificationEvents.ts

@@ -3,6 +3,19 @@ import { NotificationActionResponse } from './NotificationActionResponse';
 
 export interface Registered {
   deviceToken: string;
+  /**
+   * Indicates whether this token was received due to an FCM-initiated refresh.
+   * 
+   * - `true`: FCM automatically refreshed the token (e.g., due to security rotation,
+   *   extended inactivity, or other FCM-internal reasons). The old token is now invalid.
+   * - `false`: Token received during app initialization or manual refresh request.
+   * 
+   * **Important**: Always sync the token to your backend regardless of this value,
+   * but you may want to log or handle refresh events differently for debugging purposes.
+   * 
+   * Note: This property is only set on Android. On iOS, it will always be `undefined`.
+   */
+  isRefresh?: boolean;
 }
 
 export interface RegistrationError {

website/docs/docs/subscription.md

@@ -10,6 +10,18 @@ This section is about the first part of the flow.
 
 In order to handle notifications, you must register the `remoteNotificationsRegistered` event beforehand.
 
+## Important: Token Refresh Handling
+
+:::caution Critical for Android
+FCM (Firebase Cloud Messaging) can refresh the device token at any time, not just during initial registration. This happens when:
+- The app is restored on a new device
+- The user reinstalls the app
+- The user clears app data
+- FCM determines the token needs to be refreshed (e.g., after extended inactivity)
+- Security-related token rotation
+
+**Your app must always sync the token to your backend whenever `remoteNotificationsRegistered` fires**, not just the first time. Failure to do so will cause push notifications to silently stop working for affected users.
+:::
 
 In your React Native app:
 
@@ -22,15 +34,78 @@ class App extends Component {
 		Notifications.registerRemoteNotifications();
 
 		Notifications.events().registerRemoteNotificationsRegistered((event: Registered) => {
-			// TODO: Send the token to my server so it could send back push notifications...
-			console.log("Device Token Received", event.deviceToken);
+			// IMPORTANT: Always sync the token to your backend!
+			// This event fires on initial registration AND on token refresh.
+			console.log("Device Token Received/Refreshed", event.deviceToken);
+			this.syncTokenToBackend(event.deviceToken);
 		});
 		Notifications.events().registerRemoteNotificationsRegistrationFailed((event: RegistrationError) => {
 			console.error(event);
 		});
 	}
+	
+	async syncTokenToBackend(token: string) {
+		// POST the token to your server every time - even if you think it hasn't changed
+		await fetch('https://your-server.com/api/push-token', {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({ token }),
+		});
+	}
+}
+
+```
+
+### React Hooks Example
+
+```jsx
+import { useEffect } from 'react';
+import { Notifications } from 'react-native-notifications';
+
+function App() {
+	useEffect(() => {
+		// Set up the listener BEFORE calling registerRemoteNotifications
+		const subscription = Notifications.events().registerRemoteNotificationsRegistered((event) => {
+			console.log("Device Token Received", event.deviceToken);
+			
+			// On Android, you can check if this is an FCM-initiated refresh
+			if (event.isRefresh) {
+				console.log("Token was refreshed by FCM - old token is now invalid");
+			}
+			
+			// Always sync the token to your backend
+			syncTokenToBackend(event.deviceToken, { isRefresh: event.isRefresh });
+		});
+		
+		const errorSubscription = Notifications.events().registerRemoteNotificationsRegistrationFailed((event) => {
+			console.error("Registration failed", event);
+		});
+
+		Notifications.registerRemoteNotifications();
+
+		return () => {
+			subscription.remove();
+			errorSubscription.remove();
+		};
+	}, []);
+	
+	// ...
 }
+```
+
+### The `isRefresh` Property (Android Only)
 
+On Android, the `Registered` event includes an `isRefresh` boolean property:
+
+- `true`: The token was refreshed by FCM automatically. This means the previous token is now **invalid** and you must update your backend immediately.
+- `false`: The token was received during app initialization or a manual refresh request.
+- `undefined`: On iOS, this property is not set.
+
+```typescript
+interface Registered {
+  deviceToken: string;
+  isRefresh?: boolean; // Android only
+}
 ```
 
 When you have the device token, POST it to your server and register the device in your notifications provider (Amazon SNS, Azure, etc.).