Integrate the Campaign Cordova SDK into your app

Cordova Campaign SDK provides mobile app message handling and display capabilities for Android and iOS apps. To add the SDK to your app, use 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

Acoustic Campaign

  • To use the SDK, your company must have an active Acoustic Campaign subscription.
  • You must have a developer account for Acoustic Campaign. The account must have the following permissions enabled: Enable Mobile App Push and Enable Development for Mobile App Push.
  • You must have the base URL associated with your subscription. Contact your account manager if you don't have the base URL yet.

Mobile app compatibility

The Campaign SDK works on end users' devices running the following operating systems:

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

🚧

Warning

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

Development environment

To integrate the Campaign SDK into an iOS app using Cordova, you will need the following:

  • Xcode 15 with Command Line Tools
  • Cordova iOS plugin 7.1.x or later
  • Apple Developer Program membership (free accounts do not support push notifications)

Also, your development project must meet the following requirements:

  • It must use an explicit App ID and must be assigned to a team. For the App ID, the push notification service must be enabled.
  • The Push Notifications capability must be enabled in the project. For instructions, see Adding capabilities to your app in the Xcode guide.
  • The project must be 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).

📘

Important

The provisioning profile must match the push certificate. For example, a development provisioning profile works with a development push certificate.

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

Authentication type Credentials 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)

To integrate the Campaign SDK into an Android app using Cordova, you will need the following:

  • Android Studio Iguana | 2023.2.1 Patch 1 or later
  • Cordova Android plugin 12.0.1 or later

Also, your development project must meet the following requirements:

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

See official Cordova documentation for detailed requirements.

Before you begin

To activate the Campaign SDK within your 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 > Apps.
Apps menu in Campaign
  1. Click to add a new app.
  2. 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.
  3. 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 an iOS app to Campaign
  1. Fill out the remaining settings and save the changes.
  2. Copy your app key and keep it handy for the setup.
Copying an app key from Campaign
  1. Log in to Acoustic Campaign under a developer account.
  2. In the navigation menu, select Administration > Push developer resources > Apps.
Apps menu in Campaign
  1. Click to add a new app.
  2. Set the Type setting in accordance with the distribution model.
  3. In the Push Service field, select GCM/FCM. Set the type of authentication to V1. Provide required credentials for the selected authentication type.
Push notification service selection for Android
  1. Fill out the remaining settings and save the changes.
  2. Copy your app key and keep it handy for the setup.
Copying an app key from Campaign

Initial setup

Navigate to the main project directory and add cordova-acoustic-mobile-push.

$ npm i cordova-acoustic-mobile-push

If you need to use a beta or debug build, add -beta to the name of the package.

$ npm i cordova-acoustic-mobile-push-beta

Then run the following Node.js command from the main project directory. It will apply the changes and install related frameworks.

node node_modules/cordova-acoustic-mobile-push-sdk/scripts/installPlugins.js

Customizing the SDK configuration

