React Native Quickstart

This guide walks you through integrating PushEngage push notifications into a React Native application targeting Android and iOS. Estimated time: 15 minutes.

After completing this guide, your app will receive push notifications on both platforms. See the React Native SDK Reference for the full API.

Migration Guide: 0.0.x → 1.0.0

1.0.0 bumps the underlying iOS native SDK to 1.0.0, which splits the SDK into two CocoaPods so notification extension targets no longer link app-only code. Existing iOS integrations need three changes:

1. Remove the Podfile build-setting override — delete the APPLICATION_EXTENSION_API_ONLY = 'No' line from your post_install block. It is no longer required.

2. Switch extension target pods — in ios/Podfile, replace pod 'PushEngage', '0.0.6' (or any earlier version) inside each extension target block with pod 'PushEngageExtension'. The main app target continues to use pod 'PushEngage' (pulled transitively by pushengage-react-native).

3. Update extension Swift code — in NotificationService.swift (and NotificationViewController.swift if present), replace import PushEngage with import PushEngageExtension, and the PushEngage class prefix on extension API calls with PushEngageExtension. Method names are unchanged.

   // Before
   import PushEngage
   PushEngage.didReceiveNotificationExtensionRequest(request, bestContentHandler: bestContent)
   PushEngage.serviceExtensionTimeWillExpire(request, content: bestAttemptContent)
   PushEngage.getCustomUIPayLoad(for: notification.request)
   
   // After
   import PushEngageExtension
   PushEngageExtension.didReceiveNotificationExtensionRequest(request, bestContentHandler: bestContent)
   PushEngageExtension.serviceExtensionTimeWillExpire(request, content: bestAttemptContent)
   PushEngageExtension.getCustomUIPayLoad(for: notification.request)

JS API change: setFcmConfigErrorListenerEnabled is no longer exported. Native forwarding is enabled automatically on module load — subscribe directly via PushEngage.onFcmConfigError(callback).

Prerequisites

• React Native project with turbo module support (RN 0.78+)
• Firebase account (create one free) — required for Android
• Apple Developer account with a valid App ID — required for iOS
• APNs certificate or key (create one) — required for iOS
• PushEngage account and App ID (see Get Your App ID)

React Native Version

If you are using React Native 0.77.0 or earlier, install SDK version 0.0.1:

npm install @pushengage/[email protected]

Step 1 — Install the SDK

npm install @pushengage/pushengage-react-native

Step 2 — Android Setup

Firebase Cloud Messaging (FCM)

1. Open the Firebase console and sign in.
2. Click Add Project (or select an existing one).
3. Click the Android icon to add an Android app.
4. Enter your app's package name (found in android/app/build.gradle under applicationId).
5. Download google-services.json and place it at android/app/google-services.json.
6. Generate the Service Account JSON: Firebase console → Settings → Service accounts → Generate new private key.
7. Retrieve the Sender ID: Firebase console → Settings → Cloud Messaging tab.

Connect to PushEngage Dashboard

1. Log in to your PushEngage Dashboard.
2. Navigate to Site Settings → Installation → Android SDK tab.
3. Enter your Firebase Sender ID and upload the Service Account JSON.
4. Click Update and copy the App ID.

Step 3 — iOS Setup

Open your iOS workspace:

your_project_name/ios/your_project_name.xcworkspace

Enable Xcode Capabilities

1. Select the root project and choose your main app target.
2. Go to Signing & Capabilities → + Capability → Push Notifications.
3. Click + Capability → Background Modes, then check Remote notifications and Background fetch.

If Push Notifications is not visible: Apple Developer account → Certificates, Identifiers & Profiles → select your App ID → enable Push Notifications → return to Xcode.

Connect iOS to PushEngage Dashboard

1. PushEngage Dashboard → Site Settings → Installation → iOS SDK tab.
2. Upload your APNs certificate or key.
3. Copy the App ID.

Step 4 — Add Notification Service Extension (iOS)

Create the Extension

1. In Xcode, go to File → New → Target → Notification Service Extension → Next.
2. Name it PushEngageNotificationServiceExtension → Finish. Click Cancel when prompted to activate.
3. Select the extension target and set Deployment Target to iOS 12 or above.

Configure Podfile

Add the new extension target at the bottom of ios/Podfile:

ios/Podfile

target 'PushEngageNotificationServiceExtension' do
  pod 'PushEngageExtension'
end

Extension-only module

