APNs Setup

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

Production vs. Development Apps

When you create or edit an Urban Airship project (and thus its application record on our server), you must select whether your app system is “Development for sending test messages,” or “Production for sending messages to customers.” Apple treats the two servers separately, so a device token for development/sandbox will not work on production/distribution. Because of this, we suggest making two projects in the Urban Airship dashboard. That way you can continue to build and develop your application even after releasing it, without interrupting your users.

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

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 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 Urban Airship project first, and make sure your application code is pointing to the production project’s app key. For more tips on what to check before you release your app, see the iOS Production Launch Checklist.

Apple Steps

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 requires membership in the iOS Developer Program.

Get Your Certificate

  1. Log in to the Apple Developer Member Center, and navigate to Account » Certificates, IDs & Profiles, or use this direct link.

  2. In the left side menu, click App IDs in the Identifiers section.

    If you have not already registered an iOS App ID, click the + button and fill out the form, making sure to check the Push Notifications checkbox, and click the Continue button. Then you can skip to step 4.

  3. Click your app’s name from the list of App IDs. In the list of Application Services you will see two settings for Push Notifications, with yellow or green status icons. Click the Settings button to continue. The button will be labeled Edit if it has been configured previously.

    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 remaining steps in this section.

  4. Check the box to enable push notifications, then click the Create Certificate… button for either the Development or Production SSL Certificate. You should now see the Add iOS Certificate Assistant.

  5. Follow the instructions in the Add iOS Certificate Assistant, then click Continue.

    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.

  6. Click the Download button, and save the file for use in the remaining step.

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 as a .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. 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.
  2. 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.

  3. 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.

Urban Airship Steps

Configure the APNs Service

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”.

These steps require the certificate and password you generated in the previous section.

  1. Choose your project from the Urban Airship dashboard, click the Settings dropdown menu, then click Platforms.
  2. Click the Configure button for iOS, enter the Certificate password, then click the Choose File button and select the .p12 file exported in the completed Apple Steps.
  3. Click the Save button, or cancel to discard.

Your push certificate is now uploaded and ready for use.

For more information about configuring your project, as well as how to use the Urban Airship web application, see the Engage User Guide.

Next Steps

Configure the UA SDK

To send notifications, you must integrate the Urban Airship SDK into your Android application. See: iOS: SDK Installation.