Build the iOS sample app

Overview

The Acoustic mobile SDK includes a sample app that illustrates the use of our SDK, including the sending of push notifications. You can use the sample app to view quick example implementations of all core SDK functionality.

The sample app provides you with the following:

• Credential and ID screens that display the following values: user ID, channel ID, and app key.
• Push action screen that displays the default and custom push actions. These actions can be used when you send a mobile app message to your app users.
• Custom action screen that displays details about the example categories. You can use the example categories with the sample app.
• Test events so you can send events to the server.
• Test user attributes so you can send a user attribute to the server.
• Information about geofences and iBeacons.

The iOS sample app contains example implementations of our automatic integration method, our manual integration method, the use of the Mceconfig.json and a config object for defining SDK settings, as well as examples of both Acoustic-supplied and a custom example plugin.

📘

Note:

You cannot receive push notifications on a simulator. To experience all capabilities of the Sample app, it must be run on a real device.

Before you begin

• Create an Apple ID and password.
• Create an iPhone app key on the Campaign Automation console. Then, upload the APNS certificate.
• Add the sample iOS app to Acoustic Campaign. For more information, see Add and configure mobile developer apps.
• Download the latest version of the Mobile app messaging SDK for iOS.

Register the sample app with Apple

1. Enable push notifications in your XCode project (iOS 10 only).
   a. Go to Target sample in your XCode project.
   b. Select the Capabilities tab, and then enable Push Notifications.

2. Ensure that your iOS application contains a bridging header (Swift only).
   The bridging header must contain #import <AcousticMobilePush/AcousticMobilePush.h>. For more information, see Swift.

3. Set up App Keys or a push certificate in the Apple developer center.
   Apple Push Notification Services (APNS) allows an app to notify users when it is not running in the foreground. You must register to connect to the APNS and send mobile app messages to devices. Register with the APNS by providing an explicit app ID. You cannot use a wildcard App ID.

When you generate an explicit app ID, you can use one of the following valid forms of authentication:
P8 SSL signing key
If you use the P8 SSL signing key, you can send mobile app messages to all the applications in your Apple org. You can send the messages because you can create separate App Keys for the applications.

a) To create an app key, you need an explicit bundle ID and the team ID representing the Apple org. You can get the team ID from your Apple account membership page.
b) Generate a P8 file and provide this file when creating the app key.
c) Open Apple account, click Certificates, Identifiers & Profiles.
d) Then navigate to the All Keys page.
e) Click the Add (+) icon and select the APNS checkbox and proceed through the steps.
f) The Apple website generates a p8 file. For example, APNsAuthKey_XXXXXXXXXXX.p8, where the X's represent the App Key. You can find the file and the App Key on the App Key creation page.

P12 SSL certification
You enable mobile app messages when you create or edit an explicit app ID. Mobile app messages are not entirely enabled until client SSL certification is generated. A client SSL certificate allows your notification server to connect to the APNS. Each App ID is required to have its client SSL certificate.
To configure APNS, go to Apple account, and then follow these steps:

a) Go to Certificates, Identifiers & Profiles > Identifiers.
b) Locate the app ID that you want to use with the APNS. You can only use app IDs with a specific bundle ID with the APNS. You cannot use a wildcard app ID. A bundle ID is a specific identifier for a single app and must be unique to your app.
c) Click Edit next to the appropriate app ID.
d) Scroll down and select the Push Notifications check box.
e) Click Create Certificate for the type of SSL certificate you want to create. You can choose development or production.
f) Complete the guided steps to create the specific client SSL certificate for your app ID.
g) Download the client SSL certificate file and click Done.
h) Go to the folder where you downloaded the certificate file.
i) Double-click the file to install it in your keychain. The application creates an entry called Apple Development Push Services:<identifier>.
j) Expand to find the private key (your name or your corporate name) as a child beneath the push service.
k) Right-click and export the certificate and the private key in .p12 format. As part of the export, you must provide a password for this file.
l) You can verify your app ID settings on the app ID page. Check the development column or the distribution column depending on the client SSL certificate type. When the app ID is enabled, you will notice a green circle followed by Enabled in the push notifications row. A yellow circle followed by Configurable indicates a missing client SSL certificate.

4. Set up a new provisioning profile that is based on your new APN-enabled app ID. The profile is set up to receive test notifications. For information, see provisioning profiles.

   a) Go to Certificates, Identifiers & Profiles > Provisioning Profiles.
   b) Click the Add (+) icon.
   c) Select iOS App Development or Mac App Development as the distribution method.
   d) Select the app ID you want to use for development.
   e) Select one or more development certificates.
   f) Select one or more devices.
   g) Enter a profile name.
   h) Download the development or distribution provisioning profiles.
   i) You can now find the profiles in the Code Signing Identity for both your Target and Project settings.
   j) Select the correct profile for either Development or Distribution.
   k) Go to Build Settings > Code Signing Identity.
   l) Verify that the correct provisioning profile is selected for your bundle ID.

📘

Note:

The provisioning profile that you create must match the push certificate. For example, a development provisioning profile works with a development push certificate. Similarly, there are two production distribution profiles: ad hoc and App Store. These provisioning profiles work only with production push certificates. The provisioning profile is bundled with your app and includes the push entitlement. The push entitlement asks the user for permission to send mobile app messages when the app is opened.

Configure the sample app

1. Open the sample app.
   Swift – SampleCode_AcousticMobilePush_iOS_Swift/SwiftSample.xcworkspace
   Objective-C – SampleCode_AcousticMobilePush_iOS_ObjC/Sample.xcworkspace

2. Select the project on the XCode browser.

3. Configure the iOS App Target.
   a. Select the Sample in the Targets list.
   b. Select the General tab of the Target Editor.
   c. Update the Bundle Identifier to match an App ID and provisioning profile set up on Apple’s web portal.
   d. Select the team from the dropdown to enable Code Signing.

4. Configure the Notification Service Target.
   a. Select the Notification Service in the Targets list.
   b. Select the General tab of the Target Editor.
   c. Update the Bundle Identifier with .notification to match the App Target bundle identifier.
   d. Select the team from the dropdown to enable Code Signing.

5. Configure the Carousel Target.
   a) Select the Carousel in the Targets list.
   b) Select the General tab of the Target Editor.
   c) Update the Bundle Identifier with .carousel to match the App Target bundle identifier.
   d) Select the team from the dropdown to enable Code Signing.
   e) Select the Info tab of the Target Editor.
   f) Expand the NSExtension section and then expand the NSExtensionAttributes section.
   g) Update the UNNotificationExtensionCategory value to match the category for the carousel action.

Update the SDK configuration

1. Open the MceConfig.json file.
2. Swift requires your class to be in a namespace. For the Swift sample app, update the appDelegateClass value to SwiftSample.BaseAppDelegate.
3. Update the dev and prod entries in the appKey section to match the App Keys created in the web portal.

• The dev entry is used when you run the app from Xcode with a development provisioning profile. The prod entry is used when you run the app with an App Store, Enterprise, or AdHoc provisioning profile.
• If you do not have a production App Key, use apXXXXXXXX for the prod entry.

4. Update the baseUrl entry to match the server for your App Key. The baseURL was provided when your account was provisioned for mobile app messaging.
5. If you are not using Geofences or iBeacons, you can remove the location entry and all its children.
6. If you are using iBeacons, update the UUID in the iBeacon section of the location entry. The UUID should match the UUID for your iBeacons.

Build and run the sample app

You can now build and run the sample app and see the SDK in action.