Campaign SDK for iOS

You can configure mobile app messages in iOS apps that are developed with Swift and Objective C.

The mobile app messaging SDK for Apple iOS provides support for the following:

  • Registration for Apple Push Notification Service(APNS).
  • Mobile app message handling and display.
  • Support for inbox and in-app message.
  • Apple watch plugin to use with your iOS mobile app messages.
  • Support for SDK basic/custom events.
  • Support for location-based messaging.

Get started

  • Join the iOS Developer Program. Find your team that manages the Apple Developer Program for your organization.
  • Subscribe to an Acoustic Campaign account. For more information, contact your customer service focal. To get started with Acoustic Mobile campaign, see Get started with mobile campaign.
  • Install the iOS development tools.
  • Install your developer certificate downloaded from your team’s Apple Developer page.

Download the iOS SDK

Download the latest version of the iOS SDK and access the iOS Native APIs references and plug-ins.

📘

Note:

SDK versions before v3.6.1.0 do not support Swift application delegates. As a workaround, you can use an Objective-C delegate class. For an example, see the sample Swift project provided in the mobile app messaging SDK v3.6.1.0 (and later).

Enable Automatic Reference Counting (ARC)

You must have an app that is compliant with Automatic Reference Counting (ARC). To enable ARC in your Xcode project,

  • For Swift – go to Target > Build Phases > Compile Source. Then, select the files in the Plug-ins folder, and add -fobjc-arc.
  • For Objective C – go to Edit > Convert > To Objective-C ARC and select the project you want to convert.

It is possible to use a non-ARC project as long as the SDK, its plug-ins, and templates are built with ARC turned on. To do so, go to Target > Build Phases > Compile Source, select the MCE files, and add -fobjc-arc to all of them.

Migrate to the latest version of Swift

To migrate to the latest version, click Edit Menu > Migrate > Current Swift Syntax.

import Foundation
import UIKit
import AcousticMobilePush
let _ = UIApplicationMain(CommandLine.argc, CommandLine.unsafeArgv, nil, NSStringFromClass(MCEAppDelegate.self) )
import Foundation
import UIKit 
import AcousticMobilePush
let argv = UnsafeMutableRawPointer(CommandLine.unsafeArgv).bindMemory(to: UnsafeMutablePointer.self, capacity: Int(CommandLine.argc))
let _ = UIApplicationMain(CommandLine.argc, argv, nil, NSStringFromClass(MCEAppDelegate.self) )

Understand the iOS payload formats

A payload is a property list that specifies how alerts and custom data are displayed to your app user. A JSON dictionary object defines the property list.

Here is an example of a very simple APNS payload that sets the app badge to 2 and opens a URL when clicked:

{
    "aps": {
        "alert": "Bob wants to play poker",
        "badge": 2
    },
    "notification-action": {
        "type": "url",
        "value": "https://acoustic.com"
    }
}

Advanced payload options

Advanced message options are available on iOS 10 (and later). These options require more information in the payload.

You can use Notification Content Extensions to add media attachments to push notifications.
To add media attachments:

  1. Add the mutable-content flag to the aps key in the iOS 10 payload.
  2. Then, add the media-attachment key to the root of the iOS 10 payload.

The URL for the media file is specified in the media-attachment key of the payload. The notification service downloads the media file from the URL in the payload. The media file is then attached to the message.

There are several keys that you can use in the iOS payload.

KeyDescription
mutable-contentSet this flag to enable iOS 10 apps to process media attachments that are displayed to the user. You can specify a URL in the media-attachment key on the root of the payload. Example: "mutable-content": 1
media-attachmentUse this field to specify a URL for the media attachment. This field enables the notification service to download the media attachment. The notification service can then attach the media file to a message. Example: "media-attachment": "https://url/to/BostonMap.png"
Titles and subtitlesUse these fields to add titles and subtitles to notifications. Titles are displayed at the top, and subtitles are displayed within the notifications. The user can pull down the notification to view additional content. The below the fold section of the alert is visible and available for user interaction. Add the title field and subtitle field to the alert key in the iOS 10 payload.
title – To add a title to the notification, specify a notification title in the title field. Example: "title": "Welcome to Boston"
subtitle – To add a subtitle to the notification, add text in the subtitle field. Example: "subtitle": "Thanks for using Rent-A-Car. Your rental is ready."
category-nameAdd the category-name key to override random category names generated by the SDK. This key enables you to use iOS 10 and later features. These features require predefined compiled category names —for example, Notification Content Extensions.

Best practice for specifying file sizes in media attachments

When you add media attachments to messages in iOS 10 apps, follow Apple's size limits:

  • Audio Types: wav, aiff, mp3 or m4a Max Size: 5MB
  • Image Types: gif, jpg, png Max Size: 10MB
  • Video types: mp4, mpg, avi Codec: MPEG, MPEG2, MPEG4, AVI Max Size: 50MB
    For more details about Apple's supported file types for media, see UNNotificationAttachment.

The following code example shows a more complicated iOS payload:

{
    "aps": {
        "mutable-content": 1,
        "alert": {
            "title": "Notification title",
            "subtitle": "Notification subtitle",
            "body": "Notification body"
        }
    },
    "media-attachment": "https://url/to/content.mpg",
    "notification-action": {
        "type": "url",
        "value": "http://acoustic.com"
    },
    "category-actions": [
        {
            "name": "foo",
            "type": "url",
            "value": "https://acoustic.com"
        },
        {
            "name": "bar",
            "type": "url",
            "value": "https://example.com"
        }
    ],
    "category-name": "content-extension"
}

Update your existing project to the new Acoustic frameworks

The following instructions are for both Swift and Obj-C:

  1. Remove existing IBMMobilePush.framework, IBMMobilePushWatch.framework, IBMMobilePushNotificationService.framework.
  2. Drag AcousticMobilePush.xcframework into the general tab of iOS Target.
  3. Drag AcousticMobilePushNotification.xcframework into the iOS application's Embed Frameworks Build Phase`.

📘

Note:

AcousticMobilePushNotification.xcframework cannot be on the Notification Service Extension's general tab. If added, the automated App Store review will result in errors while the app is being uploaded. The following errors will occur:

  • ERROR ITMS-90205: "Invalid Bundle. The bundle at Name.appex contains disallowed nested bundles." and
  • ERROR ITMS-90206: "Invalid Bundle. The bundle at Name.appex contains the disallowed file 'Frameworks.'"
  1. Drag the AcousticMobilePushWatch.xcframework into the general tab of Watch Extension Target.
  2. The SDK namespaces have been renamed. All references to the namespaces in your code will need to be modified.

Make the following changes:

FromTo
IBMMobilePushWatchAcousticMobilePushWatch
IBMMobilePushNotificationServiceAcousticMobilePushNotification (without the "Service" suffix)
IBMMobilePushAcousticMobilePush