React Native Push Notifications: Complete Setup Guide (2026)

# Using npm
npm install @react-native-firebase/app @react-native-firebase/messaging

# Using yarn
yarn add @react-native-firebase/app @react-native-firebase/messaging

cd ios && pod install && cd ..

// android/build.gradle  (project-level)
buildscript {
  dependencies {
    // ... existing deps
    classpath 'com.google.gms:google-services:4.4.1'
  }
}

// android/app/build.gradle
apply plugin: 'com.google.gms.google-services'   // add at bottom of file

dependencies {
  // ... existing deps
  implementation platform('com.google.firebase:firebase-bom:32.7.0')
  implementation 'com.google.firebase:firebase-messaging'
}

<!-- android/app/src/main/AndroidManifest.xml -->
<manifest ...>
  <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
  
  <application ...>
    <!-- Required for heads-up notifications on Android 8+ -->
    <meta-data
      android:name="com.google.firebase.messaging.default_notification_channel_id"
      android:value="pushpilot_default"/>
  </application>
</manifest>

<!-- ios/YourApp/YourApp.entitlements -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>aps-environment</key>
  <string>development</string>  <!-- change to 'production' for release builds -->
</dict>
</plist>

import messaging from '@react-native-firebase/messaging';

export async function requestNotificationPermission() {
  const authStatus = await messaging().requestPermission();

  const enabled =
    authStatus === messaging.AuthorizationStatus.AUTHORIZED ||
    authStatus === messaging.AuthorizationStatus.PROVISIONAL;

  if (enabled) {
    console.log('Notification permission granted, status:', authStatus);
    return true;
  }

  console.log('Notification permission denied');
  return false;
}

import messaging from '@react-native-firebase/messaging';

export async function getFCMToken(): Promise<string | null> {
  try {
    // Check if device supports FCM (physical device only — not simulator)
    if (!messaging().isDeviceRegisteredForRemoteMessages) {
      await messaging().registerDeviceForRemoteMessages();
    }

    const token = await messaging().getToken();
    console.log('FCM Token:', token);
    return token;
  } catch (error) {
    console.error('Failed to get FCM token:', error);
    return null;
  }
}

// Listen for token refreshes — always update your backend
messaging().onTokenRefresh(async (newToken) => {
  console.log('FCM token refreshed:', newToken);
  await sendTokenToBackend(newToken);
});

async function sendTokenToBackend(token: string) {
  await fetch('https://api.yourapp.com/devices', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      fcm_token: token,
      platform: Platform.OS,     // 'ios' or 'android'
      user_id: getCurrentUserId(), // your auth user id
    }),
  });
}

import messaging, { FirebaseMessagingTypes } from '@react-native-firebase/messaging';
import { useEffect } from 'react';

export function useNotificationListeners() {
  useEffect(() => {
    // 1. Foreground messages (app is open and in focus)
    const unsubscribeForeground = messaging().onMessage(
      async (remoteMessage: FirebaseMessagingTypes.RemoteMessage) => {
        console.log('Foreground notification received:', remoteMessage);
        // Show an in-app banner or update UI state
        showInAppNotification(remoteMessage.notification);
      }
    );

    // 2. User tapped a notification while app was in background
    const unsubscribeBackground = messaging().onNotificationOpenedApp(
      (remoteMessage: FirebaseMessagingTypes.RemoteMessage) => {
        console.log('Notification tapped (background):', remoteMessage);
        handleNotificationNavigation(remoteMessage.data);
      }
    );

    return () => {
      unsubscribeForeground();
      unsubscribeBackground();
    };
  }, []);
}

// index.js  (or your app entry point — OUTSIDE the component tree)
import { AppRegistry } from 'react-native';
import messaging from '@react-native-firebase/messaging';
import App from './App';
import { name as appName } from './app.json';

// Background / quit-state handler
// This runs in a separate JS context — no React hooks or state allowed here
messaging().setBackgroundMessageHandler(async (remoteMessage) => {
  console.log('Background message received:', remoteMessage.messageId);
  // You can update AsyncStorage, trigger local notifications, etc.
  // Do NOT try to update React state or navigate here
});

AppRegistry.registerComponent(appName, () => App);

// Check if the app was launched from a notification (quit state)
// Place this in your root navigator or App.tsx
useEffect(() => {
  messaging()
    .getInitialNotification()
    .then((remoteMessage) => {
      if (remoteMessage) {
        console.log('App launched from notification:', remoteMessage);
        handleNotificationNavigation(remoteMessage.data);
      }
    });
}, []);

import { NavigationContainerRef } from '@react-navigation/native';

export function handleNotificationNavigation(
  data: Record<string, string> | undefined,
  navigationRef: NavigationContainerRef<any>
) {
  if (!data) return;

  const { screen, params } = data;

  switch (screen) {
    case 'OrderDetail':
      navigationRef.navigate('OrderDetail', { orderId: params });
      break;
    case 'Promotion':
      navigationRef.navigate('Promotions', { promoId: params });
      break;
    default:
      navigationRef.navigate('Home');
  }
}

// After getting the FCM token, register it with PushPilot
async function registerWithPushPilot(fcmToken: string, userId?: string) {
  await fetch('https://api.pushpilot.ai/v1/devices', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.PUSHPILOT_API_KEY!,
    },
    body: JSON.stringify({
      token: fcmToken,
      platform: Platform.OS === 'ios' ? 'apns' : 'fcm',
      external_id: userId,           // optional: your user identifier
      attributes: {
        app_version: getAppVersion(),
        locale: getLocale(),
      },
    }),
  });
}

curl -X POST https://fcm.googleapis.com/v1/projects/YOUR_PROJECT_ID/messages:send \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "token": "YOUR_FCM_TOKEN",
      "notification": {
        "title": "Test notification",
        "body": "If you see this, FCM is working."
      },
      "data": {
        "screen": "Home"
      }
    }
  }'