Notification extensions link the companion PushEngageExtension pod, not the main PushEngage pod. PushEngageExtension is the extension-safe core that ships the three notification-extension APIs (didReceiveNotificationExtensionRequest, serviceExtensionTimeWillExpire, getCustomUIPayLoad). Linking the wrong pod can break push delivery on production builds.

Run in the ios/ directory:

pod repo update
pod install

Implement the Extension

PushEngageNotificationServiceExtension/NotificationService.swift

import UserNotifications
import PushEngageExtension

@available(iOSApplicationExtension 12.0, *)
class NotificationService: UNNotificationServiceExtension {

    var contentHandler: ((UNNotificationContent) -> Void)?
    var bestAttemptContent: UNMutableNotificationContent?
    var request: UNNotificationRequest?

    override func didReceive(
        _ request: UNNotificationRequest,
        withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
    ) {
        self.request = request
        self.contentHandler = contentHandler
        self.bestAttemptContent = request.content.mutableCopy() as? UNMutableNotificationContent

        if let bestContent = bestAttemptContent {
            PushEngageExtension.didReceiveNotificationExtensionRequest(request, bestContentHandler: bestContent)
            contentHandler(bestContent)
        }
    }

    override func serviceExtensionTimeWillExpire() {
        if let contentHandler = contentHandler,
           let request = request,
           let bestAttemptContent = bestAttemptContent {
            guard let content = PushEngageExtension.serviceExtensionTimeWillExpire(
                request, content: bestAttemptContent
            ) else {
                contentHandler(bestAttemptContent)
                return
            }
            contentHandler(content)
        }
    }
}

Step 5 — Add Notification Content Extension (iOS, Optional)

1. In Xcode, go to File → New → Target → Notification Content Extension → Next.
2. Name it PushEngageNotificationContentExtension → Finish. Click Cancel when prompted.
3. Set Deployment Target to iOS 12 or above.
4. Add to ios/Podfile at the bottom:

target 'PushEngageNotificationContentExtension' do
  pod 'PushEngageExtension'
end

Run pod install in the ios/ directory.

Step 6 — Add App Groups (iOS)

1. Select your main app target in Xcode → Signing & Capabilities → + Capability → App Groups.
2. Add a new App Group: group.com.yourcompany.yourapp.
3. In your main app's Info.plist, add:
   • Key: PushEngage_App_Group_Key
   • Value: group.com.yourcompany.yourapp
4. In PushEngageNotificationServiceExtension/Info.plist, add the same key and value.
5. Select the extension target → enable the same App Group under Signing & Capabilities.

Step 7 — Initialize the SDK

In your root index.js:

index.js

import { AppRegistry } from 'react-native';
import PushEngage from '@pushengage/pushengage-react-native';
import App from './App';

PushEngage.setAppId('YOUR_APP_ID');
// Trigger the system permission prompt; on grant, the SDK auto-subscribes.
PushEngage.requestNotificationPermission();

AppRegistry.registerComponent('YourAppName', () => App);

For iOS, add the PushEngage lines (marked // add) to your existing ios/AppDelegate.mm. Leave the rest of the React Native template — including self.dependencyProvider and the bundleURL methods — in place:

ios/AppDelegate.mm

#import "AppDelegate.h"
@import PushEngage; // add

@implementation AppDelegate

- (instancetype)init {
    self = [super init];
    if (self) {
        [PushEngage swizzleInjectionWithIsEnabled:YES]; // add
    }
    return self;
}

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    self.moduleName = @"YourAppName";
    self.dependencyProvider = [RCTAppDependencyProvider new]; // keep — React Native template
    self.initialProps = @{};
    [PushEngage setInitialInfoFor:application with:launchOptions]; // add
    return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

// add — forward background push to the SDK
- (void)application:(UIApplication *)application
    didReceiveRemoteNotification:(NSDictionary *)userInfo
    fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    completionHandler(UIBackgroundFetchResultNewData);
}

// Keep the rest of your React Native template (sourceURLForBridge:, bundleURL, …) unchanged.

@end

note

Replace YOUR_APP_ID and YourAppName with your actual values.

Step 8 — Send a Test Notification

1. Build and run on a physical device.
2. Accept the notification permission prompt.
3. In the PushEngage Dashboard → Campaign → Push Broadcasts → Create New Push Broadcast → send a test.

Troubleshooting

iOS build error: @import when C++ modules are disabled
In Xcode → your app target → Build Settings → Other C++ Flags → add -fcxx-modules.

iOS: notifications not received after correct setup
Verify PushEngage_App_Group_Key is in both the main app's Info.plist and the extension's Info.plist, with the identical App Group name.

Next Steps

• React Native SDK Reference →
• Mobile SDK Overview →