After the initial setup, you will find the CampaignConfig.json file in the root directory of your app. Use this file to customize the SDK configuration.

  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. You can enter a version number or submit an empty value to use the latest available version (recommended).
{ "iOSVersion": "" }
  1. In the iOS section, enter the appKey you have generated and the baseUrl provided by your account manager. Do not change the app key after you publish your app.
{ "iOS": { "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 changes, run the following Node.js command from the main project directory.
node node_modules/cordova-acoustic-mobile-push-sdk-beta/scripts/installPlugins.js

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

  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. You can enter a version number or submit an empty value to use the latest available version (recommended).
{ "androidVersion ": "" }
  1. In the android section, enter the appKey and baseUrl provided by your account team. Do not change the app key after you publish your app.
{ "android": { "baseUrl": "https://mobile-sdk-lib-XX-Y.brilliantcollector.com", "appKey": { "prod": "INSERT APP KEY HERE" } } }
  1. Important: to apply the updates, run the following Node.js command from the main project directory.
node node_modules/cordova-acoustic-mobile-push-sdk-beta/scripts/installPlugins.js

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

Final project preparation

Step A: Add a Notification Service target

One of the frameworks installed using the installPlugins.js script is AcousticMobilePushNotification. It lets you enable dynamic action categories and media attachments in iOS notifications. Before a notification from the APNs service is displayed to an end user, the media attachment URL is extracted, and then the media file is downloaded and attached to the notification.

The notification service extension functions as a separate app within your app bundle and requires separate provisioning.

  1. Open the .xcworkspace file in platforms/ios/{project_name}.xcworkspace.
  2. In the navigation menu, click File > New > Target.
  3. On the iOS tab, select Notification Service Extension.
Notification Service Extension
  1. Fill out the settings for your app.
Notification Service Target
  1. If a confirmation message appears, select Activate.
Activate New Target (confirmation)
  1. Find a new target and a new directory in your project.
Project changes: new target and directory

Step B: Configure the Notification Service target

Select the new target and go through the following settings on the General tab.

  • Minimum deployments. Make sure the iOS version is the same as in the primary application target.
  • Frameworks and Libraries. Add AcousticMobilePushNotification.xcframework and libCordova.a. For AcousticMobilePushNotification.xcframework, the Embed and Sign option must be selected. AcousticMobilePush.xcframework should already be present based on earlier steps in these instructions.

On the Signing & Capabilities tab, add two capabilties: Keychain Sharing and App Groups. Make sure you use the same values as for the primary application target.

Additional capabilities

On the Build Settings tab, expand the Linking - General section. Make sure Other Linker Flags is set to -ObjC.

Other Linker Flags in Build Settings

Step C: Update related project files

  1. In the project navigator, select config.xml. Add the Notification Service target to the file's Target Membership.
Target membership setting for config.xml
  1. In the project navigator, open the Plugins directory and select MCEManualConfiguration.m. Add the Notification Service target to the file's Target Membership.
Target membership setting for MCEManualConfiguration.m
  1. In the project navigator, open the Notification Service directory and select NotificationViewController.h. Import the AcousticMobilePushNotification framework.
#import <AcousticMobilePushNotification/AcousticMobilePushNotification.h>
  1. In the same file, add an MCE notification service property.
@property MCENotificationService * notificationService;
  1. In the same directory, select NotificationViewController.m. Import MCEManualConfiguration.h and AcousticMobilePush.h.
#import "MCEManualConfiguration.h" #import "AcousticMobilePush/AcousticMobilePush.h"
  1. Create an initializer method to initialize the MCENotificationService property:
- (instancetype)init { if (self = [super init]) { [MCEConfig sharedInstanceWithDictionary:MCEManualConfiguration.xmlSettings]; self.notificationService = [[MCENotificationService alloc] init]; } return self; }
  1. Update the didReceiveNotificationRequest method to use the notification-action.
if (request.content.userInfo[@"notification-action"]) { [self.notificationService didReceiveNotificationRequest:request withContentHandler:contentHandler]; return; }
  1. In the serviceExtensionTimeWillExpire method, call the mce mobile push method of the same name.
[self.notificationService serviceExtensionTimeWillExpire];

Sample NotificationViewController.h file

#import <UserNotifications/UserNotifications.h> #import <AcousticMobilePushNotification/AcousticMobilePushNotification.h> @interface NotificationService : UNNotificationServiceExtension @property MCENotificationService * notificationService; @end

Sample NotificationViewController.m file

#import "NotificationService.h" #import "MCEManualConfiguration.h" @interface NotificationService () @property (nonatomic, strong) void (^contentHandler) (UNNotificationContent *contentToDeliver); @property (nonatomic, strong) UNMutableNotificationContent *bestAttemptContent; @end @implementation NotificationService -(instancetype)init { if(self = [super init]) { [MCEConfig sharedInstanceWithDictionary: MCEManualConfiguration. xmlSettings]; self.notificationService = [[MCENotificationService alloc] init]; } return self; } - (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull)) contentHandler { if(request.content.userInfo[@"notification-action"]) { [self.notificationService didReceiveNotificationRequest: request withContentHandler: contentHandler]; return; } } - (void)serviceExtensionTimeWillExpire { [self.notificationService serviceExtensionTimeWillExpire]; } @end

Step D: Build and run the app

In a terminal emulator, navigate to the project directory. Now you can build and run your app with the Campaign SDK.

cordova build ios cordova run ios
  1. Go to the Firebase Console and download the Firebase Android configuration file (google-services.json). Add the file to the main project directory: android/app/.
  2. To apply the changes, run the following Node.js command from the primary project directory.
node node_modules/cordova-acoustic-mobile-push-sdk-beta/scripts/installPlugins.js
  1. Synchronize your project and run the app.
cordova build android