React Native Push Notifications

Integrate real-time push notifications into your React Native app using Firebase Cloud Messaging (FCM) for Android and Apple Push Notification service (APNs) for iOS, ensuring users stay connected across both platforms.

React Native’s cross-platform nature allows unified push notification handling, but platform-specific configuration and certificates are still required.

Prerequisites

Before implementing push notifications, ensure you have:

Firebase Project

Active Firebase project with FCM enabled for both platforms

Platform Certificates

Android FCM service account JSON and iOS APNs .p12 certificate

social.plus SDK

social.plus TypeScript SDK properly integrated

Development Setup

React Native development environment configured for both platforms

Step 1: Install Dependencies

Core Firebase Dependencies

# Install React Native Firebase
npm install @react-native-firebase/app @react-native-firebase/messaging

# Optional: For enhanced notification handling
npm install @react-native-async-storage/async-storage
npm install react-native-permissions

# For iOS, install pods
cd ios && pod install && cd ..

Always use the latest stable versions. Check the React Native Firebase documentation for current compatibility.

Additional Utility Libraries

# For better permission handling
npm install react-native-permissions

# For local storage
npm install @react-native-async-storage/async-storage

# For device info (optional)
npm install react-native-device-info

Step 2: Platform Configuration

Android Configuration

Add google-services.json to android/app/
Update build.gradle files:

// android/build.gradle
buildscript {
  dependencies {
    classpath 'com.google.gms:google-services:4.3.15'
  }
}

// android/app/build.gradle
apply plugin: 'com.google.gms.google-services'

android {
  compileSdkVersion 34
  
  defaultConfig {
    minSdkVersion 21
    targetSdkVersion 34
  }
}

Add permissions to AndroidManifest.xml:

<!-- android/app/src/main/AndroidManifest.xml -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    
    <!-- Push notification permissions -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
    <uses-permission android:name="android.permission.VIBRATE" />
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
    
    <application>
        <!-- Firebase messaging service -->
        <service
            android:name="io.invertase.firebase.messaging.RNFirebaseMessagingService"
            android:exported="false">
            <intent-filter>
                <action android:name="com.google.firebase.MESSAGING_EVENT" />
            </intent-filter>
        </service>
        
        <!-- Your activities -->
    </application>
</manifest>

iOS Configuration

Add GoogleService-Info.plist to iOS project in Xcode
Enable Push Notifications capability in Xcode:
- Select your target → Signing & Capabilities → + Capability → Push Notifications
Update AppDelegate for Firebase:

// ios/YourApp/AppDelegate.mm
#import <Firebase.h>
#import <UserNotifications/UserNotifications.h>

@interface AppDelegate () <UNUserNotificationCenterDelegate>
@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  // Configure Firebase
  [FIRApp configure];
  
  // Set notification delegate
  [UNUserNotificationCenter currentNotificationCenter].delegate = self;
  
  return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

// Handle notification when app is in foreground
- (void)userNotificationCenter:(UNUserNotificationCenter *)center
       willPresentNotification:(UNNotification *)notification
         withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
  completionHandler(UNNotificationPresentationOptionAlert | UNNotificationPresentationOptionBadge | UNNotificationPresentationOptionSound);
}

@end

Update Info.plist for background modes:

<!-- ios/YourApp/Info.plist -->
<dict>
    <!-- Existing keys -->
    
    <key>UIBackgroundModes</key>
    <array>
        <string>background-fetch</string>
        <string>remote-notification</string>
    </array>
    
    <key>FirebaseAppDelegateProxyEnabled</key>
    <false/>
</dict>

Android - FCM Service Account

Generate FCM service account JSON:
- Go to Firebase Console → Project Settings → Service Accounts
- Click “Generate new private key”
- Download the JSON file
Upload to social.plus Console:
- Navigate to Settings → Push Notifications
- Upload the FCM service account JSON file

iOS - APNs Certificate

Generate .p12 certificate following the iOS setup guide
Upload to social.plus Console:
- Navigate to Settings → Push Notifications
- Upload the .p12 file with password

Refer to the iOS Push Notification Certificate Setup Guide for detailed certificate generation instructions.

Best Practices

Cross-Platform Considerations

Platform-Specific Handling: While React Native allows code sharing, handle platform differences appropriately.

// Handle platform-specific token retrieval
const getTokenForPlatform = async () => {
  if (Platform.OS === 'ios') {
    // iOS requires APNs token first
    const apnsToken = await messaging().getAPNSToken();
    if (!apnsToken) {
      console.log('APNs token not available, requesting...');
      // Handle APNs token unavailability
      return null;
    }
    return messaging().getToken();
  } else {
    // Android uses FCM token directly
    return messaging().getToken();
  }
};

Permission Management

Strategic Permission Requests: Request permissions at meaningful moments, not app launch.

// Good: Request when user joins a channel
const handleChannelJoin = async () => {
  await joinChannel();
  
  // Now request notification permissions for channel updates
  const hasPermission = await requestNotificationPermission();
  if (hasPermission) {
    console.log('User will receive channel notifications');
  }
};

// Bad: Request immediately on app launch
useEffect(() => {
  // Don't do this immediately
  // requestNotificationPermission();
}, []);

State Management

Token State Synchronization: Keep token state consistent across app lifecycle and updates.

// Use context for app-wide token state
const NotificationContext = createContext({
  token: null,
  permissionStatus: 'not-determined',
  refreshToken: () => {},
});

