Setting up iOS Push Notifications

Iterable campaigns can send iOS push notifications. Push notifications are remotely triggered notifications that appear on a user's device even when the application is closed (depending on whether or not the user allows them). Users can then tap on these notifications to open the associated application to specific, relevant content.

This is a technical guide that describes various one-time configuration and implementation steps to complete before sending iOS push notifications from Iterable campaigns. It is targeted at engineers who build iOS apps.

If you are a marketer, work with your mobile engineers to implement the steps discussed in this article. If you have already completed the technical setup, learn more about setting up a push notification campaign by reading Sending Push Notifications.

# Table of contents

# Overview

To use Iterable to send push notifications to an iOS app, the following things must happen:

• You must configure your app to receive push notifications.
• Your users must install your mobile app and, when asked, give it permission to receive push notifications.
• Your mobile app must store a unique token from Apple on the user's Iterable profile.
• Iterable must contact Apple's Push Notification service (APNs), telling it what push notification content to send and which devices to send it to.

The Iterable iOS SDK automatically tracks push notification opens, or you can use Iterable's API to do so.

# Instructions

Follow the steps below to configure Iterable to send iOS push notifications:

# 1. Configure your App ID and create an SSL certificate

For Iterable to send iOS push notifications, you must first configure the appropriate App ID in the Apple Developer Portal and create an SSL certificate for Iterable to use when authenticating with APNs.

Iterable will communicate with APNs on your behalf to send push notifications. To do this, it must authenticate with APNs using your SSL certificate, which you'll need to create and upload to Iterable.

Use a Mac to follow these steps, since they rely on the Keychain Access app installed as part of macOS:

• Log in to the Apple Developer Portal.
• Navigate to Certificates, IDs & Profiles > Identifiers > App IDs and click the App ID associated with your app.
• On the screen for your App ID, check Capabilities > Push Notifications.
• Click Save and respond to the Modify App Capabilities dialog box that appears.
• To create the certificate Iterable will use to communicate with Apple when sending push notifications:
  • In a new browser tab, follow Apple's Create a certificate signing request instructions.
  • In the Apple Developer Portal, navigate back to your App ID.
  • Click Capabilities > Push Notifications > Configure.
  • Click one of the following buttons:
    • Development SSL Certificate > Create Certificate (for testing push notifications while developing an iOS app)
    • Production SSL Certificate > Create Certificate (for sending push notifications in production)
  • Click Choose File and select the certificate signing request you created above.
  • Click Continue.
  • Click Download to download the certificate.
  • Use this file to export a .p12 file in the next step.

# 2. Export the certificate in a format Iterable can use

Next, export the downloaded certificate (.cer file) as a .p12 file that can be uploaded to Iterable:

• On your Mac, double-click the .cer file to open it in Keychain Access.
• In Keychain Access, in the lower-left corner, select Category > Certificates.
• Select the certificate to export.
• Choose File > Export Items.
• Enter a name in the Save As field.
• Accept the default .p12 file format and click Save. Respond to the prompts, and enter a password for the file if necessary.
• Keep track of this file, since you'll upload it to Iterable in a later step.

# 3. Add the Push Notifications capability to your Xcode project

To configure your Xcode project to include the Push Notifications capability:

• In Xcode, open the project associated with your mobile app.
• In the Project Navigator (the left-hand menu), select the project icon that represents your mobile app.
• In the top-left corner of the right-hand pane in Xcode, select your app's target.
• Navigate to the Capabilities tab.
• Enable Push Notifications.

# 4. Create a mobile app in Iterable

Iterable uses mobile apps to store the details about your app's name, identifier, platform, store URL, and push integrations.

To create a mobile app in Iterable:

• Navigate to Settings > Mobile Apps.
• Click Add a New Mobile App to bring up the Create New Mobile App form:
• For Name, enter the name of your app.
  • For example, Iterable Docs Push.
• For Platform, select iOS.
• For Bundle ID, enter your app's bundle ID.
  • For example, com.iterable.docspush.
