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
-
Instructions
- 1. Configure your App ID and create an SSL certificate
- 2. Export the certificate in a format Iterable can use
- 3. Add the Push Notifications capability to your Xcode project
- 4. Create a mobile app in Iterable
- 5. Assign a push integration to the mobile app
- 6. Install and configure Iterable's iOS SDK in your iOS app
- 7. Use Iterable to send a test iOS push notification
- Next steps
- Troubleshooting
- Customizing iOS push notifications
- Further reading
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.
NOTES
Iterable's iOS SDK automatically tracks push notification opens. You can also use Iterable's API to do so.
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.
NOTE
APNs (Apple's Push Notification service) currently supports two types of connections: token-based (.p8) and certificate-based (.p12). Iterable’s APNs push integration uses the certificate-based (.p12) method.
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.
NOTE
After adding the Push Notifications service to an App ID, you must re-generate and download the app's provisioning profiles to the machine you to build the app.
- Navigate in the Apple Developer Portal to Certificates, IDs & Profiles > Provisioning Profiles.
- Click the provisioning profile you'd like to edit.
- Edit the provisioning profile as necessary, and click Save.
- Click Download, and double-click the downloaded provisioning profile to install it.
- Make sure your Xcode project is configured to use the provisioning profile as necessary.
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.
WARNING
If you haven't regenerated and reinstalled your provisioning files since adding the Push Notifications service to your App ID, Xcode will show an error when you attempt to add the Push Notifications capability. For more information, see above.
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.
TIPS
- It's best to use separate Iterable projects for sandbox and production data.
- An Iterable push notification campaign can target as many (or few) of your mobile apps as necessary.
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 example,
- For Platform, select iOS.
- For Bundle ID, enter your app's bundle ID.
- For example,
com.iterable.docspush
.
- For example,
- (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.
TIP
- It may take a few minutes for the certificates to be registered for our sending to enable the Test Push notification
- It's best to use separate Iterable projects for sandbox and production data.
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 and configure Iterable's iOS SDK in your iOS app
To learn how to install and configure Iterable's iOS SDK, read Iterable's iOS SDK.
NOTE
You can receive Iterable push notifications without setting up the Iterable iOS SDK. To do so, you'll need to call Iterable's API:
- Call
POST /api/users/registerDeviceToken
each time the app opens. - Call
POST /api/users/disableDevice
each time the user signs out of the app. - Track push notification opens by calling
POST /api/events/trackPushOpen
.
7. 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 theappPackageName
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.
- To use the default push notification sound, set this field to
Adding deep links to iOS push notifications
WARNING
By default, iOS apps can open HTTPS URLs, but not HTTP. Because of this, you should use HTTPS whenever possible. However, it is possible to configure your iOS apps to work with HTTP URLs by configuring App Transport Security exceptions in Xcode.
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, read Deep Links in Push Notifications.
If your app is not using Iterable's iOS SDK, it can still push notification deep
links. 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:
Comments
0 comments
Please sign in to leave a comment.