const NotificationProvider = ({ children }) => {
  const [token, setToken] = useState(null);
  const [permissionStatus, setPermissionStatus] = useState('not-determined');
  
  const refreshToken = useCallback(async () => {
    const newToken = await TokenManager.refreshTokenIfNeeded();
    setToken(newToken);
  }, []);
  
  return (
    <NotificationContext.Provider value={{ token, permissionStatus, refreshToken }}>
      {children}
    </NotificationContext.Provider>
  );
};

Error Handling

Robust Error Management: Implement comprehensive error handling for various failure scenarios.

class NotificationErrorHandler {
  static handleError(error: any, context: string) {
    console.error(`Notification error in ${context}:`, error);
    
    // Log to crash reporting service
    // crashlytics().recordError(error);
    
    // Handle specific error types
    if (error.code === 'messaging/unknown') {
      this.handleUnknownError(error);
    } else if (error.code === 'messaging/registration-token-not-registered') {
      this.handleTokenNotRegistered();
    } else if (error.code === 'messaging/invalid-registration-token') {
      this.handleInvalidToken();
    }
  }
  
  static handleTokenNotRegistered() {
    // Clear stored token and re-register
    TokenManager.clearStoredData();
    // Re-initialize push notifications
  }
  
  static handleInvalidToken() {
    // Get new token
    TokenManager.refreshTokenIfNeeded();
  }
}

Testing Strategies

Firebase Console Testing

Use Firebase Console to send test messages:
- Go to Firebase Console → Cloud Messaging → Send Test Message
- Use the FCM token from your debug component
- Test different message types and data payloads
Test Both Platforms:
- iOS: Test with TestFlight builds (debug builds don’t receive push notifications)
- Android: Test with both debug and release builds

Troubleshooting

Common Issues

Token Not Generated:

Firebase Configuration: Verify google-services.json (Android) and GoogleService-Info.plist (iOS) are correctly placed
Permissions: Ensure notification permissions are granted
Network Connectivity: Check internet connection
APNs Token (iOS): Verify APNs token is available before requesting FCM token

// Debug token generation issues
const debugTokenIssues = async () => {
  console.log('=== Token Debug ===');
  
  // Check permissions
  const authStatus = await messaging().hasPermission();
  console.log('Permission status:', authStatus);
  
  // Check device registration
  console.log('Device registered:', messaging.isDeviceRegisteredForRemoteMessages);
  
  // For iOS, check APNs token
  if (Platform.OS === 'ios') {
    const apnsToken = await messaging().getAPNSToken();
    console.log('APNs token available:', !!apnsToken);
  }
  
  // Try to get token
  try {
    const token = await messaging().getToken();
    console.log('FCM token:', token ? 'Available' : 'Not available');
  } catch (error) {
    console.error('Token generation error:', error);
  }
};

Platform-Specific Issues

iOS Specific:

Push notifications don’t work in iOS Simulator
Debug builds can’t receive push notifications
Requires valid APNs certificate uploaded to social.plus Console

Android Specific:

Android 13+ requires runtime notification permission
Verify FCM service account JSON is uploaded to console
Check that google-services.json matches your package name

// Platform-specific debugging
const debugPlatformIssues = async () => {
  if (Platform.OS === 'ios') {
    console.log('iOS Debug Info:');
    console.log('- Running on simulator:', __DEV__ && Platform.isPad);
    console.log('- Bundle ID:', getBundleId());
    
    const apnsToken = await messaging().getAPNSToken();
    console.log('- APNs token available:', !!apnsToken);
  } else {
    console.log('Android Debug Info:');
    console.log('- Android version:', Platform.Version);
    console.log('- Package name:', getPackageName());
    
    if (Platform.Version >= 33) {
      const hasPermission = await PermissionsAndroid.check(
        PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS
      );
      console.log('- POST_NOTIFICATIONS permission:', hasPermission);
    }
  }
};

React Native Firebase

Official React Native Firebase documentation

FCM Legacy Migration

Guide for migrating from FCM legacy API

iOS Certificate Setup

Detailed iOS APNs certificate generation guide

Android FCM Setup

Android Firebase Cloud Messaging configuration

Testing Requirements: iOS push notifications require TestFlight or App Store builds. Android notifications work in both debug and release builds, but release builds are recommended for production testing.

Powered by

Getting Started

Fundamentals

Social

Chat

React Native Push Notifications

Prerequisites

Firebase Project

Platform Certificates

social.plus SDK

Development Setup

Step 1: Install Dependencies

Core Firebase Dependencies

Additional Utility Libraries

Step 2: Platform Configuration

Android Configuration

iOS Configuration

Android - FCM Service Account

iOS - APNs Certificate

Best Practices

Testing Strategies

Firebase Console Testing

Troubleshooting

React Native Firebase

FCM Legacy Migration

iOS Certificate Setup

Android FCM Setup

Powered by

Getting Started

Fundamentals

Social

Chat

​Prerequisites

Firebase Project

Platform Certificates

social.plus SDK

Development Setup

​Step 1: Install Dependencies

​Core Firebase Dependencies

​Additional Utility Libraries

​Step 2: Platform Configuration

​Android Configuration

​iOS Configuration

​Step 3: Upload Certificates to social.plus Console

​Android - FCM Service Account

​iOS - APNs Certificate

​Best Practices

​Testing Strategies

​Firebase Console Testing

​Troubleshooting

​Related Resources

React Native Firebase

FCM Legacy Migration

iOS Certificate Setup

Android FCM Setup

Prerequisites

Step 1: Install Dependencies

Core Firebase Dependencies

Additional Utility Libraries

Step 2: Platform Configuration

Android Configuration

iOS Configuration

Step 3: Upload Certificates to social.plus Console

Android - FCM Service Account

iOS - APNs Certificate

Best Practices

Testing Strategies

Firebase Console Testing

Troubleshooting

Related Resources