Push notification integration

This reference article covers how to set push notifications for React Native. Integrating push notifications requires setting up each native platform separately. Follow the respective guides listed to finish the installation.

Step 1: Complete the initial setup

• expo
• android native
• ios native

1
"firebaseCloudMessagingSenderId": "693679403398"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "expo": {
    "android": {
      "googleServicesFile": "PATH_TO_GOOGLE_SERVICES"
    },
    "plugins": [
      [
        "@braze/expo-plugin",
        {
          "androidApiKey": "YOUR-ANDROID-API-KEY",
          "iosApiKey": "YOUR-IOS-API-KEY",
          "enableBrazeIosPush": true,
          "enableFirebaseCloudMessaging": true,
          "firebaseCloudMessagingSenderId": "YOUR-FCM-SENDER-ID",
          "androidHandlePushDeepLinksAutomatically": true
        }
      ],
    ]
  }
}

Step 2: Request push notifications permission

Use the Braze.requestPushPermission() method (available on v1.38.0 and up) to request permission for push notifications from the user on iOS and Android 13+. For Android 12 and below, this method is a no-op.

This method takes in a required parameter that specifies which permissions the SDK should request from the user on iOS. These options have no effect on Android.

1
2
3
4
5
6
7
8
const permissionOptions = {
  alert: true,
  sound: true,
  badge: true,
  provisional: false
};

Braze.requestPushPermission(permissionOptions);

Step 2.1: Listen for push notifications (optional)

You can additionally subscribe to events where Braze has detected and handled an incoming push notification. Use the listener key Braze.Events.PUSH_NOTIFICATION_EVENT.

1
2
3
4
Braze.addListener(Braze.Events.PUSH_NOTIFICATION_EVENT, data => {
  console.log(`Push Notification event of type ${data.payload_type} seen. Title ${data.title}\n and deeplink ${data.url}`);
  console.log(JSON.stringify(data, undefined, 2));
});

Push notification event fields

For a full list of push notification fields, refer to the table below:

Step 3: Enable deep linking (optional)

To enable Braze to handle deep links inside React components when a push notification is clicked, first implement the steps described in React Native Linking library, or with your solution of choice. Then, follow the additional steps below.

To learn more about what deep links are, see our FAQ article.

• android native
• ios native

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  self.moduleName = @"BrazeProject";
  self.initialProps = @{};

  BRZConfiguration *configuration = [[BRZConfiguration alloc] initWithApiKey:apiKey endpoint:endpoint];
  configuration.triggerMinimumTimeInterval = 1;
  configuration.logger.level = BRZLoggerLevelInfo;
  Braze *braze = [BrazeReactBridge initBraze:configuration];
  AppDelegate.braze = braze;

  [self registerForPushNotifications];
  [[BrazeReactUtils sharedInstance] populateInitialPayloadFromLaunchOptions:launchOptions];

  return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

1
2
3
4
5
6
7
8
9
// Handles deep links when an iOS app is launched from a hard close via push click.
// This edge case is not handled in the React Native Linking library and is provided as a workaround by Braze.
Braze.getInitialPushPayload(pushPayload => {
  if (pushPayload) {
    console.log('Braze.getInitialPushPayload is ' + pushPayload);
    showToast('Initial URL is ' + pushPayload.url);
    handleOpenUrl({ pushPayload.url });
  }
});

Step 4: Test displaying push notifications

At this point, you should be able to send notifications to the devices. Adhere to the following steps to test your push integration.

1. Set an active user in the React Native application by calling Braze.changeUserId('your-user-id') method.
2. Head to Campaigns and create a new push notification campaign. Choose the platforms that you’d like to test.
3. Compose your test notification and head over to the Test tab. Add the same user-id as the test user and click Send Test. You should receive the notification on your device shortly.

Advanced configurations with the Expo plugin

For certain advanced cases that need to be configured in the native Android and iOS SDKs, Braze provides special configurations via the Expo plugin to handle those push notifications behaviors.

Forwarding Android push to additional FMS

If you want to use an additional Firebase Messaging Service (FMS), you can specify a fallback FMS to call if your application receives a push that isn’t from Braze. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "expo": {
    "plugins": [
      [
        "@braze/expo-plugin",
        {
          ...
          "androidFirebaseMessagingFallbackServiceEnabled": true,
          "androidFirebaseMessagingFallbackServiceClasspath": "com.company.OurFirebaseMessagingService"
        }
      ]
    ]
  }
}

Enabling rich push notifications for iOS

To enable rich push notifications on iOS using Expo, configure the enableBrazeIosRichPush property to true in your expo.plugins object in app.json:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "expo": {
    "plugins": [
      [
        "@braze/expo-plugin",
        {
          ...
          "enableBrazeIosRichPush": true
        }
      ]
    ]
  }
}

Lastly, add the bundle identifier for this app extension to your project’s credentials configuration: <your-app-bundle-id>.BrazeExpoRichPush. For further details on this process, refer to Using app extensions with Expo Application Services.

Enabling Push Stories for iOS

To enable Push Stories on iOS using Expo, ensure you have an app group defined for your application. For more information, see Adding an App Group.

Next, configure the enableBrazeIosPushStories property to true and assign your app group ID to iosPushStoryAppGroup in your expo.plugins object in app.json:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "expo": {
    "plugins": [
      [
        "@braze/expo-plugin",
        {
          ...
          "enableBrazeIosPushStories": true,
          "iosPushStoryAppGroup": "group.com.company.myApp.PushStories"
        }
      ]
    ]
  }
}

Lastly, add the bundle identifier for this app extension to your project’s credentials configuration: <your-app-bundle-id>.BrazeExpoPushStories. For further details on this process, refer to Using app extensions with Expo Application Services.

Using app extensions with Expo Application Services

If you are using Expo Application Services (EAS) and have enabled enableBrazeIosRichPush or enableBrazeIosPushStories, you will need to declare the corresponding bundle identifiers for each app extension in your project. There are multiple ways you can approach this step, depending on how your project is configured to manage code signing with EAS.

One approach is to use the appExtensions configuration in your app.json file by following Expo’s app extensions documentation. Alternatively, you can set up the multitarget setting in your credentials.json file by following Expo’s local credentials documentation.