React Native Bare SDK

​

Mental Model

• The JavaScript layer calls Sendrealm.initialize, requestPermission, login, trackEvent, and listener APIs.
• The native layer receives FCM or APNs tokens, handles notification callbacks, displays notifications, and forwards events back to JavaScript.

​

Setup Order

1. Upload Firebase and APNs credentials in Sendrealm.
2. Install @sendrealm/react-native.
3. Add Android google-services.json and enable iOS Push Notifications capabilities.
4. Rebuild Android and iOS native apps.
5. Add the iOS app delegate hooks.
6. Initialize Sendrealm from JavaScript.
7. Request notification permission after your app explains the value.
8. Call login when the user signs in.
9. Send test pushes on Android and iOS.

​

Requirements

• React 18 or newer
• React Native 0.72 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 on the iOS Apple Developer App ID and Xcode target

​

Install

npm install @sendrealm/react-native

npx react-native run-android
npx react-native run-ios

cd ios
pod install

​

Android Setup

• The device or emulator must have Google Play services.
• The Firebase Android app package name must match your React Native Android applicationId.
• google-services.json must be added to the native Android app.
• The Firebase service account JSON must be uploaded in Sendrealm.
• The app must be rebuilt after installing the SDK.

​

Generate google-services.json

1. Open the Firebase console.
2. Select the Firebase project for your Android app.
3. If you only have a Google Cloud project, add Firebase to that existing Google Cloud project from the Firebase console first.
4. From the Firebase project overview, click the Android icon or Add app.
5. Enter the exact package name from android/app/build.gradle, usually defaultConfig.applicationId.
6. Click Register app.
7. Click Download google-services.json.
8. Move the file to:

android/app/google-services.json

​

Apply The Google Services Gradle Plugin

plugins {
    id("com.google.gms.google-services") version "4.5.0" apply false
}

plugins {
    id("com.android.application")
    id("com.google.gms.google-services")
}

​

Do Not Confuse The Two Firebase JSON Files

• android/app/google-services.json in the app so Firebase client configuration is available.
• Firebase service account private key JSON in Sendrealm so Sendrealm can send through FCM.

​

iOS AppDelegate Setup

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)
}

​

iOS Capabilities In Xcode

1. Open ios/<YourApp>.xcworkspace.
2. Select the iOS app project in the left navigator.
3. Select the main app target.
4. Open Signing & Capabilities.
5. Click the add capability button.
6. Add Push Notifications.
7. Confirm the Team and Bundle Identifier match the app you configured in Apple Developer and Sendrealm.

​

iOS APNs Key For Sendrealm

• The Apple Developer user must be an Account Holder or Admin.
• The key must have Apple Push Notification service selected.
• If Apple asks for scope, use Team Scoped for the simplest setup or Topic Specific for a stricter key.
• If you choose Topic Specific, include the exact Bundle ID used by the React Native iOS target.
• Download the .p8 file immediately because Apple only allows the private key to be downloaded once.

​

Initialize

import { useEffect } from "react";
import Sendrealm from "@sendrealm/react-native";

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

  return null;
}

​

Initialization Options

• appId: required Sendrealm app ID from the dashboard.
• externalUserId: optional user ID to link during initialization.
• userEmail: optional user email to link during initialization.
• autoRequestPermission: whether the SDK should ask for notification permission during initialization.
• apnsEnvironment: iOS APNs environment, usually sandbox for development and production for TestFlight or App Store.
• suppressForegroundNotifications: lets JavaScript handle foreground display instead of native display.
• foregroundPresentation: controls foreground display behavior.

​

Notification Permission

await Sendrealm.requestPermission();

const status = await Sendrealm.getPermissionStatus();
const allowed = await Sendrealm.hasNotificationPermission();

​

Identity

await Sendrealm.login("user-123", "user@example.com");

await Sendrealm.logout();

​

Tags

await Sendrealm.addTags({
  plan: "pro",
  onboardingComplete: true,
});

• plan: "pro"
• preferredLanguage: "en"
• onboardingComplete: true
• lastViewedCategory: "orders"

​

Custom Events

await Sendrealm.trackEvent("checkout_started", {
  product_id: "sku_123",
  price: 29,
});

​

Notification Listeners

const sub = Sendrealm.addNotificationClickListener((event) => {
  console.log(event.notificationId, event.launchUrl);
});

sub.remove();

const sub = Sendrealm.addForegroundNotificationListener((event) => {
  console.log(event.payload.notification?.title);
});

const initial = await Sendrealm.getInitialNotification();

​

Foreground Display

await Sendrealm.setForegroundPresentation({
  display: true,
  banner: true,
  list: true,
  sound: true,
  badge: true,
});

​

Android Notification Channels

await Sendrealm.createNotificationChannel({
  id: "orders",
  name: "Orders",
  importance: "high",
  soundName: "order_update",
});

await Sendrealm.syncNotificationChannels();

​

Delivery Timing And OS Behavior

• Android devices enter Doze or App Standby.
• Android battery optimization or OEM background limits restrict the app.
• Android notification channels are disabled or set to low importance.
• FCM normal-priority messages wait for a maintenance window.
• FCM lowers behavior after high priority is overused for non-visible messages.
• iOS background updates are throttled by APNs or iOS.
• iOS Focus, notification summary, or notification settings suppress display.
• The device is offline or the token is stale.

​

Diagnostics

const diagnostics = await Sendrealm.getSupportDiagnostics();
console.log(JSON.stringify(diagnostics, null, 2));

• Device ID is present.
• Token is present.
• Permission is granted or has the expected status.
• Subscribed state is true unless the user opted out.
• Queue counts are empty or shrinking.
• Last SDK error is empty or explains the failure.

​

Testing Checklist

• Android test device has Google Play services.
• iOS test device is physical.
• Android package name matches Firebase.
• iOS App ID has Push Notifications enabled in Apple Developer.
• iOS app target has Push Notifications enabled in Xcode.
• iOS Bundle ID, Team ID, Key ID, .p8, and APNs environment match the build.
• The app rebuilds successfully after installing the SDK.
• iOS app delegate forwards APNs callbacks.
• initialize resolves successfully.
• requestPermission returns the expected permission state.
• A foreground push is received.
• A background push is received.
• Delayed delivery is acceptable for non-urgent campaigns.
• Time-sensitive notifications use visible platform-appropriate payloads.
• Tapping a push routes to the expected screen.
• getSupportDiagnostics() shows token presence.

​

Troubleshooting

​

Related Pages

• React Native Expo SDK
• Mobile Push Credentials
• Send Push Notification API