Skip to main content

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.

Prerequisites​

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 10 or above.

Configure Podfile​

Open ios/Podfile. Inside the existing post_install block, add the lines shown below. Then add the new extension target at the bottom of the file:

ios/Podfile
# Inside your existing post_install block, add:
installer.pods_project.targets.each do |target|
  target.build_configurations.each do |config|
    config.build_settings['APPLICATION_EXTENSION_API_ONLY'] = 'No'
  end
end

# At the bottom of Podfile, add:
target 'PushEngageNotificationServiceExtension' do
  pod 'PushEngage', '0.0.6'
end

Run in the ios/ directory:

pod repo update
pod install

Implement the Extension​

PushEngageNotificationServiceExtension/NotificationService.swift
import UserNotifications
import PushEngage

@available(iOSApplicationExtension 10.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 {
            PushEngage.didReceiveNotificationExtensionRequest(request, bestContentHandler: bestContent)
            contentHandler(bestContent)
        }
    }

    override func serviceExtensionTimeWillExpire() {
        if let contentHandler = contentHandler,
           let request = request,
           let bestAttemptContent = bestAttemptContent {
            guard let content = PushEngage.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 10 or above.
  4. Add to ios/Podfile at the bottom:
target 'PushEngageNotificationContentExtension' do
  pod 'PushEngage', '0.0.6'
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 PushEngage initialization to ios/AppDelegate.mm:

ios/AppDelegate.mm
#import "AppDelegate.h"
@import PushEngage;

@implementation AppDelegate

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

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    self.moduleName = @"YourAppName";
    self.initialProps = @{};
    [PushEngage setInitialInfoFor:application with:launchOptions];
    return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

- (void)application:(UIApplication *)application
    didReceiveRemoteNotification:(NSDictionary *)userInfo
    fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    completionHandler(UIBackgroundFetchResultNewData);
}

@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​

Last updated on