This article describes how to get set up to send push notifications from Iterable to your iOS apps.
In this article
- Step 1: Enable push notifications in Xcode
- Step 2: Enable push notifications in the Apple Developer Portal
- Step 3: Create and download an auth token or certificate from Apple
- Step 4: Create or update an app in Iterable
- Step 5: Install and configure Iterable's iOS SDK
- Step 6: Send a test push notification
- Further reading
To get set up to send push notifications to your iOS app, follow these steps:
Step 1: Enable push notifications in Xcode
First, add the Push Notifications capability to your app's Xcode project. To do this, follow the steps in the "Enable the Push Notifications Capability" section of Apple's Registering Your App with APNs article.
Step 2: Enable push notifications in the Apple Developer Portal
Next, in the Apple Developer Portal, enable the Push Notifications capability for your App ID:
Sign in to the Apple Developer Portal.
In the left nav, click Certificates, IDs & Profiles.
On the Certificates, IDs & Profiles page, in the left nav, click Identifiers.
View your app's details by clicking its App ID.
On the Capabilities tab, scroll down and check the Push Notifications capability.
Save your changes.
Make sure to regenerate and reinstall your provisioning files after adding the Push Notifications capability to your App ID.
Step 3: Create and download an auth token or certificate from Apple
To send a push notification, Iterable has to communicate with Apple's Push Notification Service (APNs) on your behalf, telling it what message to send and where to send it. To authenticate with APNs, Apple provides token-based authentication (.p8 files) and certificate-based authentication (.p12 or PEM files).
We recommend using token-based authentication (.p8 files). This approach is easier to set up, auth tokens don't expire (so you don't need to worry about an expired certificate preventing you from sending push notifications), and push notifications can be sent at a faster rate.
Token-based authentication (.p8 file) — Recommended by Apple. With this approach, Iterable can use the same, non-expiring auth token to send push notifications to all of your apps (development and production). This is the fastest, most convenient, least error-prone way to authenticate with APNs. To set up token-based authentication:
Follow the instructions Apple provides in Establishing a Token-Based Connection to APNs.
Download the .p8 file. You'll upload it to Iterable in a later step.
Certificate-based authentication (.p12 file or PEM file) — With this approach, Iterable uses per-app, per-environment (development and production) certificates to send push notifications to your apps. These certificates expire each year, so you have to manually keep them up-to-date. To set up certificate-based authentication:
Follow the instructions Apple provides in Establishing a Certificate-Based Connection to APNs.
Download the certificate on your Mac. Then, install it in KeyChain Access by double-clicking it and choosing to install it in your login keychain.
Open Keychain Access and select the login keychain.
Select the certificate you just installed, and 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. You'll upload it to Iterable in a later step.
Step 4: Create or update an app in Iterable
Iterable uses mobile apps to store information about your mobile apps: their names, identifiers, platforms, store URLs, and push notification configuration—including authentication credentials needed to send push notifications.
To create or update a mobile app in Iterable, you'll need to sign in with an account whose role includes the Channel configuration > Setup & manage permission.
To create or update a mobile app in Iterable:
Navigate to Settings > Mobile apps.
If you've already created a mobile app in Iterable, open it up to view its details. Otherwise, create a new app by clicking Add a new mobile app, and fill in the various fields:
Name — The name of your app. For example,
My Test App.
- Platform — iOS
Bundle ID — Your app's bundle ID. For example,
- Store URL — Optional. Your app's App Store URL.
Then, click Create app. You'll be taken to the app's detail page:
- Name — The name of your app. For example,
Click Add new credential.
Depending on the type of credentials you generated in the previous section of this article, select .p8 Auth Key, .p12 Certificate, or PEM File:
Then, click Continue.
Upload and configure your credentials.
For .p8 auth tokens:
- Upload your .p8 file.
- Enter your Key ID, which you can find in the Apple Developer Portal (it's displayed on the page where you download the key, and when you click into the key details).
- Enter your Team ID, which you can find on the Membership tab of your account in the Apple Developer Portal.
- Enter your app's Bundle ID.
- Click Update.
When adding auth tokens (.p8 files) to your iOS mobile apps in Iterable, don't delete any certificates (.p12 files) that are already in use. Instead, add the .p8 files using the Upload & Replace option found in the overflow menu for the existing push integration. This will prevent any interruption in Iterable's ability to send push notifications to your users (and everything will just keep working when your existing certificates expire, too).
For .p12 certificates:
- Upload your .p12 file.
- Enter the password for the certificate.
- Select an environment (production or sandbox).
- Click Update.
For PEM files:
A PEM file is another representation of the same information found in a .p12 file.
- Paste in the text for your certificate.
- Paste in the text for your RSA private key.
- Choose an environment (production or sandbox).
- Click Update.
Step 5: Install and configure Iterable's iOS SDK
Iterable's iOS SDK simplifies the process of working with push notifications in your iOS apps. To learn how to install and configure this SDK, read Iterable's iOS SDK.
Don't use the SDK? You don't have to use Iterable's iOS SDK to receive push notifications from Iterable. If you'd like, you can work with our API instead:
POST /api/users/registerDeviceTokeneach time the app opens, to save the device's push token to Itearble.
POST /api/users/disableDeviceeach time a user signs out of the app, to prevent further push notifications from being sent to that user.
POST /api/events/trackPushOpento track push notification opens.
Step 6: Send a test push notification
Now, send a test push notification:
In Iterable, navigate to Audience > Contact Lookup. Enter the user's email address and pull up their Iterable user profile.
devicesarray on their profile, and use the
appPackageNamefield to find the object that corresponds to your app.
tokenfield from this object. You'll use this value to send your test push notification.
Navigate to Settings > Mobile Apps. Click the mobile app to which you'd like to send a test push notification.
In the Push Credentials section, click Test Push. This will bring up the Send Test Push window, where you can enter:
- Device token — The token you found above, which determines the destination app and recipient for your test push message.
- Message — A test message to send.
On your mobile device, make sure the iOS app is not in the foreground (by default, iOS apps do not display their own push notifications when they're in the foreground).
Click Send notification.
The push notification should arrive on the device.
To learn more about sending iOS push notifications from Iterable, read: