Skip to content

Area: Developers

Connect your React Native app

@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 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 lists what changed since 0.4.1. Every method is listed in the React Native SDK reference.

  • 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. 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.
  • 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.
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/:

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.

1. Entry file: notification adapter and background handler

Section titled “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
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.

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:

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

Section titled “3. Push: taps, permission, token, foreground messages, inbox, cold start”

Do these in this order, after setDeviceId and setProfileId:

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:

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.

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.

Start the app, accept the notification permission and open a screen with a page token. Then follow 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.

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.

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.

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

API

  • Push notifications API overview

    How a browser or mobile app registers for Releva push notifications: the web SDK setup, the two registration endpoints, authentication with the access token, errors and limits.