Skip to content

Area: Developers

Push notifications with Expo

Apps that already run an expo-notifications push stack keep it and use the SDK’s Expo adapter instead of Firebase messaging and notifee. This page replaces only the install and push sections of Connect your React Native app; the client, identity, tracking, banners, stories, NPS, App Inbox and backend calls are the same.

Android iOS
Push while the app is open Title, body, action button Drawn by iOS as your notification handler allows
Push while the app is in the background or closed Title, body, action button Drawn by iOS
Action button Yes Only with a Notification Service Extension in your app
Image No: expo-notifications cannot draw a big picture on Android Only with a Notification Service Extension in your app
Tap tracking and navigation Yes, in every app state Android only on the released SDK; see Known limits
  • A development build of your app (npx expo run:android / run:ios or EAS), a TestFlight build or a store build. Expo Go cannot load the config plugins or run the background task.
  • Your shop’s Access Token: Find your Access Token and Secret Key.
  • A Firebase project with google-services.json for the Android app’s package name, and its service account uploaded in Releva with App Type Unified: Add your Firebase credentials for app push.
  • For iOS: iOS APNs environment on the same tab set to Sandbox for development builds or Production for TestFlight and App Store builds. On this stack the app registers its APNs token and Releva exchanges it for an FCM token through your iOS-capable Firebase credential; there is no separate “APNs import” switch to ask for.
npm install @releva-ai/sdk-react-native
npx expo install @react-native-async-storage/async-storage @react-native-community/netinfo \
expo-notifications expo-task-manager expo-application expo-build-properties

Do not add @react-native-firebase/messaging to the same app: it and expo-notifications each register an Android Firebase messaging service, and Android hands each push to only one of them. @notifee/react-native is not needed. The SDK accepts expo-notifications 0.27 or later.

{
"expo": {
"ios": { "bundleIdentifier": "com.example.shop" },
"android": {
"package": "com.example.shop",
"googleServicesFile": "./google-services.json"
},
"plugins": [
["expo-notifications", { "enableBackgroundRemoteNotifications": true }],
"expo-task-manager",
["expo-build-properties", { "ios": { "enableSceneSupport": true } }]
]
}
}

What the entries do: googleServicesFile is the Android route into Firebase Cloud Messaging and must be the file of the Firebase project whose service account is uploaded in Releva, for this app’s package name (ask your account manager which project that is); enableBackgroundRemoteNotifications lets iOS wake the app for a background push; enableSceneSupport is required for iOS builds made with Xcode 27 (Expo 57.0.23 and expo-build-properties 57.0.22 or later; Expo SDK 58’s template already has it). iOS needs no GoogleService-Info.plist on this stack. Run npx expo prebuild --clean after changing plugins.

2. Entry file: adapter and background task

Section titled “2. Entry file: adapter and background task”

Both at module top level, before the app renders: when a push arrives with the app closed, Android starts your JavaScript only to run this task. Point "main" in package.json at this file.

index.ts
import * as Notifications from 'expo-notifications';
import * as TaskManager from 'expo-task-manager';
import { EngagementTrackingService } from '@releva-ai/sdk-react-native';
import { expoNotificationsAdapter, extractRelevaPayload } from '@releva-ai/sdk-react-native/expo';
import 'expo-router/entry'; // only with Expo Router: a custom entry file must load the router itself
EngagementTrackingService.setNotificationAdapter(expoNotificationsAdapter);
const RELEVA_BACKGROUND_TASK = 'RELEVA_BACKGROUND_NOTIFICATION_TASK';
TaskManager.defineTask(RELEVA_BACKGROUND_TASK, async ({ data }) => {
const payload = extractRelevaPayload(data);
if (payload) await EngagementTrackingService.handleBackgroundMessage(payload);
});
Notifications.registerTaskAsync(RELEVA_BACKGROUND_TASK).catch((e) =>
console.warn('[Releva] Failed to register background notification task:', e),
);

The adapter creates the Android channel releva_notifications and never calls setNotificationHandler: your own handler stays as it is. A push that arrives while the app is open is shown only if that handler returns shouldShowBanner: true, on both platforms. If you have no handler yet, add one; keep your existing handler if you already have one:

Notifications.setNotificationHandler({
handleNotification: async () => ({
shouldShowBanner: true,
shouldShowList: true,
shouldPlaySound: true,
shouldSetBadge: false,
}),
});

3. App start: permission, token, foreground listener

Section titled “3. App start: permission, token, foreground listener”

Where you initialise the client, in place of the Firebase token code of the main page:

