React Native SDK

@reachbell/react-native is the React Native client SDK for both Expo and bare RN apps — the mobile counterpart to the browser SDK. It acquires the device's native push token (FCM on Android, APNs on iOS) and registers it with ReachBell, and supports identify / tag. To send messages to those devices from your backend, use the Node server SDK.

Preview: these mobile SDKs are newly released. Install the peer deps and verify in a test build on a physical device before shipping.

Install

npm install @reachbell/react-native

Then install the token backend your app uses (and AsyncStorage, recommended):

# Expo apps
npx expo install expo-notifications @react-native-async-storage/async-storage
 
# Bare React Native apps
npm install @react-native-firebase/app @react-native-firebase/messaging @react-native-async-storage/async-storage
cd ios && pod install   # iOS

The SDK supports two token backends and auto-detects which one your app has installed at runtime — Expo via expo-notifications, or bare React Native via @react-native-firebase/messaging. Install one of them (whichever matches your app); both are optional peer dependencies. The acquired token is persisted with @react-native-async-storage/async-storage when available, so identify() / tag() work after registration and across app restarts; if it isn't installed, an in-memory mirror covers the current session.

Setup

Native push credentials are required on both platforms — the SDK can only register a token your app is configured to receive.

Expo

Install the deps above. expo-notifications requires a development build or a production build — push tokens are not available in Expo Go for remote (FCM/APNs) push.
Configure native push credentials with EAS:
- Android (FCM): add your FCM server credentials in the Expo dashboard (or eas credentials). Place google-services.json and reference it via expo.android.googleServicesFile in app.json.
- iOS (APNs): run eas credentials to create/upload an APNs key, and enable the Push Notifications capability (EAS does this automatically when building).

(Recommended) set a notification handler near app start so foreground notifications behave:

import * as Notifications from 'expo-notifications';
 
Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowAlert: true,
    shouldPlaySound: true,
    shouldSetBadge: false,
  }),
});

The SDK uses Expo's getDevicePushTokenAsync() (the raw FCM/APNs token), not getExpoPushTokenAsync(), because ReachBell delivers to FCM/APNs directly.

Bare React Native

Install @react-native-firebase/app, @react-native-firebase/messaging, and AsyncStorage (see above), then cd ios && pod install.
Android (FCM): drop google-services.json into android/app/ and apply the Google Services Gradle plugin (per the RNFirebase Android setup). Android 13+ requires the POST_NOTIFICATIONS runtime permission — register() handles the prompt.
iOS (APNs): add GoogleService-Info.plist to the Xcode project, enable the Push Notifications capability and Background Modes → Remote notifications, and upload your APNs key to the Firebase console (per the RNFirebase iOS setup). Firebase exchanges the APNs token for an FCM token, which is what gets registered.

On iOS, the SDK registers the FCM token returned by @react-native-firebase/messaging (Firebase manages the APNs↔FCM exchange under the hood), so tokenType is reported as fcm when this backend is used and apns is reserved for native APNs token flows.

Initialize

Call init once before everything else, with your project's public API key:

import * as ReachBell from '@reachbell/react-native';
 
ReachBell.init({ apiKey: 'rb_live_…' });

init also accepts optional apiUrl, timeoutMs, and debug options. All requests send x-api-key: <your project apiKey> and default to https://api.reachbell.com.

Register for push

register() asks the OS for notification permission, acquires the device push token, and registers it with ReachBell. Call it on a physical device once the user is ready to opt in:

const r = await ReachBell.register();
if (r.success) {
  console.log('registered token:', r.token);
} else {
  console.warn('register failed:', r.reason);
}

You can bind the user id at registration time, which is equivalent to register() followed by identify('user_42'):

await ReachBell.register('user_42');

The current persisted device token is available any time via getToken(), which returns null if the device hasn't registered yet.

Identify

After the user logs in, link the device to your own user id:

await ReachBell.identify('user_42');

Tag

Attach segmentation tags to the device:

await ReachBell.tag(['pro', 'beta']);

Results

Every method returns a plain result object you can branch on — there are no thrown errors to catch.

register() returns { success, token?, reason? }. On success, token holds the registered device token; on failure, reason is one of:

sdk_not_initialized · unsupported_platform · no_push_module ·
permission_denied · no_token · subscribe_failed_<status> ·
timed_out · network_error

no_push_module means neither expo-notifications nor @react-native-firebase/messaging is installed — register() resolves with { success: false, reason: 'no_push_module' }.

identify() and tag() return { ok, reason? }. On failure, reason is one of:

sdk_not_initialized · no_subscription · server_<status> ·
timed_out · network_error

no_subscription means there's no registered device yet — call register() first.

This SDK's job is registration + identity (token → ReachBell). Rendering and handling received notifications stays with your notification library: on Expo use Notifications.addNotificationReceivedListener / addNotificationResponseReceivedListener; on bare RN use messaging().onMessage (foreground) and messaging().setBackgroundMessageHandler (background/quit). To send to these devices from your backend, see the Node server SDK.

Setup (start here)

Flutter