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:

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

3. Click to add a new app.
4. 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.
5. 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.

6. Fill out the remaining settings and save the changes.
7. Copy your app key and keep it handy for the setup.

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

4. Fill out the settings for your app.

5. If a confirmation message appears, select Activate.

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