# Connect your React Native app

> Install @releva-ai/sdk-react-native with Firebase messaging and notifee, initialise the client with your Access Token, register the push token, track screens with page tokens and check in Releva that data arrives.

`@releva-ai/sdk-react-native` connects a React Native app to Releva: screen and product tracking, product blocks, banners, stories, NPS surveys, app push and the App Inbox. This page covers the recommended stack, **Firebase messaging + notifee**. If your app uses Expo with `expo-notifications`, follow [Push notifications with Expo](https://releva.ai/documentation/integrations/react-native/push-notifications-with-expo/) for the install and push sections and this page for everything else.

The code is cut down from Releva’s example app and the SDK’s README at version 0.4.1. The latest release is 0.4.3 (16 October 2026); the [integrations changelog](https://releva.ai/documentation/changelog/integrations/) lists what changed since 0.4.1. Every method is listed in the [React Native SDK reference](https://releva.ai/documentation/integrations/react-native/sdk-reference/).

## Before you start

* React 18 or later, React Native 0.72 or later, Node 20 or later for the toolchain.
* Your shop’s **Access Token** from **Settings › Shop & Integration › General**: [Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/). Never put the **Secret Key** in the app.
* One page token per screen you want to track or personalise, from the **Token:** bar on **Personalization › Product Blocks**: [Pages and tokens](https://releva.ai/documentation/learn/product-blocks/how-product-blocks-work/#pages-and-tokens).
* For push: a Firebase project with `google-services.json` (Android) and `GoogleService-Info.plist` (iOS), and its service account uploaded in Releva: [Add your Firebase credentials for app push](https://releva.ai/documentation/integrations/mobile/add-firebase-credentials-for-app-push/).

## Install

```plaintext
npm install @releva-ai/sdk-react-native
npm install @react-native-async-storage/async-storage @react-native-community/netinfo
```

`async-storage` (1.21 or later) and `netinfo` (11 or later) are required peers. For push on this stack add the Firebase and notifee peers, then run `pod install` in `ios/`:

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

The SDK accepts `@react-native-firebase/messaging` 20 or later and `@notifee/react-native` 7 or later. The Firebase calls below use the modular API (`getMessaging()`, `getToken()`); the namespaced `messaging().getToken()` form works on versions that still ship it. No crypto polyfill is needed by the SDK itself.

Set up Firebase in the native projects as Firebase documents it: `google-services.json` in `android/app/` with the `com.google.gms.google-services` Gradle plugin, and `GoogleService-Info.plist` in the Xcode project.

## Configure

### 1. Entry file: notification adapter and background handler

The SDK core depends on no notification library. Releva sends data-only pushes on Android, and an adapter draws them. Register it **at module top level in `index.js`**, before any message handler: on a cold start Android runs this file only to deliver the message, and an adapter registered later is too late.

**index.js**

```plaintext
import { AppRegistry } from 'react-native';
import { getMessaging, setBackgroundMessageHandler } from '@react-native-firebase/messaging';
import { EngagementTrackingService } from '@releva-ai/sdk-react-native';
import { notifeeNotificationAdapter } from '@releva-ai/sdk-react-native/notifee';
import App from './src/App';
import { name as appName } from './app.json';


EngagementTrackingService.setNotificationAdapter(notifeeNotificationAdapter);


setBackgroundMessageHandler(getMessaging(), async (remoteMessage) => {
  await EngagementTrackingService.handleBackgroundMessage(remoteMessage.data ?? {});
});


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

Without the adapter the SDK logs `[Releva] No notification adapter registered` and draws nothing, which looks like a push that never arrived. Tracking, banners, stories, NPS and the inbox need no adapter.

### 2. Client, device id, profile id

```plaintext
import { RelevaClient, RelevaConfigPresets } from '@releva-ai/sdk-react-native';


// realm: '' unless Releva gives you one. accessToken: Settings › Shop & Integration › General.
export const client = new RelevaClient('', '<yourAccessToken>', RelevaConfigPresets.full());


// A stable id for this install, for example a UUID stored on first launch.
await client.setDeviceId(deviceId);


// After login. The anonymous profile the shopper browsed under is merged into this one.
await client.setProfileId('DEMO-1001');
```

Every call throws `Please provide deviceId before using the client!` until `setDeviceId` has run. On **logout** set a fresh anonymous id with the merge skipped, then register the push token again so it moves to the new profile:

```plaintext
await client.setProfileId(newAnonymousId, true);   // true = skipMerge
const token = await getToken(getMessaging());
if (token) await client.registerPushToken(Platform.OS === 'ios' ? 'ios' : 'android', token);
```

Call `client.dispose()` when your root component unmounts; it stops the inbox’s AppState listener and the engagement batch timer.

### 3. Push: taps, permission, token, foreground messages, inbox, cold start

Do these in this order, after `setDeviceId` and `setProfileId`:

```plaintext
import { Linking, Platform } from 'react-native';
import {
  AuthorizationStatus, getMessaging, getToken, onMessage, onTokenRefresh, requestPermission,
} from '@react-native-firebase/messaging';
import { EngagementTrackingService, NavigationService, type RelevaNotificationAction } from '@releva-ai/sdk-react-native';


// a) Taps: the SDK records the click, then calls you. Navigating is your app's job.
await client.enablePushEngagementTracking({
  onNotificationTapped: (action: RelevaNotificationAction) => {
    const nav = NavigationService.navigationRef?.current;
    if (action.target === 'inbox') {
      nav?.navigate('Inbox', action.parameters);            // parameters.inboxMessageId
    } else if (action.target === 'screen' && action.screen) {
      nav?.navigate(action.screen, action.parameters);      // Screen + KV Pairs from the push form
    } else if (action.target === 'url' && action.url) {
      Linking.openURL(action.url).catch(() => {});
    }
  },
});


// b) Permission and token. Re-register on refresh: this SDK does not do it for you.
const messaging = getMessaging();
const status = await requestPermission(messaging);
if (status === AuthorizationStatus.AUTHORIZED || status === AuthorizationStatus.PROVISIONAL) {
  const deviceType = Platform.OS === 'ios' ? 'ios' : 'android';
  const token = await getToken(messaging);
  if (token) await client.registerPushToken(deviceType, token);
  onTokenRefresh(messaging, (newToken) => client.registerPushToken(deviceType, newToken));
}


// c) Foreground pushes, including silent inbox-sync signals. Register after (b).
onMessage(messaging, async (remoteMessage) => {
  await EngagementTrackingService.handleForegroundMessage(remoteMessage.data ?? {});
});


// d) App Inbox, after the profile id is set.
await client.initializeInbox();


// e) The tap that launched a closed app. After (a), once navigation is ready.
await client.checkInitialNotification();
```

`action.screen` is the free-form **Screen** name and `action.parameters` the **KV Pairs** set under **Mobile Targeting** on the push notification’s **Behavior** tab; `action.target` is `screen`, `url`, `inbox` or `null` for **Main Screen**.

If you use React Navigation, hand the SDK your navigation ref once so the callback can reach it:

```plaintext
import { NavigationContainer, createNavigationContainerRef } from '@react-navigation/native';
import { NavigationService } from '@releva-ai/sdk-react-native';


const navigationRef = createNavigationContainerRef();
NavigationService.setNavigationRef(navigationRef);


<NavigationContainer ref={navigationRef}>{/* screens */}</NavigationContainer>
```

**On iOS** Releva sends every visible push with an alert, so iOS draws it itself while the app is in the background or closed; the notifee adapter draws only foreground pushes, with image and button. Taps on iOS-drawn pushes are still tracked and routed through `checkInitialNotification()` and `onNotificationTapped`. Do not also forward Releva taps from your own `onNotificationOpenedApp` handler, or each tap is counted twice. Images must be JPEG or PNG for iOS.

### 4. Track screens with page tokens

```plaintext
import { BannerManagerService, StoryManagerService, createActiveCart, createPaidCart, emptyCustomFields } from '@releva-ai/sdk-react-native';


export const bannerManager = new BannerManagerService();
export const storyManager = new StoryManagerService();


// Each screen view. screenToken is the page token from Personalization › Product Blocks.
const response = await client.trackScreenView({
  screenToken: '<homePageToken>',
  productIds: ['DEMO-1001', 'DEMO-1002'],
});
if (response.banners.length > 0) bannerManager.initialize(response.banners);
if (response.stories.length > 0) storyManager.initialize(response.stories);


await client.trackProductView({ screenToken: '<productPageToken>', productId: 'DEMO-1001', categories: ['Shoes'] });


// Cart and wishlist: the first call only stores; later changes send a push.
await client.setCart(createActiveCart([{ id: 'DEMO-1001', price: 29.99, quantity: 1, custom: emptyCustomFields() }]));
await client.setWishlist([{ id: 'DEMO-1002', custom: emptyCustomFields() }]);


// Order placed in the app: sends the paid cart, then clears the stored cart.
await client.trackCheckoutSuccess({
  orderedCart: createPaidCart([{ id: 'DEMO-1001', price: 29.99, quantity: 1, custom: emptyCustomFields() }], 'DEMO-ORDER-1001'),
});
```

A screen sent without a page token, or with a made-up name such as `'home_screen'`, is accepted with `200` but records no page view and returns no banners or stories. Nothing in the response says why.

Banners and stories render through `BannerDisplayWidget`, `StoryDisplayWidget` and `NpsOverlayWidget` wrapped around your screens; the managers above feed them. The `scrollPercentage`, `cartChanged` and `wishlistChanged` triggers need a signal from your app (`setScrollOffset`, `notifyCartChanged`, `notifyWishlistChanged` on both managers). Leave-intent is web-only and never fires on mobile. See the [SDK reference](https://releva.ai/documentation/integrations/react-native/sdk-reference/#on-screen-content).

## Verify

Start the app, accept the notification permission and open a screen with a page token. Then follow [Check that your mobile app is connected](https://releva.ai/documentation/integrations/mobile/check-that-your-mobile-app-is-connected/): **Push Notification Subscribe** on **Data Platform › Events**, **Viewed Page** for the screen, and **App push: Subscribed** on the profile. The SDK logs every request with its status, for example `[Releva] POST /api/v0/appPush/tokens -> 202`.

## Troubleshooting

**Nothing shows for a push on Android while the app is in the background or closed.** The adapter is not registered at module top level, or `setBackgroundMessageHandler` is missing from `index.js`. Both must run before the app component.

**Pushes do not show while the app is open.** `onMessage` is not wired to `handleForegroundMessage`, or it was registered before `requestPermission`/`getToken` on a fresh install, which can invalidate an earlier listener. Register it after the token code.

**A tap does nothing when the app was closed.** `checkInitialNotification()` was not called, or was called before `enablePushEngagementTracking()` or before the navigation container was ready.

**Each tap is counted twice on iOS.** Your own `onNotificationOpenedApp` handler also forwards Releva taps. Filter them out with `isRelevaMessage(remoteMessage.data)` or leave them to the SDK.

**`400 pushToken looks like a raw APNs device token…`** You sent an APNs token with `deviceType: 'ios'`. On this stack register the FCM token from `getToken`; APNs tokens are for the Expo stack only.

**No banners, stories or product blocks, and no Viewed Page event.** The screen’s `screenToken` is not a page token. Copy it from **Personalization › Product Blocks**.

**Pushes stop after a while.** FCM rotated the token and `onTokenRefresh` is not wired, or the app did not re-register after logout. The SDK never re-registers on its own.

**Requests time out or fail with 5xx.** Tracking, banner and story events, push token registration, NPS and inbox calls are aborted after `requestTimeoutMs` (30 s) and retried up to `maxRetryAttempts` (3) on transport failures and 5xx, never on 4xx.

## What syncs

| Data                                                                        | Endpoint                                                                                       | When the SDK calls it                                                                                                                                                                                                                                                  |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Screen, product, search views; custom events; cart, wishlist; checkout      | `POST /api/v0/push`                                                                            | `trackScreenView`, `trackProductView`, `trackSearchView`, `trackCustomEvent`, `trackCheckoutSuccess`; `setCart`/`setWishlist` on a change after the first call. Sends `deviceId`, `profile.id`, `sessionId`, `mergeProfileIds`, the page token, the cart and wishlist. |
| App push token                                                              | `POST /api/v0/appPush/tokens`                                                                  | Only when you call `registerPushToken(deviceType, token, options?)`. Writes a **Push Notification Subscribe** event each time.                                                                                                                                         |
| Push tap                                                                    | `GET <callbackUrl>` from the push data                                                         | On a tap, https only, queued offline (up to 100 for 24 hours).                                                                                                                                                                                                         |
| Banner impressions and actions, story actions                               | `POST /api/v0/impressions`, `POST /api/v0/push/events`                                         | When banners and stories are shown and used.                                                                                                                                                                                                                           |
| NPS answer                                                                  | `POST /api/v0/nps/{token}/submissions`                                                         | `submitNpsResponse`.                                                                                                                                                                                                                                                   |
| App Inbox                                                                   | `GET /api/v0/inbox/messages`, `GET /api/v0/inbox/unread-count`, read, read-all, delete, action | `initializeInbox()`, a silent sync push, resume with a cache older than 5 minutes, and the `InboxService` methods.                                                                                                                                                     |
| Products, orders paid outside the app, refunds, profile attributes, consent | not sent by the SDK                                                                            | Your backend: see [What your backend still sends](https://releva.ai/documentation/integrations/mobile/mobile-sdks-overview/#what-your-backend-still-sends).                                                                                                                             |

The SDK sends no e-mail, phone number, name or consent.

## Next steps

* [React Native SDK reference](https://releva.ai/documentation/integrations/react-native/sdk-reference/): Look up every client, tracking, push, inbox and on-screen method and the errors to expect.
* [Push notifications with Expo](https://releva.ai/documentation/integrations/react-native/push-notifications-with-expo/): Set up Releva push in an app that uses Expo and expo-notifications.
* [Add your Firebase credentials for app push](https://releva.ai/documentation/integrations/mobile/add-firebase-credentials-for-app-push/): Upload the Firebase service account Releva sends Android and iOS push through.
* [Check that your mobile app is connected](https://releva.ai/documentation/integrations/mobile/check-that-your-mobile-app-is-connected/): Confirm that push token registrations arrive and the profile shows App push Subscribed.