import * as Notifications from 'expo-notifications';
import * as Application from 'expo-application';
import { EngagementTrackingService, isRelevaMessage } from '@releva-ai/sdk-react-native';
import { getDevicePushToken, isRelevaLocalNotification } from '@releva-ai/sdk-react-native/expo';
await client.setDeviceId('<deviceId>');
await client.setProfileId('<profileId>');
await client.enablePushEngagementTracking({ onNotificationTapped });
// Without the permission (iOS, and Android 13 and later) pushes are dropped silently.
await Notifications.requestPermissionsAsync();
// Android: an FCM token. iOS: an APNs token that Releva exchanges for an FCM token.
const devicePushToken = await getDevicePushToken();
if (devicePushToken?.tokenType === 'fcm') {
await client.registerPushToken('android', devicePushToken.token);
} else if (devicePushToken?.tokenType === 'apns') {
await client.registerPushToken('ios', devicePushToken.token, {
tokenType: 'apns',
bundleId: Application.applicationId!,
});
}
// Pushes that arrive while the app is open, including silent inbox-sync pushes.
// The listener also fires for the local notification the SDK itself schedules;
// skip that one, or every push re-displays itself forever.
Notifications.addNotificationReceivedListener((notification) => {
const data = (notification.request.content.data ?? {}) as Record<string, any>;
if (isRelevaMessage(data) && !isRelevaLocalNotification(data)) {
EngagementTrackingService.handleForegroundMessage(data);
}
});

On logout, set the new profile id and register the token from getDevicePushToken() again the same way. Call client.checkInitialNotification() once, after enablePushEngagementTracking() and after your root layout has mounted (for example from a useEffect in app/_layout.tsx with Expo Router), so the tap that launched a closed app is routed. A later normal launch does not route or record that tap again.

The SDK records the click and calls your onNotificationTapped with the push’s target; navigating is your app’s job:

import { Linking } from 'react-native';
import { router } from 'expo-router';
import type { RelevaNotificationAction } from '@releva-ai/sdk-react-native';
function onNotificationTapped(action: RelevaNotificationAction) {
if (action.target === 'inbox') {
router.push('/inbox');
} else if (action.target === 'screen' && action.screen === 'product') {
// action.screen is the Screen name set under Mobile Targeting in the Releva push form
router.push({ pathname: '/product/[id]', params: { id: String(action.parameters.productId) } });
} else if (action.target === 'url' && action.url) {
Linking.openURL(action.url);
}
}

Expo Router reads the host of a link in your own scheme (myapp://shop.example/product/3) as the first path segment and shows “Unmatched Route”. Map such links in app/+native-intent.tsx with redirectSystemPath:

app/+native-intent.tsx
export function redirectSystemPath({ path }: { path: string; initial: boolean }) {
const host = 'shop.example';
const at = path.indexOf(`${host}/`);
return at === -1 ? path : path.slice(at + host.length);
}

Follow Check that your mobile app is connected. For iOS, a successful registration means the APNs exchange worked: the Push Notification Subscribe event is tagged device_ios and the profile shows an IOS badge.

400 APNs token could not be imported into FCM. Status: INTERNAL. (or another status). The build’s APNs environment does not match iOS APNs environment on Settings › Messaging › Push Notifications: development builds need Sandbox, TestFlight and App Store builds Production. Also check that bundleId is the app’s real bundle identifier.

400 No iOS Firebase account is configured for this domain. No Unified credential and no iOS Firebase Credentials are saved for the shop.

400 pushToken looks like a raw APNs device token… The iOS token was registered without tokenType: 'apns' and bundleId.

The token listener loops. If you re-register on Notifications.addPushTokenListener, register the token it hands you, and only when it differs from the last one. Do not call getDevicePushToken() inside it.

Pushes do not show while the app is open. Your notification handler must return shouldShowBanner: true.

Pushes do not show while the app is closed. Check the plugins in app.json and the entry file, and test on a real device with a release build. On Android, close the app by swiping it away, not with Force stop: after a force stop Android blocks all pushes until the app is opened again.

The iOS app closes at launch on iOS 27 (“UIScene life cycle is required”). The build was made with Xcode 27 without scene support. Add the enableSceneSupport plugin and run npx expo prebuild --clean.

  • iOS taps need SDK 0.5.0 or later. On @releva-ai/sdk-react-native 0.4.2 and earlier the Expo adapter reads only notification.request.content.data, which is empty for Releva pushes on iOS, so iOS taps are neither tracked nor routed. From 0.5.0 the adapter also reads request.trigger.payload, and relevaDataFromExpoNotification(notification) does the same for your own addNotificationReceivedListener.
  • On Android with the app closed, expo-notifications shows its own copy of the push (title only) before the app’s JavaScript starts; the SDK then shows the full notification and removes the copy, so the phone can alert twice for about a second.
  • No big picture on Android; images and buttons on iOS need a Notification Service Extension.