Documentation
Help CenterCommunityDevelopersAcademyStatus

Add the Campaign SDK to your React Native app

Suggest Edits

The React Native Campaign SDK provides mobile app message handling and display capabilities for Android and iOS apps. To add the SDK to your app, use yarn or npm CLI. For basic and advanced settings, we provide a unified configuration file CampaignConfig.json.

🚧

Warning

The Campaign SDK does not encrypt data transmitted via push notifications and in-app messages. To transmit sensitive information, you must encrypt it before sending and decrypt it in the memory of the end user's device.

Requirements

Mobile app compatibility

  • iOS 13 and later
  • Android 5.0 (API level 21) and later

Development environment

To add the Campaign SDK to an iOS app using React Native, you will need the following:

  • Xcode 15 with Command Line Tools
  • Node.js 18 or later
  • React Native 0.64 or later
  • Apple Developer Program membership (free accounts do not support push notifications)

To add the Campaign SDK to an Android app using React Native, you will need the following:

  • Node.js 18 or later
  • React Native 0.64 or later

Currently, we do not support the Expo CLI.

Before you begin

Before you begin, make sure the following conditions are met.

Acoustic Campaign

  • Your company has an active Acoustic Campaign subscription.
  • You have a developer account for Acoustic Campaign. The account has the following permissions enabled: Enable Mobile App Push and Enable Development for Mobile App Push.

iOS app

  • Your iOS project uses an explicit App ID and is assigned to a team. For the App ID, the push notification service is enabled.
  • In your iOS project, the Push Notifications capability is enabled. For instructions, see Adding capabilities to your app in the Xcode guide.
  • Your app is registered with Apple Push Notification service (APNs). You can use either of the following authentication methods to secure connection to APNs: token-based (p8) (recommended by Apple) or certificate-based (p12).

What to prepare for the setup depending on the selected authentication type:

Authentication typeCredentials to submit to Acoustic Campaign
Token-based (p8)1) An authentication token signing key, which is a text file with the .p8 extension
2) A 10-character string with the Key ID
3) The Team ID associated with your app
4) The Bundle ID assigned to your app
Certificated-based (p12) 1) A certificate file with the .p12 extension
2) CSR (a private key used to encrypt the certificate)

Android app

  • Your mobile app is registered and implemented (this is necessary to enable testing and creating notifications).
  • Firebase Cloud Messaging is enabled.
  • The install location of your app is set to the internal memory of a mobile device, not to external storage cards.

Initial setup

  1. Add react-native-acoustic-mobile-push from the project folder.
yarn add react-native-acoustic-mobile-push

npm i react-native-acoustic-mobile-push
  1. Edit App.js to include the following two lines after the existing import statements:
import { NativeModules } from 'react-native';
const { RNAcousticMobilePush } = NativeModules;
RNAcousticMobilePush.requestPushPermission();

📘

Note

If you aren't using the App.js bundle, you can import the SDK into the component you need.

Customizing SDK configuration

Step A: get an app key

To activate the Campaign SDK within your iOS app, you must generate an app key for it and upload the app's push certificate to Acoustic Campaign.

  1. Log in to Acoustic Campaign under a developer account.
  2. In the navigation menu, select Administration > Push developer resources.
Access to mobile app setup

Access to mobile app setup

  1. Under Apps, click to add a new app.
  2. In the Push Service field, select APNs. Then select the type of authentication to use: P8 or P12. Provide required credentials for the selected authentication type.
Adding mobile app to Campaign

Adding mobile app to Campaign

  1. Set the Type setting in accordance with the distribution model. Select Development to run the app from Xcode with a development provisioning profile. Or select Production to run the app with an App Store, Enterprise, or ad hoc provisioning profile.
  2. Fill out the remaining settings and save the changes.
  3. Copy your app key and keep it handy for the setup.
Copy app key

Copy app key

Step B: update the configuration file

  1. In the root directory of your app, find the CampaignConfig.json file. Use this file to customize the SDK configuration.
Editing CampaignConfig.json

