Push Notifications for iOS

There are 3 stages to complete in order to setup Push Notifications with Sailthru Mobile:

  1. Enable Push Notifications on your App ID
  2. Generate push certificates and upload to Sailthru Mobile
  3. Create a push-enabled provisioning profile for distribution

Step 1: Enable Push Notification on your App ID

Each iOS application that uses the APNS must have a unique application ID.

To get started, sign into the iOS Developer Program and click on Certificates, IDs & Profiles.


Create or reuse an App ID

You need to create a new App ID or to reuse one you previously created.

If you are reusing an existing App ID, you can skip this section and just make sure it's enabled for Push Notifications.

If you are creating a new App ID, click on App IDs under Identifiers.


Click on the Add button (the plus icon) on the right hand side of the page.


In the App ID Description section, specify a name for your app. In the App ID Suffix, make sure Explicit App ID is selected, then specify a Bundle ID.

In the App Services section, make sure to enable Push Notifications, then click Continue.

In the confirmation screen, make sure that Push Notification appear as Configurable, then click Register.


Click Done, then click on your app name in the App IDs list and click Edit. In the screen that appears, scroll to Push Notification and create a certificate for both Development and Production. To do so, click Create Certificate in the relevant section and follow the steps that appear. Once you're done, make sure you import your certificates into your keychain on your Mac by opening the .cer files you generated. When asked, make sure to save them into the Login keychain.

You should have two certificates: Development (Apple Development iOS Push Services) and Production (Apple Push Services). You will need to update these two certificates to Sailthru Mobile later in the process.

Check push notifications are enabled for your App ID

Click on your app name in the App IDs, then click Edit. Make sure that your Push Notification section looks like this:


Interface for enabling Push Notifications for an App ID

Open Xcode on your Mac. Select your project and your target. Under Capabilities, make sure the switch for Push Notifications is enabled.


Enable this setting in your target's capability settings.


If you migrated your project from a previous version of Xcode, please disable the Push Notification switch, then enabled it again. This will force Xcode to update the entitlements file. Previous versions of Xcode did not record entitlements correctly in certain cases, and this step will force Xcode to write it again.

Step 2: Export and upload Push certificates to Sailthru Mobile

On your Mac, open Keychain Access and find the development and production push certificates generated in the first step.

Select the certificate named Apple Development IOS Push Services (your.bundle.id). Right click on the item and select Export "Apple Development IOS Push Services (your.bundle.id)". Save each certificate in p12 format onto your Mac with no password.

Repeat these steps for the certificate named Apple Push Services: (your.bundle.ID).


Exporting push notification certificates from Keychain Access.

Upload your certificates to Sailthru Mobile

Sailthru Mobile needs your push certificates in order to send push notifications to your app.

Log into Sailthru Mobile, then navigate to Settings -> Developer.

In the iOS section, drag and drop your Development certificate into the Apple Push Certificate (Development) box. Your Production Certificate goes into the Apple Push Certificate (Production) section.


The Sailthru Mobile certificate upload section. Upload both your certificates here.


We accept a "Production or Sandbox" certificate in both boxes, but a "Sandbox Only" certificate will only be accepted into the Apple Push Certificate (Development) box.

Step 3: Create a push-enabled provisioning profile for distribution

The next step is to create a provisioning profile so that your application can be installed onto a real device for testing push notifications.

If you haven't already done so, sign into the iOS Developer Program and click on Certificates, IDs & Profiles. In the Certificate section, choose All.


Create a new certificate by clicking the Add sign in the right hand side of the page. In the next screen, choose App Store and Ad Hoc. If you plan on shipping the App to the App Store, like any production testing, you will first need to use an Ad Hoc build to test release mode.

Click Continue, then follow the instructions on the page.

When done, head over to Provisioning Profiles, then click Distribution. If you are testing, select Ad Hoc. If you are distributing your app to the public, select App Store. Follow the instructions to download the provisioning profile.


When creating a new profile ensure that you reference the App ID setup earlier.
For existing provisioning profiles, you will need to re-generate the profile in order to support push notifications.

The latest Xcode can automatically manage signing for you. However, you can still retain control over your profiles and certificates by doing the following:

  1. From your Apple Developer Portal, head over to Provisioning Profiles, then click Distribution
  2. Download the .mobileprovision profile you created before to import it into Xcode.
  3. In Xcode, select your project file, then click General. Deselect Automatically manage signing
  4. In the Signing (Debug) section, select your debug or development provisioning profile
  5. In the Signing (Release) section, select your development provisioning profile you created in the previous step.


App Store and Distribution provisioning profiles

After you have enabled and tested push notifications, you will need to generate a new provisioning profile. Failing to do so prior to releasing the App Store will mean that Push Notifications will not work with your application.

More information is available in the iOS Release Checklist.

Confirming Push Setup

Step 1. Confirm development devices are receiving device tokens

  1. Launch your app on your iOS device, ensuring that you have built your app using a development provisioning profile with push enabled.
  2. Log in to Sailthru Mobile, click on your app, settings and then click on the Developer tab where you should see your device listed.
  3. This device log also shows whether push notifications are enabled. If you do not see a push enabled device, review this troubleshooting guide which works through common integration issues.

Viewing the device logs in Sailthru Mobile. This may take a few moments.

Step 2. Confirm production devices are receiving device tokens

  1. In Xcode, edit your scheme from Product -> Scheme -> Edit Scheme and put your build into release mode.
  2. Repeat the same steps as above. You should see your device token change as it receives a production gateway token from APNS.

Click the target, click edit scheme. Change "Build Configuration" from "Debug" to "Release" and uncheck "Debug executable"

Step 3. Sending Test Pushes

All registered devices can either be in production (i.e. built against a production provisioning profile) or development (i.e. built against a development provisioning profile).

The next step is to setup in-app messaging in your app.