diff --git a/src/data/nav/pubsub.ts b/src/data/nav/pubsub.ts
index 6936a8f9ab..25d399b491 100644
--- a/src/data/nav/pubsub.ts
+++ b/src/data/nav/pubsub.ts
@@ -268,6 +268,11 @@ export default {
name: 'FCM',
link: '/docs/push/getting-started/fcm',
},
+ {
+ name: 'React Native',
+ link: '/docs/push/getting-started/react-native',
+ languages: ['javascript'],
+ },
],
},
{
diff --git a/src/images/content/screenshots/getting-started/react-native-push-getting-started-guide.png b/src/images/content/screenshots/getting-started/react-native-push-getting-started-guide.png
new file mode 100644
index 0000000000..f065d3d92f
Binary files /dev/null and b/src/images/content/screenshots/getting-started/react-native-push-getting-started-guide.png differ
diff --git a/src/pages/docs/push/getting-started/react-native.mdx b/src/pages/docs/push/getting-started/react-native.mdx
new file mode 100644
index 0000000000..8e958cd91d
--- /dev/null
+++ b/src/pages/docs/push/getting-started/react-native.mdx
@@ -0,0 +1,570 @@
+---
+title: "Getting started: Push Notifications in React Native"
+meta_description: "Get started with Ably Push Notifications in React Native. Learn how to register for push notifications with Firebase Cloud Messaging (FCM), activate push on your client, handle incoming notifications, and send push messages on iOS and Android."
+meta_keywords: "Push Notifications React Native, Ably Push, FCM, Android Push, iOS Push, React Native push notifications, Firebase Cloud Messaging, Ably Push Notifications guide, realtime push React Native, push notification example, Ably tutorial React Native, device registration, push messaging"
+---
+
+This guide will get you started with Ably Push Notifications in a new React Native application.
+
+You'll learn how to set up your application with Firebase Cloud Messaging (FCM), register devices with Ably, send push notifications, subscribe to channel-based push, and handle incoming notifications on both iOS and Android.
+
+## Prerequisites
+
+1. [Sign up](https://ably.com/signup) for an Ably account.
+2. Create a [new app](https://ably.com/accounts/any/apps/new), and create your first API key in the **API Keys** tab of the dashboard.
+3. Your API key needs the `publish`, `subscribe`, and `push-admin` capabilities.
+4. For channel-based push, add a rule for the channel with **Push notifications enabled** checked. In the dashboard left sidebar: **Configuration** → **Rules** → **Add** or **Edit** a rule, then enable the Push notifications option. See [channel rules](/docs/channels#rules) for details.
+5. Install [Node.js](https://nodejs.org/) 18 or higher.
+6. Set up your React Native development environment following the [React Native CLI Quickstart](https://reactnative.dev/docs/set-up-your-environment).
+7. For iOS: Install [Xcode](https://developer.apple.com/xcode/). Push notifications require a physical iOS device (simulators do not support push).
+8. For Android: Install [Android Studio](https://developer.android.com/studio). Use a physical device or an emulator with Google Play Services installed.
+
+### (Optional) Install Ably CLI
+
+Use the [Ably CLI](https://github.com/ably/cli) as an additional client to quickly test Pub/Sub features and push notifications.
+
+1. Install the Ably CLI:
+
+
+```shell
+npm install -g @ably/cli
+```
+
+
+2. Run the following to log in to your Ably account and set the default app and API key:
+
+
+```shell
+ably login
+```
+
+
+### Set up Firebase Cloud Messaging
+
+Firebase Cloud Messaging delivers push notifications for both Android and iOS. To enable FCM:
+
+1. Go to the [Firebase Console](https://console.firebase.google.com/) and create a new project (or use an existing one).
+2. Register your Android app using your package name. Download `google-services.json` and place it in `android/app/`.
+3. Download your Firebase service account JSON file from your Firebase console: **Project configuration** → **Service Accounts** → **Generate new private key**.
+4. In the Ably dashboard left sidebar, navigate to your app's **Push Notifications**.
+5. Scroll to the **Configure push service for devices** section and press **Configure Push**.
+6. Upload your Firebase service account JSON file in **Setting up Firebase Cloud Messaging** section.
+7. In the [Apple Developer portal](https://developer.apple.com), go to **Certificates, Identifiers & Profiles** → **Keys**.
+8. Add a new key and check **Apple Push Notifications service (APNs)**, click **Register**.
+9. Download the `.p8` file — you can only download it once. Note your **Key ID** and **Team ID**.
+10. In the Firebase Console, go to **Project configuration** → **Cloud Messaging** → **Apple App Setup** → **APNS authentication key** to upload your `.p8` file.
+11. Register an iOS app in your Firebase project using your bundle identifier. Download `GoogleService-Info.plist` and add it to your Xcode project's root target.
+
+### Create a React Native project
+
+Create a new React Native project and install the required dependencies:
+
+
+```shell
+npx react-native@latest init PushTutorial
+cd PushTutorial
+npm install ably @react-native-firebase/app @react-native-firebase/messaging @notifee/react-native
+```
+
+
+#### Configure Android project
+
+Apply the Google Services plugin in `android/build.gradle`:
+
+```kotlin
+// android/build.gradle
+buildscript {
+ dependencies {
+ classpath('com.google.gms:google-services:4.4.2')
+ }
+}
+```
+
+Then apply it in `android/app/build.gradle`:
+
+```kotlin
+// android/app/build.gradle
+apply plugin: 'com.google.gms.google-services'
+```
+
+Also declare the `POST_NOTIFICATIONS` permission in `android/app/src/main/AndroidManifest.xml`:
+
+```xml
+
+
+
+ ...
+
+```
+
+
+
+#### Configure iOS project
+
+Open `ios/PushTutorial.xcworkspace` in Xcode and add the `Push Notifications` capability: select your target, go to **Signing & Capabilities**, and click **+ Capability**.
+
+Add `use_modular_headers!` to `ios/Podfile` after `prepare_react_native_project!`:
+
+```ruby
+prepare_react_native_project!
+use_modular_headers!
+```
+
+This is required for Firebase Swift pods (`FirebaseCoreInternal`, `GoogleUtilities`) to be integrated as static libraries. Then install the native pods:
+
+
+```shell
+cd ios && pod install && cd ..
+```
+
+
+Then add `FirebaseApp.configure()` to `AppDelegate.swift` before React Native starts:
+
+```swift
+import Firebase
+
+func application(
+ _ application: UIApplication,
+ didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
+) -> Bool {
+ FirebaseApp.configure()
+ // ... rest of existing setup
+}
+```
+
+Add all further code to `App.tsx`.
+
+## Step 1: Set up Ably
+
+Replace the contents of `App.tsx` with the following to initialize the Ably Realtime client, wrap the app in `AblyProvider` and `ChannelProvider`, and subscribe to a channel for incoming messages using the `useChannel` hook:
+
+
+```javascript
+import React, {useRef, useState} from 'react';
+import {
+ Platform,
+ ScrollView,
+ StyleSheet,
+ Text,
+ TouchableOpacity,
+ View,
+} from 'react-native';
+import {SafeAreaView} from 'react-native-safe-area-context';
+import * as Ably from 'ably';
+import {AblyProvider, ChannelProvider, useChannel, useAbly} from 'ably/react';
+import messaging from '@react-native-firebase/messaging';
+import notifee, {AuthorizationStatus} from '@notifee/react-native';
+
+const CHANNEL_NAME = 'exampleChannel1';
+
+// Use token authentication in production
+const client = new Ably.Realtime({
+ key: '{{API_KEY}}',
+ clientId: 'push-tutorial-client',
+});
+
+function PushScreen() {
+ const [status, setStatus] = useState('Ready to start');
+ const [log, setLog] = useState([]);
+
+ function log(message: string) {
+ setLog(prev => [...prev, message]);
+ }
+
+ function showStatus(message: string) {
+ setStatus(message);
+ console.log(message);
+ }
+
+ useChannel(CHANNEL_NAME, message => {
+ log(`Received: ${message.name} - ${JSON.stringify(message.data)}`);
+ });
+
+ return (
+
+
+ Ably Push Tutorial
+
+ {status}
+
+
+ {log.map((entry, i) => (
+ {entry}
+ ))}
+
+
+
+ );
+}
+
+export default function App() {
+ return (
+
+
+
+
+
+ );
+}
+
+const styles = StyleSheet.create({
+ safeArea: {flex: 1, backgroundColor: '#fff'},
+ container: {flex: 1, padding: 16},
+ title: {fontSize: 22, fontWeight: 'bold', textAlign: 'center', marginBottom: 12},
+ statusBox: {backgroundColor: '#f0f0f0', padding: 12, borderRadius: 6, marginBottom: 12},
+ statusText: {fontSize: 14},
+ logBox: {flex: 1, backgroundColor: '#fff', borderWidth: 1, borderColor: '#ddd', borderRadius: 6, padding: 8},
+ logEntry: {fontFamily: Platform.OS === 'ios' ? 'Courier' : 'monospace', fontSize: 12, marginBottom: 4},
+});
+```
+
+
+Key configuration options:
+
+- `key`: Your Ably API key.
+- `clientId`: A unique identifier for this client.
+
+`AblyProvider` makes the Ably client available to all child components via React context. `ChannelProvider` scopes child components to `exampleChannel1`. `useChannel` subscribes to incoming realtime messages on that channel, replacing the manual `useEffect` + `channel.subscribe` pattern.
+
+## Step 2: Set up push notifications
+
+Push notification activation in React Native requires obtaining an FCM registration token and registering the device with Ably. Add the following inside `PushScreen`:
+
+
+```javascript
+// Inside PushScreen:
+const client = useAbly();
+
+// Generate a unique device ID for this installation
+const [deviceId] = useState(
+ `push-tutorial-${Platform.OS}-${Math.random().toString(36).slice(2, 9)}`,
+);
+const tokenRefreshUnsubscribeRef = useRef<(() => void) | null>(null); // To store the FCM token refresh listener unsubscribe function
+
+async function requestPermission(): Promise {
+ if (Platform.OS === 'android') {
+ // Use notifee for consistent permission behavior across Android versions
+ const settings = await notifee.requestPermission();
+ return settings.authorizationStatus >= AuthorizationStatus.AUTHORIZED;
+ }
+ // On iOS, request permission using Firebase Messaging which will trigger the native iOS permission dialog
+ const authStatus = await messaging().requestPermission();
+ return (
+ authStatus === messaging.AuthorizationStatus.AUTHORIZED ||
+ authStatus === messaging.AuthorizationStatus.PROVISIONAL
+ );
+}
+
+// Save the device registration with Ably using the FCM token
+async function saveDeviceRegistration(token: string) {
+ await client.push.admin.deviceRegistrations.save({
+ id: deviceId,
+ clientId: 'push-tutorial-client',
+ platform: Platform.OS === 'ios' ? 'ios' : 'android',
+ formFactor: 'phone',
+ push: {
+ recipient: {
+ transportType: 'fcm',
+ registrationToken: token,
+ },
+ },
+ });
+}
+
+async function activatePush() {
+ try {
+ showStatus('Activating push notifications...');
+ const granted = await requestPermission();
+ if (!granted) {
+ showStatus('Notification permission denied.');
+ return;
+ }
+
+ await messaging().registerDeviceForRemoteMessages(); // Required to receive push notifications on iOS, no-op on Android
+ const fcmToken = await messaging().getToken();
+ await saveDeviceRegistration(fcmToken);
+
+ tokenRefreshUnsubscribeRef.current?.();
+ tokenRefreshUnsubscribeRef.current = messaging().onTokenRefresh(async newToken => {
+ try {
+ await saveDeviceRegistration(newToken);
+ } catch (error: any) {
+ console.error('Failed to update FCM token:', error.message);
+ }
+ });
+
+ showStatus(`Push activated. Device ID: ${deviceId}`);
+ log(`Push activated. Device ID: ${deviceId}`);
+ } catch (error: any) {
+ showStatus(`Failed to activate push: ${error.message}`);
+ }
+}
+
+async function deactivatePush() {
+ try {
+ showStatus('Deactivating push notifications...');
+ await client.push.admin.deviceRegistrations.remove(deviceId);
+ tokenRefreshUnsubscribeRef.current?.();
+ tokenRefreshUnsubscribeRef.current = null;
+ showStatus('Push notifications deactivated.');
+ } catch (error: any) {
+ showStatus(`Failed to deactivate push: ${error.message}`);
+ }
+}
+```
+
+
+The `transportType` is set to `fcm` on both platforms because `messaging().getToken()` always returns an FCM registration token, even on iOS. Firebase exchanges the APNs device token for an FCM token internally, so Ably communicates with Firebase rather than APNs directly (instead Firebase sends push notifications to iOS devices via APNs).
+
+`activatePush()` does the following:
+
+1. Requests notification permission from the user.
+2. Obtains the FCM registration token from Firebase.
+3. Registers the device with Ably's push notification service using the token.
+
+After successful activation, `deviceId` contains the unique device ID assigned to this installation.
+
+
+
+
+
+
+
+## Step 3: Subscribe and test push notifications
+
+The FCM SDK handles background push notifications automatically and displays them as system notifications. For foreground handling, use `@notifee/react-native` to display notifications while the app is open.
+
+Add the following inside `PushScreen`:
+
+
+```javascript
+useEffect(() => {
+ // Create a default Android notification channel
+ if (Platform.OS === 'android') {
+ notifee.createChannel({id: 'default', name: 'Default Channel'});
+ }
+
+ // Handle foreground push messages
+ const unsubscribe = messaging().onMessage(async remoteMessage => {
+ const title = remoteMessage.notification?.title ?? 'Push Notification';
+ const body = remoteMessage.notification?.body ?? '';
+ log(`Push received: ${title} — ${body}`);
+ await notifee.displayNotification({
+ title,
+ body,
+ android: {channelId: 'default'},
+ });
+ });
+
+ return () => {
+ unsubscribe();
+ };
+}, []);
+```
+
+
+To subscribe your device to a channel so it can receive channel-based push notifications, add the following functions inside `PushScreen`, after the functions from Step 2:
+
+
+```javascript
+async function subscribeToChannel() {
+ try {
+ await client.push.admin.channelSubscriptions.save({
+ deviceId,
+ channel: CHANNEL_NAME,
+ });
+ showStatus(`Subscribed to push on channel: ${CHANNEL_NAME}`);
+ } catch (error: any) {
+ showStatus(`Failed to subscribe: ${error.message}`);
+ }
+}
+
+async function unsubscribeFromChannel() {
+ try {
+ await client.push.admin.channelSubscriptions.remove({
+ deviceId,
+ channel: CHANNEL_NAME,
+ });
+ showStatus(`Unsubscribed from push on channel: ${CHANNEL_NAME}`);
+ } catch (error: any) {
+ showStatus(`Failed to unsubscribe: ${error.message}`);
+ }
+}
+```
+
+
+
+
+Use the Ably CLI to send a test push notification to your client ID:
+
+
+```shell
+ably push publish --client-id push-tutorial-client \
+ --title "Test push" \
+ --body "Hello from CLI!" \
+ --data '{"foo":"bar","baz":"qux"}'
+```
+
+
+Or from code:
+
+
+```javascript
+await client.push.admin.publish(
+ {clientId: 'push-tutorial-client'},
+ {
+ notification: {title: 'Test push', body: 'Hello from code!'},
+ data: {foo: 'bar', baz: 'qux'},
+ },
+);
+```
+
+
+Or send directly to a device ID:
+
+
+```shell
+ably push publish --device-id \
+ --title "Test push" \
+ --body "Hello from device ID!"
+```
+
+
+
+```javascript
+await client.push.admin.publish(
+ {deviceId: ''},
+ {
+ notification: {title: 'Test push', body: 'Hello from code!'},
+ },
+);
+```
+
+
+To send push notifications via a channel, you first need a UI to subscribe to the channel.
+
+## Step 4: Build the UI
+
+Update the `return` statement in `PushScreen` to add buttons that call all the push functions:
+
+
+```javascript
+return (
+
+
+ Ably Push Tutorial
+
+ {status}
+
+
+
+ Activate Push
+
+
+ Deactivate Push
+
+
+ Subscribe to Channel
+
+
+ Unsubscribe from Channel
+
+
+
+ {log.map((entry, i) => (
+ {entry}
+ ))}
+
+ setLog([])}>
+ Clear Log
+
+
+
+);
+```
+
+
+Add the button styles to the `StyleSheet.create` call:
+
+
+```javascript
+buttons: {gap: 8, marginBottom: 12},
+btn: {padding: 14, borderRadius: 6, alignItems: 'center'},
+btnText: {color: '#fff', fontWeight: '600'},
+btnGreen: {backgroundColor: '#28a745'},
+btnRed: {backgroundColor: '#dc3545'},
+btnPurple: {backgroundColor: '#6f42c1'},
+btnOrange: {backgroundColor: '#fd7e14'},
+btnGray: {backgroundColor: '#6c757d', marginTop: 8},
+
+```
+
+
+Build and run your app on a physical device:
+
+
+```shell
+# Android
+npx react-native run-android
+
+# iOS
+npx react-native run-ios --device
+```
+
+
+You can also open each platform project in their respective IDEs and run from there.
+
+Tap **Activate Push** and wait until the status message displays your device ID. Try sending a test push notification using the Ably CLI commands shown in Step 3.
+
+### Send push via channel
+
+To test push notifications via channel, tap **Subscribe to Channel** in the app and then send a push notification to the channel using the Ably CLI:
+
+
+```shell
+ably push publish --channel exampleChannel1 \
+ --title "Ably CLI" \
+ --body "Hello from CLI!" \
+ --data '{"foo":"bar"}'
+```
+
+
+Or from code:
+
+
+```javascript
+await client.channels.get(CHANNEL_NAME).publish({
+ name: 'example',
+ data: 'Hello from channel!',
+ extras: {
+ push: {
+ notification: {title: 'Channel Push', body: 'Hello from code!'},
+ data: {foo: 'bar', baz: 'qux'},
+ },
+ },
+});
+```
+
+
+If you tap **Unsubscribe from Channel**, the device no longer receives push notifications for that channel. Send the same command again and verify that no notification is received.
+
+
+
+## Next steps
+
+* Understand [token authentication](/docs/auth/token) before going to production.
+* Explore [push notification administration](/docs/push#push-admin) for managing devices and subscriptions.
+* Learn about [channel rules](/docs/channels#rules) for channel-based push notifications.
+* Read more about the [Push Admin API](/docs/api/realtime-sdk/push-admin).
+
+You can also explore the [Ably JavaScript SDK](https://github.com/ably/ably-js) on GitHub, or visit the [API references](/docs/api/realtime-sdk?lang=javascript) for additional functionality.