Push Notifications for React Native: FCM and APNs Setup

Tappd lets you register device push tokens from Firebase Cloud Messaging (FCM) on Android and Apple Push Notification Service (APNs) on iOS, then send targeted push notifications through the Tappd platform. This guide walks you through requesting permissions, retrieving tokens, registering them with the SDK, and handling incoming notifications on both platforms.

Prerequisites

Before setting up push notifications, make sure you have:

Firebase Cloud Messaging (FCM) configured for Android
Apple Push Notification Service (APNs) configured for iOS
Push notification certificates or authentication keys uploaded to Firebase Console
A user identified via tappd.identify() — push tokens are always associated with an identified user

You must call tappd.identify() before registering a push token. Attempting to register a token for an anonymous session will fail.

Installation

Install the React Native Firebase messaging package and its peer dependency:

npm install @react-native-firebase/app @react-native-firebase/messaging
cd ios && pod install && cd ..

Setup

Request permissions

On iOS you must explicitly request permission before you can receive notifications. On Android, FCM handles permission automatically.

import messaging from '@react-native-firebase/messaging';
import { Platform } from 'react-native';

async function requestPushPermission() {
  if (Platform.OS === 'ios') {
    const authStatus = await messaging().requestPermission();
    const enabled =
      authStatus === messaging.AuthorizationStatus.AUTHORIZED ||
      authStatus === messaging.AuthorizationStatus.PROVISIONAL;
    return enabled;
  } else {
    // Android — FCM requests permissions automatically
    return true;
  }
}

Get the push token

Retrieve the FCM token that identifies this device:

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

async function getPushToken() {
  try {
    const token = await messaging().getToken();
    return token;
  } catch (error) {
    console.error('Failed to get push token:', error);
    return null;
  }
}

Pass the token and the platform string to registerPushToken():

import TappdSDK from '@tappd/mobile-sdk';
import messaging from '@react-native-firebase/messaging';
import { Platform } from 'react-native';

const tappd = new TappdSDK({ appId: 'YOUR_APP_ID' });

// Identify the user first
await tappd.identify({
  external_id: 'user_123',
  email: 'john@example.com',
});

// Get and register the token
const token = await messaging().getToken();
if (token) {
  await tappd.registerPushToken(
    token,
    Platform.OS === 'ios' ? 'ios' : 'android'
  );
}

Complete Setup Example

Here’s a full App component that wires up all three steps and handles token refresh in one place:

import React, { useEffect } from 'react';
import messaging from '@react-native-firebase/messaging';
import { Platform } from 'react-native';
import TappdSDK from '@tappd/mobile-sdk';

const tappd = new TappdSDK({ appId: 'YOUR_APP_ID' });

function App() {
  useEffect(() => {
    setupPushNotifications();
  }, []);

  async function setupPushNotifications() {
    try {
      // Request permission on iOS
      if (Platform.OS === 'ios') {
        const authStatus = await messaging().requestPermission();
        const enabled =
          authStatus === messaging.AuthorizationStatus.AUTHORIZED ||
          authStatus === messaging.AuthorizationStatus.PROVISIONAL;

        if (!enabled) {
          console.log('Push notifications not authorized');
          return;
        }
      }

      // Get token and register with Tappd
      const token = await messaging().getToken();
      if (token) {
        await tappd.registerPushToken(
          token,
          Platform.OS === 'ios' ? 'ios' : 'android'
        );
        console.log('Push token registered');
      }

      // Re-register automatically when the token rotates
      messaging().onTokenRefresh(async (newToken) => {
        await tappd.registerPushToken(
          newToken,
          Platform.OS === 'ios' ? 'ios' : 'android'
        );
        console.log('Push token refreshed');
      });
    } catch (error) {
      console.error('Push notification setup failed:', error);
    }
  }

  return (
    // Your app
  );
}

Check Subscription Status

After registering a token, you can verify the user’s subscription state:

async function checkSubscription() {
  try {
    const status = await tappd.checkPushSubscription();

    console.log('Subscribed:', status.subscribed);
    console.log('Status:', status.status); // 'subscribed', 'opted_in', or 'unsubscribed'
    console.log('Device Count:', status.deviceCount);

    return status;
  } catch (error) {
    console.error('Failed to check subscription:', error);
    return null;
  }
}

Handle Token Refresh

FCM occasionally rotates push tokens. Always listen for refresh events and re-register so your user’s token stays current:

import messaging from '@react-native-firebase/messaging';
import { Platform } from 'react-native';

messaging().onTokenRefresh(async (newToken) => {
  try {
    await tappd.registerPushToken(
      newToken,
      Platform.OS === 'ios' ? 'ios' : 'android'
    );
    console.log('Token refreshed and registered');
  } catch (error) {
    console.error('Failed to register refreshed token:', error);
  }
});

