APNS Setup

Apple Push Notification Service (APNs) is the transport method that Urban Airship supports for iOS notifications.

Production vs Development Apps in Urban Airship

When you create or edit an application record on our server, you must select whether your app system is “In development, connecting to test servers,” or “In production, connecting to real push servers.” Apple treats the two servers separately, so a device token for development/sandbox will not work on production/distribution.

When building your app using a development provisioning profile, set your Urban Airship application to In development, and upload the development Push 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 an application that is In production, and upload the production Push SSL certificate.

Because Apple treats development and production/distribution as completely separate instances, we suggest making two applications in the Urban Airship web interface. That way you can continue to build and develop your application even after releasing it without interrupting your users.

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 Urban Airship app key that is set as In Development. Development apps use different tokens that, when included in a push to a production app, will fail and in many cases cause all other pushes to fail.

Always create a Production Status Urban Airship app first and make sure your application code is pointing to the production app key. For more tips on what to check before you release your app, see the iOS Production Launch Checklist.

Get Your Certificate from Apple

Before you can integrate Urban Airship into your iOS apps, there are a handful of steps you must take on the Apple end of things, which require membership in the iOS Developer Program.

You will complete the following steps in the Apple Developer Member Center before your app is ready to communicate with Urban Airship:

Find Your Application

In the Apple Developer Members Center, click on App IDs in the Identifiers section of the Certificates, Identifiers & Profiles menu pane.

If you haven’t registered an App ID yet, click the + symbol and fill out the form, making sure to check the Push Notifications checkbox.

When you expand the application, you will see two settings for push notifications with yellow or green status icons:

Click Settings or Edit to continue.

The Settings button may be titled Edit if push notifications have been previously configured. If the Settings/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 remainder of the steps in this section.

Generate Your Certificate

  1. Choose either the Development or Production certificate option and click Create Certificate.

  2. After clicking Create Certificate, you will see the Add iOS Certificate Assistant. Follow the instructions in the assistant and then click Continue.

  3. Using the Certificate Signing request that was just created, generate the APNS Push SSL certificate.

  4. Once the Download button appears, you are ready to download. You may need to reload the page for this to update. Download the newly created certificate:

  5. Open the certificate. Opening the certificate will open Keychain Access. In Keychain Access your certificate should be shown under “My Certificates”. If not, check “Certificates” to see if it’s located there.

Renewing Your Certificate

If you are renewing either your Development or Production 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.

Export the .p12 File

You’re almost there. The final step before heading back over to the Urban Airship application is to save your signing certificate as a .p12 file.

  1. Select the certificate that was just added to Keychain Access and select File -> Export Items… from the menu. 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.

  2. When saving the file, use the Personal Information Exchange (.p12) format.

Configure APNS with Urban Airship

Never use the same push certificate across multiple Urban 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: “com.yourcompany.app.adhoc”.

  1. Find your app in the Urban Airship web application and in the settings drop down menu click Services.

  2. From the list of available services to configure, navigate to Apple Push Notification Service (APNs) and click Configure.

  3. If your certificate has a password, enter it here. Then, click the Choose File button.

  4. Select the file that was saved in step 2 of Export the .p12 File.

  5. After uploading the file, make sure to click Save.

Your push certificate is now uploaded and ready for use.