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)

• 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).

📘

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:

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.

3. Under Apps, click to add a new app.
4. 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.

5. 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.
6. Fill out the remaining settings and save the changes.
7. Copy your app key and keep it handy for the setup.

Step B: update the configuration file

Find a new file (CampaignConfig.json) in the root directory of your app. Use this file to customize the library configuration.

1. Make sure you are using the right build. During testing, set useRelease to false. For production, use true.

{
  "useRelease": true
}

2. 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": ""
}

3. 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"
    }
  }
}

4. 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].

Step A: Add the Notification Service Extension

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. In your XCode project, click File > New > Target.
2. On the iOS tab, select Notification Service Extension.

3. In the Language list, select Objective-C. Fill out the remaining settings as appropriate.

4. If a confirmation message appears, select Activate.

5. Find a new target and a new directory in your project.

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.

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

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.

2. In the project navigator, open the Plugins directory and select MCEManualConfiguration.m. Add the Notification Service target to the file's Target Membership.

3. In the project navigator, open the Notification Service directory and select NotificationViewController.h. Import the AcousticMobilePushNotification framework.

#import <AcousticMobilePushNotification/AcousticMobilePushNotification.h>

4. In the same file, add an MCE notification service property.

@property MCENotificationService * notificationService;

5. In the same directory, select NotificationViewController.m. Import MCEManualConfiguration.h and AcousticMobilePush.h.

#import "MCEManualConfiguration.h"
#import "AcousticMobilePush/AcousticMobilePush.h"

6. 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;
}

7. Update the didReceiveNotificationRequest method to use the notification-action.

if (request.content.userInfo[@"notification-action"]) {
  [self.notificationService didReceiveNotificationRequest:request
                                       withContentHandler:contentHandler];
  return;
}

8. 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