Handle Push Notifications

Foreground
Background
Notification taps

Handle messages while the app is in the foreground using onMessage():

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

messaging().onMessage(async (remoteMessage) => {
  console.log('Foreground message:', remoteMessage);

  // Track receipt
  await tappd.track('push_notification.received', {
    notificationId: remoteMessage.messageId,
    title: remoteMessage.notification?.title,
    body: remoteMessage.notification?.body,
  });

  // Show your custom in-app notification UI here
});

Register a background handler in your index.js entry file. This runs in a separate context, so the main SDK instance may not be available.

// index.js
import messaging from '@react-native-firebase/messaging';

messaging().setBackgroundMessageHandler(async (remoteMessage) => {
  console.log('Background message:', remoteMessage);

  // The SDK instance may not be initialized here.
  // If you need to track receipt, call the Tappd API directly.
});

Register setBackgroundMessageHandler() in index.js before AppRegistry.registerComponent(). It must be registered at module load time, not inside a React component.

Track when users open the app by tapping a notification. Handle both cold-start (app was closed) and warm-start (app was backgrounded) cases:

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

// Cold start — app launched by tapping the notification
messaging()
  .getInitialNotification()
  .then(async (remoteMessage) => {
    if (remoteMessage) {
      await tappd.trackPushOpen(remoteMessage);
    }
  });

// Warm start — app was already running or backgrounded
messaging().onNotificationOpenedApp(async (remoteMessage) => {
  await tappd.trackPushOpen(remoteMessage);
});

Platform-Specific Setup

iOS
Android

1. Enable the Push Notifications capability

In Xcode:

Open your project and select your app target.
Go to Signing & Capabilities.
Click + Capability.
Add Push Notifications.

2. Configure APNs in Firebase Console

Open Firebase Console → Project Settings → Cloud Messaging.
Under the Apple app configuration section, upload your APNs Authentication Key (.p8) or APNs Certificate (.p12).

APNs Authentication Keys (.p8) are preferred over certificates — they don’t expire and work across all your apps.

1. Add the Firebase configuration file

Download google-services.json from the Firebase Console and place it in android/app/.

2. Configure the project-level `build.gradle`

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

3. Apply the plugin in the app-level `build.gradle`

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

After modifying Gradle files, run cd android && ./gradlew clean to clear the build cache before rebuilding.

Troubleshooting

Token not registering

If registerPushToken() throws an error or the token doesn’t appear in the Tappd dashboard:

Ensure identify() was called first — the SDK requires a known user before it can associate a device token.
Check FCM/APNs configuration — on iOS, confirm the APNs key or certificate is uploaded to Firebase Console. On Android, confirm google-services.json is in android/app/.
Verify network connectivity — token registration requires an active internet connection.
Check your error logs — wrap registerPushToken() in try-catch and log any caught errors.

Notifications not being received

If push notifications aren’t arriving on the device:

Verify the token is registered — check the Tappd dashboard to confirm the device appears under the user’s profile.
Check subscription status — call tappd.checkPushSubscription() and inspect the status field.
Verify FCM/APNs setup — use the Firebase Console’s test message tool to send a direct test notification to the token.
Check device permissions — on iOS, go to Settings → Notifications and confirm notifications are allowed for your app.

Best Practices

Identify users before registering tokens — push tokens are tied to users; always call identify() first.
Always listen for token refresh — FCM can rotate tokens at any time. A stale token means missed notifications.
Track opens on both cold and warm starts — handle both getInitialNotification() and onNotificationOpenedApp() to get complete open-rate data.
Wrap everything in try-catch — token retrieval and registration can fail due to network issues or misconfigured credentials.
Use Platform.OS — always pass 'ios' or 'android' to registerPushToken() so Tappd routes notifications through the correct provider.

​Prerequisites

​Installation

​Setup

​Complete Setup Example

​Check Subscription Status

​Handle Token Refresh

​Handle Push Notifications

​Platform-Specific Setup

​1. Enable the Push Notifications capability

​2. Configure APNs in Firebase Console

​1. Add the Firebase configuration file

​2. Configure the project-level build.gradle

​3. Apply the plugin in the app-level build.gradle

​Troubleshooting

​Best Practices

Prerequisites

Installation

Setup

Complete Setup Example

Check Subscription Status

Handle Token Refresh

Handle Push Notifications

Platform-Specific Setup

1. Enable the Push Notifications capability

2. Configure APNs in Firebase Console

1. Add the Firebase configuration file

2. Configure the project-level `build.gradle`

3. Apply the plugin in the app-level `build.gradle`

Troubleshooting

Best Practices