Skip to main content
Use the Sendrealm React Native SDK in React Native apps that own their native android and ios projects. If you use Expo prebuild or EAS builds, use React Native Expo SDK.

​
Requirements

  • React 18 or newer.
  • React Native 0.76 or newer.
  • Android device or emulator with Google Play services.
  • Physical iOS device for APNs testing.
  • A Sendrealm app ID from the dashboard.
  • Firebase credentials uploaded for Android delivery.
  • APNs credentials uploaded for iOS delivery.
  • Push Notifications enabled for the iOS App ID and Xcode target.
Expo Go is not supported because mobile push requires native code.

​
Setup Order

  1. Upload Firebase and APNs credentials in Sendrealm.
  2. Install @sendrealm/react-native.
  3. Add Android google-services.json.
  4. Enable iOS Push Notifications capabilities.
  5. Forward iOS AppDelegate notification callbacks.
  6. Rebuild Android and iOS.
  7. Initialize Sendrealm from JavaScript.
  8. Ask for notification permission after explaining the value to the user.
  9. Call login when the user signs in.
  10. Send test pushes on Android and iOS.

​
Install

npm install @sendrealm/react-native
Rebuild the native apps after installing: 
npx react-native run-android
npx react-native run-ios
If your iOS project uses CocoaPods directly: 
cd ios
pod install

​
Android Setup

Android push uses Firebase Cloud Messaging. Before testing Android:
  • Add android/app/google-services.json.
  • Apply the Google Services Gradle plugin if your app does not already use it.
  • Confirm the Firebase Android package name matches your React Native Android applicationId.
  • Upload the Firebase service account JSON in Sendrealm.
  • Test on a device or emulator with Google Play services.
See Mobile Push Credentials for the Firebase walkthrough.

​
iOS Setup

Before testing iOS:
  • Enable Push Notifications for the Apple App ID.
  • Enable Push Notifications on the Xcode app target.
  • Use a Bundle ID that matches the app configured in Sendrealm.
  • Upload the APNs .p8 key, Key ID, Team ID, Bundle ID, and environment in Sendrealm.
  • Test on a physical iOS device.
If your app sends background updates, enable Background Modes with Remote notifications. If your app sends rich image notifications, add a Notification Service Extension target. Autolinking installs the iOS native module, but bare apps still need to forward APNs callbacks from AppDelegate.swift: 
import SendrealmReactNative

func application(
  _ application: UIApplication,
  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
) -> Bool {
  SendrealmModule.configure()
  return true
}

func application(
  _ application: UIApplication,
  didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
  SendrealmModule.didRegisterForRemoteNotifications(withDeviceToken: deviceToken)
}

func application(
  _ application: UIApplication,
  didReceiveRemoteNotification userInfo: [AnyHashable: Any],
  fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
) {
  SendrealmModule.didReceiveRemoteNotification(userInfo)
  completionHandler(.newData)
}
If your app sets UNUserNotificationCenter.current().delegate after Sendrealm is configured, forward notification responses from that delegate so open and action events are tracked: 
func userNotificationCenter(
  _ center: UNUserNotificationCenter,
  didReceive response: UNNotificationResponse,
  withCompletionHandler completionHandler: @escaping () -> Void
) {
  SendrealmModule.didReceiveNotificationResponse(response)
  completionHandler()
}
See Mobile Push Credentials for the APNs walkthrough.

​
Initialize

Initialize once near app startup: 
import { useEffect } from "react";
import Sendrealm from "@sendrealm/react-native";

export default function App() {
  useEffect(() => {
    void Sendrealm.initialize({
      appId: "YOUR_SENDREALM_APP_ID",
      environment: "development",
      autoRequestPermission: false,
      apnsEnvironment: "sandbox",
    });
  }, []);

  return null;
}
Use environment: "development" for test devices you want to target separately. Omit it for production. Use apnsEnvironment: "sandbox" for development-signed iOS builds and production for TestFlight or App Store builds. Most apps should keep autoRequestPermission: false and ask permission after an in-app explanation.

​
Ask For Permission

await Sendrealm.requestPermission();
Check status: 
const status = await Sendrealm.getPermissionStatus();
const allowed = await Sendrealm.hasNotificationPermission();
Android 13 and newer show a runtime notification prompt. iOS shows the alert, badge, and sound authorization prompt. 
await Sendrealm.login("user-123", "user@example.com");
Call logout when the user signs out: 
await Sendrealm.logout();

​
Tags

Use tags for app-observed preferences, state, and behavior: 
await Sendrealm.addTags({
  plan: "pro",
  onboardingComplete: true,
});
Do not use SDK tags for authoritative account, billing, security, compliance, or verified profile data. Send those from your backend.

​
Custom Events

Track app events for segmentation, analytics, or automations: 
await Sendrealm.trackEvent("checkout_started", {
  product_id: "sku_123",
  price: 29,
});
Use stable event names and avoid sending sensitive data unless your team intentionally wants that data stored in Sendrealm.

​
Notification Opens

Listen for notification opens when your app needs to route the user: 
const sub = Sendrealm.addNotificationClickListener((event) => {
  console.log(event.notificationId, event.launchUrl);
});

sub.remove();
Read the notification that opened the app from a cold start: 
const initial = await Sendrealm.getInitialNotification();

​
Android Notification Channels

Create Android notification channels when your app needs explicit sound, vibration, or importance behavior: 
await Sendrealm.createNotificationChannel({
  id: "orders",
  name: "Orders",
  importance: "high",
  soundName: "order_update",
});
Android remembers channel behavior after a channel is created. Use a new channel ID for materially different sound or importance behavior.

​
Diagnostics

Collect support-safe diagnostics during setup: 
const diagnostics = await Sendrealm.getSupportDiagnostics();
console.log(JSON.stringify(diagnostics, null, 2));
Confirm diagnostics show:
  • A device ID.
  • Token presence.
  • Expected permission status.
  • Subscribed state unless the user opted out.
  • SDK version.
  • No unexpected SDK error.

​
Troubleshooting

SymptomWhat to check
Expo Go fails to load the packageUse a development build or bare app because native code is required.
Android token is missingUse a Google Play device or emulator and verify Firebase package name setup.
iOS push does not arriveUse a physical device and verify APNs environment, Bundle ID, Team ID, Key ID, and .p8 key in Sendrealm.
iOS entitlement is missingEnable Push Notifications in Apple Developer and on the Xcode app target.
Notifications are delayedCheck Android power management, FCM priority, iOS APNs priority, Focus settings, and notification permissions.
Some pushes are missingCheck stale tokens, disabled channels, offline devices, and provider diagnostics.
Tags return ContactNotLinkedCall login(userId, email) before tags.
Notification opens app but not the expected screenCheck the notification launch URL and your app’s deep link configuration.