# Push notifications with Expo

> Set up Releva push in a React Native app that uses Expo and expo-notifications, with the Expo adapter of @releva-ai/sdk-react-native, APNs token registration for iOS and the iOS APNs environment setting in Releva.

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](https://releva.ai/documentation/integrations/react-native/connect-your-react-native-app/); the client, identity, tracking, banners, stories, NPS, App Inbox and backend calls are the same.

> **Note**
>
> The code below follows the SDK’s README at version 0.4.1. The `app.json` setup was tested on Expo SDK 57 (React Native 0.86) with release builds on iOS 27 and Android 16.

## What your users will see

|                                                   | 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](https://releva.ai/documentation/integrations/react-native/push-notifications-with-expo/#known-limits) |

## Before you start

* 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](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/).
* 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](https://releva.ai/documentation/integrations/mobile/add-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.

## Install

```plaintext
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.

## Configure

### 1. `app.json`

```plaintext
{
  "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

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**

```plaintext
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:

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

### 3. App start: permission, token, foreground listener

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

```plaintext
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.

### 4. Taps and navigation with Expo Router

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

```plaintext
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**

```plaintext
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);
}
```

## Verify

Follow [Check that your mobile app is connected](https://releva.ai/documentation/integrations/mobile/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.

## Troubleshooting

**`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`.

## Known limits

* **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.

## Next steps

* [Connect your React Native app](https://releva.ai/documentation/integrations/react-native/connect-your-react-native-app/): Install the SDK, track screens and check that data arrives.
* [React Native SDK reference](https://releva.ai/documentation/integrations/react-native/sdk-reference/): See the push methods, payload and tap action in detail.
* [Add your Firebase credentials for app push](https://releva.ai/documentation/integrations/mobile/add-firebase-credentials-for-app-push/): Upload the credentials Releva sends app push through.
* [Push notifications API overview](https://releva.ai/documentation/reference/push-notifications/overview/): See the endpoints that register your app for push.