Before you can integrate Airship into your iOS apps, there are a handful of steps you must take on the Apple end of things, which requires membership in the iOS Developer Program.
We will be using the Apple Push Notification Service (APNs) as the transport method for iOS push notifications. In the next section we will configure a development app and a production app for push services.
Production vs. Development Apps
When you create or edit an Airship project (and thus its application
record on our server), you must select whether your app system is Test
(development for sending test messages), or Live (production for sending
messages to customers). Apple treats the two servers separately, so a
device token for
test/sandbox will not work on
live/production. Because of this, we suggest making two projects
in the Airship dashboard. That way you can continue to build and develop
your application even after releasing it, without interrupting your users.
Apple provides two primary types of SSL certificates: The APNs Development iOS certificate and the
Apple Push Notification service SSL (Sandbox & Production) certificate. The Sandbox & Production certificate can be
used on both
live/production apps, while the APNs Development iOS certificate may only
be used with
test/sandbox iOS apps.
When building your app using a development provisioning profile, set your Airship project to Test, and upload an APNs Development iOS or Apple Push Services SSL certificate. To push to an app built with a distribution provisioning profile (either with a release build in Xcode, ad hoc distribution, or the iTunes App Store), use a project that is designated as Live, and upload an Apple Push Services SSL certificate.
To support Catalyst apps in Xcode 11+, it’s necessary that your app be built with a provisioning profile that includes
an Apple Developer certificate (for use in Xcode 11 or later) and the
Mac capability listed under Enabled Capabilities:
Do not a) submit to the App Store or b) test notifications on an ad hoc build while your app’s code is pointing to an Airship app key that is set as Test. Test apps use different tokens that, when included in a push to a Live app, will fail and in many cases cause all other pushes to fail.
Always create a Live Airship project first, and make sure your application code is pointing to the live project’s app key. For more tips on what to check before you release your app, see the iOS Production Launch Checklist.
Get Your Certificate
In the left side menu, click Identifiers, then click your app’s name in the list of App IDs.
If you have not already registered an iOS App ID, click +, select App IDs, and click Continue:
Fill out the Register an App ID form, making sure to check the Push Notifications checkbox, then click Continue and Register.
Click your app’s name in the list of App IDs, and skip to step 4 below.
In the list of Capabilities check the box for Push Notifications, then click Configure to continue to the Apple Push Notification service SSL Certificates section. The button will be labeled Edit if it has been configured previously.
If the Configure/Edit button is not available, you may not be the team agent or an admin. The person who originally created the developer account is your team agent, and they will have to carry out the remaining steps in this section.
Click Create Certificate to create a Production SSL Certificate. This will generate an Apple Push Notification service SSL (Sandbox & Production) certificate compatible with both the Production and Development environments.
You should now see the Create New Certificate section to generate an Apple Push Notification service SSL (Sandbox & Production) certificate:
Follow the instructions to create a certificate signing request in the Create New Certificate section, then click Continue after your certificate signing request is uploaded.
You can now use the newly-created Certificate Signing request to generate the APNs Push SSL certificate. The next step requires the Download button to be active. You may need to reload the page if it is not yet active.
Click Download and save the file for use in the next step, Exporting your .p12 file.
Renewing Your Certificate
If you are renewing either your Test or Live Push SSL Certificate, follow the steps outlined above as if you were uploading the certificate for the first time. There is no need to revoke the previous certificate in order to make this change. There may be two production certificates at the same time, to allow you to continue using the old certificate while uploading the new one.
Send a test message to make sure that you’ve uploaded the correct, renewed certificate. If you upload the wrong certificate (a certificate not associated with your app and audience) and send a message, Apple will report that your audience is not related to your app, forcing Airship to remove those members of your audience. The Airship error console reports a
Rejected Device Token error for each member of your audience when your certificate does not match your app.
Export as a .p12 File
You’re almost there. The final step before heading back over to the Airship application is to save your signing certificate as a .p12 file.
Open the certificate you downloaded in the previous steps, which should open in the Keychain Access app. The certificate should be listed in My Certificates.
Click the certificate in the list, then from the File menu, select Export Items….
Be sure to select My Certificates under the Category menu on the lower left-hand side. If My Certificates is not highlighted, you will not be able to export the certificate as a .p12 file.
Save the file in the Personal Information Exchange (.p12) format.You will be prompted to create a certificate password. Use this password in the next step: Configure the APNs Service.
Configure your iOS project for push notifications in the Airship dashboard.
Configure the APNs Service
Never use the same push certificate across multiple Airship app keys. You should also never use the same bundle ID across multiple app keys in the same environment (development or production).
Not following these instructions can result in rejected device tokens and APNs feedback processed by the wrong app key. If you need to have a third app key for ad hoc builds (which also use Distribution-type push certificates), the bundle ID should be changed so you can use a different certificate, for example:
You will need the certificate .p12 file and password you generated in the previous section.
- Go to Settings » Channels » Mobile App and click Add for iOS.
- Select Certificate-based authentication, then enter the certificate password and upload the .p12 file.
- Click Add iOS.
Your push certificate is now uploaded and ready for use.