React Native push notifications

The pushix-react-native package registers Android phones and iPhones with Pushix, shows notifications, tells your app when one is tapped, and shows in-app messages. It works with plain React Native and with Expo development builds.

Under the hood it uses React Native Firebase for the push token and messages, Notifee to draw notifications (buttons, pictures, channels, notifications while the app is open) and AsyncStorage to remember the device.

Requirements#

• React Native 0.76 or newer (old or new architecture), React 18.2+
• @react-native-firebase/app and @react-native-firebase/messaging 22 or newer. Version 27 needs dynamic frameworks on iOS (see iOS setup).
• @notifee/react-native 9
• @react-native-async-storage/async-storage 1.19 or newer (2.x and 3.x work)
• Android minSdk 24 and compileSdk 34 or newer
• iOS 15.0 or newer, Xcode 16, and a paid Apple Developer account (push needs an APNs key)
• One Firebase project with your Android app and your iOS app in it.
• Expo: a development build (npx expo run:android, EAS Build). Expo Go doesn't contain these native modules.

1. Add the package#

Copy the sdks/react-native folder from your Pushix download next to your app (or into a private Git repository) and install it with its peer dependencies:

npm install --install-links ../pushix/sdks/react-native
npm install @react-native-firebase/app @react-native-firebase/messaging \
  @notifee/react-native @react-native-async-storage/async-storage
cd ios && pod install

--install-links makes npm copy the package into node_modules. Without it npm makes a symlink to a folder outside your project, which Metro refuses ("Unable to resolve module pushix-react-native … could not be found within the project"). A later plain npm install turns the copy back into a symlink, so also add this line to your app's .npmrc:

install-links=true

You can instead run npm pack in the SDK folder and npm install the .tgz file. With Yarn 1: yarn add file:../pushix/sdks/react-native (Yarn copies it).

If the app already uses another push SDK, remove it (and its Expo config plugin, if any): two push SDKs in one app fight over Firebase messaging and the iOS notification delegate.

2. Add Firebase to the app#

Follow the React Native Firebase getting started guide for @react-native-firebase/app. In short:

• Android: download google-services.json from Firebase into android/app/, add classpath("com.google.gms:google-services:4.5.0") to the dependencies of android/build.gradle and apply plugin: "com.google.gms.google-services" to android/app/build.gradle.
• iOS: add GoogleService-Info.plist to the app target in Xcode, call FirebaseApp.configure() (with import FirebaseCore) at the start of application(_:didFinishLaunchingWithOptions:) in AppDelegate.swift, and use dynamic frameworks in ios/Podfile (React Native Firebase 27 gets Firebase through Swift Package Manager):

platform :ios, '15.0'
use_frameworks! :linkage => :dynamic

Use the Firebase project whose service account you upload to Pushix. A different project makes every send fail with SENDER_ID_MISMATCH.

Then create firebase.json in the project root (next to package.json):

{
  "react-native": {
    "messaging_android_notification_channel_id": "pushix_default"
  }
}

That points notifications Android shows while the app is closed at the SDK's high-importance channel. Leave messaging_ios_foreground_presentation_options out (or []): the SDK shows foreground notifications itself, and iOS would otherwise show them twice. Leave messaging_installation_id_enabled off; Pushix sends to FCM tokens.

3. Android setup#

Notification icon — Android draws the small icon as a white silhouette, so a full-colour launcher icon shows up as a white square. Create a white-on-transparent icon (Android Studio → New → Image Asset → Notification Icons), name it ic_stat_notification, and use it in two places:

<!-- android/app/src/main/AndroidManifest.xml, inside <application>: for notifications Android shows while the app is closed -->
<meta-data android:name="com.google.firebase.messaging.default_notification_icon"
    android:resource="@drawable/ic_stat_notification" />

and defaultSmallIcon: 'ic_stat_notification' in Pushix.initialize (for notifications the SDK draws). You can also set it once for all sends in the dashboard (App settings → Android defaults). Don't add default_notification_channel_id or default_notification_color to the manifest: React Native Firebase already declares them (from firebase.json), and a second copy breaks the build. Set the colour with "messaging_android_notification_color": "@color/your_colour" in firebase.json.

Permission — Android 13+ asks before showing notifications. Firebase declares the permission; if the dialog never appears, add it to AndroidManifest.xml yourself:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

Keep icons and sounds in release builds — icons and sounds named only in messages (small_icon, android_sound) look unused to the build and get removed by resource shrinking. Create android/app/src/main/res/raw/keep.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:keep="@drawable/ic_stat_*,@raw/*" />

If a message names an icon, sound or channel that doesn't exist in the app, the SDK falls back to the default icon, sound and channel instead of dropping the notification. Notification buttons need no manifest entries; Notifee handles them.