• (Optional) For Store URL, enter your app's App Store URL.
• Click Create App. This brings up a screen showing the app's details:

# 5. Assign a push integration to the mobile app

A push integration stores the certificates or API key necessary to send a push notification. A push integration is stored as part of a mobile app. You can either associate an existing push integration or a new push integration with a mobile app.

# Existing push integration

To associate an already-existing push integration with the newly created mobile app:

• Navigate to Settings > Mobile Apps.

• Find the existing push integration in the Unassigned Integrations interface at the bottom of the screen.

  

• Click that push integration's Assign App button.

• In the Assign Push Integration window, select the mobile app you just created.

  

• Click Assign.

# New push integration

To create a new push integration for the mobile app:

• With the new mobile app still open in Iterable, click the Configure button next to Apple (for production) or Apple Sandbox (for development), bringing up a window similar to the following:

  

• Click Choose File and select the .p12 file created above.

• If your .p12 file has a password, enter it in the Password field.

• Click Update to create the push integration.

# 6. Install Iterable's iOS SDK in your mobile app

To install Iterable's iOS SDK, use a dependency manager or perform a manual installation.

# 7. Configure the Iterable SDK

Read Configuring the SDK on GitHub to learn how to configure the Iterable iOS SDK in your mobile app.

# 8. Use Iterable to send a test iOS push notification

To send a test iOS push notification, first look up the device token for a test user who has installed and run the app:

• In Iterable, navigate to Audience > Contact Lookup and enter the user's email address.
• In the devices array, examine the appPackageName field to find the object that corresponds to your app.
• Copy the token, since you'll need this to send the test push notification.

Then, send a test push notification to that user:

• Navigate to Settings > Mobile Apps.
• Click the mobile app for which you'd like to send a push notification.
• In the Integrations section, click Test Push to bring up the Send Test Push window:
• For Device Token, enter the token you located above.
• For Message, enter a message to display in the push notification.
• On your mobile device, make sure the iOS app is not in the foreground, since displaying push notifications while an iOS app is in the foreground requires custom code.
• Click Send Notification.
• Monitor the recipient's device to verify that the push notification arrives.

# Customizing iOS push notifications

The following sections describe the technical setup necessary for various iOS push notification customizations in Iterable.

For marketer-specific information about how to configure these features in Iterable when sending a campaign, read Sending Push Notifications.

# Adding sounds to iOS push notifications

To add sound to iOS push notifications, follow these instructions:

• Place the necessary sound files in the iOS project's Library/Sound folder, or in the top-level directory of the Xcode project.

  NOTE

  See Apple's UNNotificationSound documentation for a list of supported sound formats.

• When creating a push notification template in Iterable, put the name of the sound file in the Sound field:

  

  NOTES

  • To use the default push notification sound, set this field to default.
  • Whether or not a device plays the sound or vibrates depends on the user's device settings.

# Adding deep links to iOS push notifications

Iterable push notification templates make it possible to set deep link URLs for iOS and Android.

To learn more about using Iterable's iOS SDK to handle deep links, take a look at the Iterable iOS SDK documentation on GitHub.

If your app is not using Iterable's iOS SDK, it can still handle a deep link contained in an Iterable push notification. Iterable provides the deep link URL in the defaultAction object included in the notification's payload. When this object's type field is set to openUrl, the data field will contain the deep link URL.

When using the SDK, code executing after an app has opened in response to a user's interaction with a push notification can use IterableApi.lastPushPayload to access the push notification's payload.

# Add media attachments to iOS push notifications

To add media attachments to display as part of an iOS push notification, you'll need to add a Configuring a Mobile App for Rich Push Notifications to your application.

# Troubleshooting

If you have trouble registering for push notifications in iOS 10 or later, read iOS 10 debugging: push notifications not registering for more information.

# Further reading

For more information about push notifications in Iterable, read:

• Push Notification Setup FAQ.
• Sending Push Notifications
• iOS 10 Debugging: Push Notifications Not Registering
• Iterable iOS SDK docs
• Apple's UserNotifications framework documentation
• Setting up Android Push Notifications.