Setting up iOS Push Notifications

This section will walk through a complete iOS push notification setup. At the end of this article, you should have the ability to send live campaigns to your iOS users through Iterable.

# 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 (see Registering Your App with APNs).
• Your users must install your mobile app and, when asked, give it permission to receive push notifications (see Asking Permission to Use Notifications).
• Your mobile app must store a unique token from Apple on the user's Iterable profile (see "Register Your App and Retrieve Your App's Device Token" in Registering Your App with APNs).
• Iterable must contact Apple's Push Notification service (APNs), telling it what push notification content to send and which devices to send it to.

# Instructions

# 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

You will want to send the token to Iterable. Add this function your didReceiveRemoteNotification method as shown below:

// MARK: Silent Push for in-app
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    IterableAppIntegration.application(application, didReceiveRemoteNotification: userInfo, fetchCompletionHandler: completionHandler)
}

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

# Next steps

If your app received the push notification, proceed to the next step.

# Troubleshooting

If you have trouble registering for push notifications in iOS 10 or later, read Push Notification Testing and Troubleshooting.

You may also want to:

• Try re-exporting the .p12 certificates (from beginning to end) and re-upload to Iterable. Occasionally, Apple requires you to do it again.
• Ensure you have correct API key for you project.
• Ensure you exported the Sandbox certificate if you are testing with Xcode.
• Ensure you exported the Product certificate if you are testing with TestFlight.

# 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 Creating a Push Notification Campaign.

# 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 images, videos, or sounds to an iOS push notification, you'll need to add a Notification Service Extension to your app. For more information, read Advanced iOS Push Notifications.

# Further reading

For more information about push notifications in Iterable, read:

• Frequently Asked Questions
• Creating a Push Notification Campaign
• Push Notification Testing and Troubleshooting
• Iterable iOS SDK docs
• Apple's UserNotifications framework documentation
• Setting up Android Push Notifications.