4. iOS setup#

iPhone notifications travel from Pushix through Firebase to Apple (APNs). Three one-time steps:

APNs key in Firebase. In the Apple Developer site create a key with Apple Push Notifications service (APNs) and download the .p8 file. In Firebase → Project settings → Cloud Messaging → Apple app configuration, upload it with its Key ID and your Team ID. One key works for all your apps.

Capabilities. Open ios/YourApp.xcworkspace in Xcode, select the app target → Signing & Capabilities, and add Push Notifications and Background Modes with Remote notifications ticked.

Deployment target. iOS 15.0 or newer, in the Podfile (above) and under the target → General → Minimum Deployments.

Unlike the Flutter SDK there is no UNUserNotificationCenter line to add to the AppDelegate: React Native Firebase and Notifee install the notification delegate themselves.

Pictures and buttons on iPhone (optional)#

While the app is open the SDK shows pictures and buttons itself. When the app is in the background, iOS only shows a picture (big_picture or ios_attachments) and buttons when the app has a Notification Service Extension. Pushix has one ready:

1. Open ios/YourApp.xcworkspace in Xcode: File → New → Target → Notification Service Extension, name it NotificationService and click Finish (choose "Cancel" if Xcode offers to activate the scheme).
2. Add Pushix's extension library to it in ios/Podfile, then run cd ios && pod install:

target 'NotificationService' do
  use_frameworks!
  pod 'Pushix/Extension', :path => '../../pushix/sdks/ios'   # the sdks/ios folder from your Pushix download
end

3. Replace the generated NotificationService.swift with:

import Pushix

class NotificationService: PushixNotificationServiceExtension {}

The extension downloads the picture and adds the message's buttons (it registers a category for them); it needs no Firebase code. Deployment target 13.0 or later.

Your own button categories (optional)#

With the extension above, buttons need nothing else. To use a category of your own instead, register it at start-up:

import notifee from '@notifee/react-native';

notifee.setNotificationCategories([
  { id: 'OFFER_ACTIONS', actions: [{ id: 'claim', title: 'Claim', foreground: true }, { id: 'later', title: 'Later' }] },
]);

and send "ios_category": "OFFER_ACTIONS" (composer → iOS options → Category). The tapped button's id arrives as event.result.actionId for notifications shown while the app is open. For notifications iOS drew itself while the app was in the background, Firebase reports taps on the notification but not which button, so such a tap may arrive without actionId.

Badges#

Send ios_badgeType Increase or SetTo with ios_badgeCount. Pushix keeps each iPhone's count and resets it to zero on the server whenever the app opens. To clear the number on the icon itself when the app opens, call notifee.setBadgeCount(0).

5. Register the background handlers (index.js)#

Android starts your app's JavaScript without any screens to handle a push that arrives while the app is closed. Only code at the top level of the entry file runs then, so register the SDK's two handlers in index.js, before AppRegistry:

// index.js
import notifee from '@notifee/react-native';
import { getMessaging, setBackgroundMessageHandler } from '@react-native-firebase/messaging';
import { pushixBackgroundHandler, pushixNotifeeBackgroundHandler } from 'pushix-react-native';
import { AppRegistry } from 'react-native';
import App from './App';
import { name as appName } from './app.json';

// Draws Android notifications with buttons, a large icon or grouping while the app is closed.
setBackgroundMessageHandler(getMessaging(), pushixBackgroundHandler);
// Reports taps on those notifications and their buttons.
notifee.onBackgroundEvent(pushixNotifeeBackgroundHandler);

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

Plain notifications (title, text, picture) are shown by Android and iOS without the handlers, but buttons and large icons need them. Firebase and Notifee each allow only one background handler; if your app already has one, call Pushix from it:

setBackgroundMessageHandler(getMessaging(), async (message) => {
  await pushixBackgroundHandler(message);
  // ...your own code
});

notifee.onBackgroundEvent(async (event) => {
  await pushixNotifeeBackgroundHandler(event);
  // ...your own code
});

6. Initialize#

Call initialize once from your root component. Not at the top of index.js: that also runs when Android handles a push in the background.

// App.tsx
import { useEffect } from 'react';
import { LogLevel, Pushix, PushixInAppMessageHost } from 'pushix-react-native';

export default function App() {
  useEffect(() => {
    Pushix.Debug.setLogLevel(LogLevel.Warn); // Verbose while setting up
    Pushix.initialize('YOUR_APP_ID', {
      serverUrl: 'https://pushix.in',
      defaultSmallIcon: 'ic_stat_notification', // Android
    });

    Pushix.Notifications.addEventListener('click', (event) => {
      const data = event.notification.additionalData ?? {};
      // route to a screen, e.g. data.screen === 'orders'
    });
  }, []);

  return (
    <>
      <RootNavigator />
      <PushixInAppMessageHost />
    </>
  );
}

