> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendrealm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# React Native Bare SDK

> Install and initialize Sendrealm in a bare React Native app.

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](/sdks/react-native-expo).

## 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

```bash theme={null}
npm install @sendrealm/react-native
```

Rebuild the native apps after installing:

```bash theme={null}
npx react-native run-android
npx react-native run-ios
```

If your iOS project uses CocoaPods directly:

```bash theme={null}
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](/tutorials/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`:

```swift theme={null}
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:

```swift theme={null}
func userNotificationCenter(
  _ center: UNUserNotificationCenter,
  didReceive response: UNNotificationResponse,
  withCompletionHandler completionHandler: @escaping () -> Void
) {
  SendrealmModule.didReceiveNotificationResponse(response)
  completionHandler()
}
```

See [Mobile Push Credentials](/tutorials/mobile-push-credentials) for the APNs walkthrough.

## Initialize

Initialize once near app startup:

```tsx theme={null}
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

```tsx theme={null}
await Sendrealm.requestPermission();
```

Check status:

```tsx theme={null}
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.

## Link A Signed-In User

```tsx theme={null}
await Sendrealm.login("user-123", "user@example.com");
```

Call `logout` when the user signs out:

```tsx theme={null}
await Sendrealm.logout();
```

## Tags

Use tags for app-observed preferences, state, and behavior:

```tsx theme={null}
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:

```tsx theme={null}
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:

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

sub.remove();
```

Read the notification that opened the app from a cold start:

```tsx theme={null}
const initial = await Sendrealm.getInitialNotification();
```

## Android Notification Channels

Create Android notification channels when your app needs explicit sound, vibration, or importance behavior:

```tsx theme={null}
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:

```tsx theme={null}
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

| Symptom                                            | What to check                                                                                                  |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Expo Go fails to load the package                  | Use a development build or bare app because native code is required.                                           |
| Android token is missing                           | Use a Google Play device or emulator and verify Firebase package name setup.                                   |
| iOS push does not arrive                           | Use a physical device and verify APNs environment, Bundle ID, Team ID, Key ID, and `.p8` key in Sendrealm.     |
| iOS entitlement is missing                         | Enable Push Notifications in Apple Developer and on the Xcode app target.                                      |
| Notifications are delayed                          | Check Android power management, FCM priority, iOS APNs priority, Focus settings, and notification permissions. |
| Some pushes are missing                            | Check stale tokens, disabled channels, offline devices, and provider diagnostics.                              |
| Tags return `ContactNotLinked`                     | Call `login(userId, email)` before tags.                                                                       |
| Notification opens app but not the expected screen | Check the notification launch URL and your app's deep link configuration.                                      |

## Related Pages

* [React Native Expo SDK](/sdks/react-native-expo)
* [Mobile Push Credentials](/tutorials/mobile-push-credentials)
* [Send Push Notification API](/api-reference/endpoint/send-push-notification)