CampaignConfig.json in the root folder

  1. Make sure you are using the right build. During testing, set useRelease to false. For production, use true.
  "useRelease": true,
  1. Check the version of the Campaign SDK for your iOS app. We recommend using the latest version whenever possible.
 "iOSVersion": "3.9.18",
  1. In the iOS section, enter the app key you have generated at step A and the base URL provided by your account team. Do not change the app key after you publish your app.
{
  "baseUrl": "https://mobile-sdk-lib-XX-Y.brilliantcollector.com",
  "appKey": {
    "dev": "INSERT YOUR DEV APPKEY HERE",
    "prod": "INSERT YOUR PROD APPKEY HERE"
  }
}
  1. Important: to apply the updates, navigate to the main project directory and run the following Node.js command.
node node_modules/react-native-acoustic-mobile-push/postinstall.js ./

To learn more about your options, see the following recipe: Configure mobile SDKs [iOS].

Step C: integrate the iOS notification service

The iOS notification service requires separate provisioning. This framework lets you enable "push received" events, dynamic action categories, and media attachments.

  1. In your XCode project, go to the File menu and select New > Target. A dialog box opens.
  2. Under iOS, select Notification Service Extension.
Choose a template: Notification Service Extension

Choose a template: Notification Service Extension

  1. Set the extension name to NewAppNotificationService, and choose Objective-C as Language.
  2. If a confirmation message appears, click Activate.
Confirmation message

Confirmation message

  1. Select the new target and change its Bundle Identifier prefix to .notification.
  2. Verify that the new target has the same iOS version as the application target. SDK minimum supported version is 12.4.
  3. Add the MceConfig.json file to the Notification Service target. Open the file and check the notification service target membership in the Target Membership of the File Inspector in the Xcode pane.
  4. Add the Keychain Sharing capability to both your notification service extension and Application target. Be sure to use the same value as the main application.
  5. Replace the contents of NotificationService.m with the following code.
// NotificationService.m
#import "NotificationService.h"

@implementation NotificationService

@end
  1. Replace the contents of NotificationService.h with the following code.
// NotificationService.h
#import <UserNotifications/UserNotifications.h>
#import <AcousticMobilePushNotification/AcousticMobilePushNotification.h>

@interface NotificationService : MCENotificationService

@end

Step A: get an app key

To activate the Campaign SDK within your Android app, you must generate an app key for it and upload the app's push certificate to Acoustic Campaign.

  1. Log in to Acoustic Campaign under a developer account.
  2. In the navigation menu, select Administration > Push developer resources.
Access to mobile app setup

Access to mobile app setup

  1. Under Apps, click to add a new app.
  2. In the Push Service field, select GCM/FCM. Then select the type of authentication to use: Legacy or V1. Provide required credentials for the selected authentication type.
Adding mobile app to Campaign

Adding mobile app to Campaign

  1. Fill out the remaining settings as appropriate and save the changes.
  2. Copy your app key and keep it handy for the setup.
Copy app key

Copy app key

Step B: update the configuration file

  1. In the root directory of your app, find the CampaignConfig.json file. Use this file to customize the SDK configuration.
Editing CampaignConfig.json

CampaignConfig.json in the root folder

  1. Make sure you are using the right build. During testing, set useRelease to false. For production, use true.
  "useRelease": true,
  1. Check the version of the Campaign SDK for your Android app. We recommend using the latest version whenever possible.
"androidVersion": "3.9.18",
  1. In the android section, enter the app key you have generated and the base URL provided by your account team. Do not change your app key after you publish your app.
{
  "baseUrl": "https://mobile-sdk-lib-XX-Y.brilliantcollector.com",
  "appKey": {
    "prod": "INSERT APP KEY HERE"
  }
}
  1. Important: to apply the updates, navigate to the main project directory and run the following Node.js command.
node node_modules/react-native-acoustic-mobile-push/postinstall.js ./

To learn more about available configuration options, see the following recipe: Configure mobile SDKs [Android].

Final project preparation

  1. Open your iOS project in Xcode.
  2. (optional) Enable location updates in the background. For instructions, see Handling location updates in the background in the Xcode guide.
  3. Run the iOS.
  4. Run pod install from the App's ios folder.
pod install
  1. Launch your iOS app.
npx react-native run-ios

📘

Note:

The iOS Simulator app is unable to handle push messages. Run your app on a real device.

  1. Go to the Firebase Console and download the Firebase Android configuration file (google-services.json). Add the file to your project folder: android/app/.
  2. If you are going to support location services, add the following line to the app-level build.gradle file.
implementation 'com.google.android.gms:play-services-location:<play-services version>'
  1. Synchronize your project and run the app.
npx react-native run-android

Updated 5 months ago