initialize options:

Then ask for permission at a sensible moment (iPhone and Android 13+ show the system dialog):

await Pushix.Notifications.requestPermission(true);

With true, when the dialog can no longer appear because the user said no before, the app's notification settings open instead.

When the user logs in to your app, link the device to your user id so your backend can target them:

Pushix.login(String(user.id)); // on login
Pushix.logout();               // on logout (also clears tags)

Calls made before initialize wait for it. That's it. Open the app once and the device appears in the dashboard under Subscribers, marked Android or iOS.

API overview#

Exported types include PushixNotification (notificationId, title, body, additionalData, launchURL, actionButtons, bigPicture, …), NotificationClickEvent, NotificationWillDisplayEvent, InAppMessageClickEvent and LogLevel.

Handling taps#

Pushix.Notifications.addEventListener('click', (event) => {
  const n = event.notification;
  console.log(n.notificationId);      // id from the REST API
  console.log(n.additionalData);      // your "data" object
  console.log(n.launchURL);           // your "url"
  console.log(event.result.actionId); // button id, or undefined for the notification itself
  console.log(event.result.url);      // the button's url, or the launch url
});

• Taps that open the app from closed are delivered as soon as you add the first click listener (on the next tick), so add it early.
• http:// and https:// URLs open in the browser automatically. Turn that off with autoOpenWebUrls: false.
• Each tap is reported to the server and shows up as “Clicked” in the dashboard.

Deep links (myshop://orders) are not opened automatically; route them yourself. With React Navigation, use a navigation ref:

import { createNavigationContainerRef, NavigationContainer } from '@react-navigation/native';

export const navigationRef = createNavigationContainerRef<RootStackParamList>();

Pushix.Notifications.addEventListener('click', ({ notification, result }) => {
  const open = () => {
    if (result.url === 'myshop://orders' || notification.additionalData?.screen === 'orders') {
      navigationRef.navigate('Orders');
    }
  };
  navigationRef.isReady() ? open() : setTimeout(open, 300);
});

// <NavigationContainer ref={navigationRef}>…</NavigationContainer>

If you already have a React Navigation linking config, Linking.openURL(result.url) hands the link to it.

While the app is open#

Notifications are shown even when the app is in the foreground, on Android and iPhone (drawn by Notifee). To hide or delay one:

Pushix.Notifications.addEventListener('foregroundWillDisplay', (event) => {
  if (currentScreen === 'orders') {
    event.preventDefault();               // don't show it
    // event.getNotification().display(); // or show it later
  }
});

Call preventDefault() synchronously inside the listener. On iOS, React Native Firebase's own foreground banners stay off (the default), so a message isn't shown twice; pushes from other senders in your app aren't shown while it is open either, unless you draw them.

In-app messages#

Create them in the dashboard under In-app messages: a pop-up, card, top or bottom banner, or full screen, with your colours, picture and up to three buttons. The SDK downloads the ones meant for this device each time a session starts and shows them by their trigger:

Mount the host once, as the last child of your root component, so it draws above your screens:

import { useSafeAreaInsets } from 'react-native-safe-area-context';

function Root() {
  const insets = useSafeAreaInsets(); // optional; estimated from the status bar without it
  return (
    <>
      <NavigationContainer>…</NavigationContainer>
      <PushixInAppMessageHost insets={insets} />
    </>
  );
}

Pop-ups and full-screen messages open in a React Native Modal; cards and banners are drawn over your app without blocking it. The host keeps clear of the notch, status bar and home indicator; pass insets (most apps already have react-native-safe-area-context) for exact spacing.

Pushix.InAppMessages.addTrigger('cart_value', 1200);
Pushix.InAppMessages.setPaused(true);  // e.g. during a game round
Pushix.InAppMessages.setPaused(false);

Pushix.InAppMessages.addEventListener('click', (event) => {
  // event.result.actionId is the button id; event.result.url its link
  if (event.result.action === 'deep_link' && event.result.url === 'myshop://account') {
    navigationRef.navigate('Kyc');
  }
});

Frequency rules (show at most N times, wait between showings) are kept on the device. "Open a link" buttons open the browser; "Deep link" buttons are handed to your click listener (or opened with Linking if you have none). Seen, clicked and closed counts appear in the dashboard and in Analytics. Messages wait while the app is in the background or paused, and show when it comes back.

iOS can't show a pop-up on top of another Modal: if your app has one open, pause in-app messages until it closes.

Tags#

Tags are key–value strings used for segments, filters and {{ personalisation }}.

Pushix.User.addTags({ level: 7, plan: 'gold', last_bonus: Math.floor(Date.now() / 1000) });
Pushix.User.removeTag('plan');
const tags = await Pushix.User.getTags();

Your backend can also set tags by user id without the app: PUT /api/v1/apps/{app_id}/users/{external_user_id}.

Changes made while offline are saved on the phone and sent when the server can be reached again.

Data-only messages#

Messages sent with content_available: true and no contents don't show anything. While the app is open you get them here:

Pushix.Notifications.addEventListener('silentData', (n) => {
  if (n.additionalData?.refresh === 'balance') reloadBalance();
});

When the app is in the background they arrive in Firebase's background handler; read them in your own handler (see step 5) with message.data. iOS limits how often background messages wake an app.

Consent#

Pushix.setConsentRequired(true); // before initialize
// later, when the user agrees:
Pushix.setConsentGiven(true);

Until consent is given the device isn't registered and nothing is sent to Pushix.

Expo#

The SDK works in Expo apps built with development builds or EAS Build (not Expo Go). In app.json:

{
  "expo": {
    "android": {
      "package": "com.yourcompany.app",
      "googleServicesFile": "./google-services.json"
    },
    "ios": {
      "bundleIdentifier": "com.yourcompany.app",
      "googleServicesFile": "./GoogleService-Info.plist",
      "entitlements": { "aps-environment": "production" },
      "infoPlist": { "UIBackgroundModes": ["remote-notification"] }
    },
    "plugins": [
      "@react-native-firebase/app",
      ["@react-native-firebase/messaging", { "android": { "notificationIcon": "./assets/notification_icon.png" } }],
      ["expo-build-properties", { "ios": { "useFrameworks": "dynamic" } }],
      ["./plugins/withNotificationIcon", { "icon": "./assets/notification_icon.png" }]
    ]
  }
}

Install expo-build-properties with npx expo install expo-build-properties. Notifee and AsyncStorage need no plugin. Put firebase.json (step 2) in the project root as well.

Notification icon. The Firebase plugin points Android at @drawable/notification_icon but doesn't create it. This small local plugin copies your white-on-transparent PNG into the Android project; save it as plugins/withNotificationIcon.js:

const fs = require('fs');
const path = require('path');
const { withDangerousMod } = require('expo/config-plugins');

module.exports = function withNotificationIcon(config, { icon }) {
  return withDangerousMod(config, [
    'android',
    async (cfg) => {
      const dir = path.join(cfg.modRequest.platformProjectRoot, 'app/src/main/res/drawable');
      fs.mkdirSync(dir, { recursive: true });
      fs.copyFileSync(path.join(cfg.modRequest.projectRoot, icon), path.join(dir, 'notification_icon.png'));
      return cfg;
    },
  ]);
};

and pass defaultSmallIcon: 'notification_icon' to Pushix.initialize.

Entry file. The background handlers must run before the app registers, so set "main": "index.js" in package.json and create index.js. With a classic App.tsx:

// index.js
import notifee from '@notifee/react-native';
import { getMessaging, setBackgroundMessageHandler } from '@react-native-firebase/messaging';
import { registerRootComponent } from 'expo';
import { pushixBackgroundHandler, pushixNotifeeBackgroundHandler } from 'pushix-react-native';
import App from './App';

setBackgroundMessageHandler(getMessaging(), pushixBackgroundHandler);
notifee.onBackgroundEvent(pushixNotifeeBackgroundHandler);

registerRootComponent(App);

With Expo Router, drop the App and registerRootComponent lines and end the file with import 'expo-router/entry'; instead, then put initialize and <PushixInAppMessageHost /> in app/_layout.tsx.

Then npx expo prebuild --clean (or let EAS Build do it). Pictures and buttons on iPhone while the app is in the background need a Notification Service Extension, which in Expo needs a config plugin for app extensions; everything else works without one.

How notifications are drawn#

• Plain messages (title, text, picture) are sent as normal notifications. Android and iOS show them even if the app was swiped away.
• On Android, messages with buttons, a large icon or android_group are sent as data messages and drawn by the SDK through pushixBackgroundHandler. These need the app process to start, which some phone makers (Xiaomi, Oppo, Vivo, Realme) block when battery saving is aggressive. Prefer plain messages for anything important.
• While the app is open, every Pushix notification is drawn by the SDK so foregroundWillDisplay can hide it.

Testing#

1. Run the app on your phone (npx react-native run-android / run-ios, or a development build) and allow notifications. On iPhone use a real device; the simulator only receives pushes on recent Xcode with Apple silicon.
2. In the dashboard, open Subscribers, click your device and tick Test device.
3. New message → Send to test devices.

Troubleshooting#