iOS Push: Getting Started

Production vs Development Apps in Urban Airship

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

../_images/prod-vs-dev.png

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.

Set Up Your Application with 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.

If you are an iOS Developer, these are the required steps you must take in order to configure your app for push notifications. Once these basic steps are completed, your app will be ready to communicate with the Urban Airship Push service.

We use your Push SSL Certificate to communicate with Apple’s push notification servers. The private key resides securely on our servers, and Apple uses the public key to authenticate us on your behalf.

Finding Your Application

../_images/app-ids.png

In the Apple Developer Members Center, click on Identifiers under iOS Apps and locate your application in the list. 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.

../_images/creating-app.png

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

../_images/app-id.png

Click Settings to continue. (Note: 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 steps below.

Downloading Your Certificate

If you need to enable the Development or Production Push SSL Certificate, click Settings/(Edit) and choose which certificate to create:

../_images/config-cert.png

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

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

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

../_images/download-cert.png

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.

../_images/keychain-cert.png

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.

Exporting the .p12 file

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.

../_images/export-p12.png

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

../_images/export-filename.png

Uploading the push certificate to Urban Airship

Go to the your application in the Urban Airship dashboard, go to Settings, Services, and click the Configure button for Apple Push Notification Service.

../_images/db-edit.png ../_images/db-edit2.png

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

../_images/db-edit3.png

Select the file that was saved in step 2 of Exporting the .p12 file.

../_images/p12-upload.png

After uploading the file make sure to click Save.

Your push certificate is now uploaded and ready for use.

Setting up Urban Airship

Now that you’re all set up on the Apple end, it’s time to integrate Urban Airship into your iOS project. Below are the minimum steps required to configure your app(s) to talk to the Urban Airship service. We will take things from there, communicating with APNS on your behalf.

Once the Urban Airship pieces are in place, we will maintain two-way communication with Apple, sending notifications and other content on your behalf, and receiving and reporting user activity and engagement data back to you.

Download & Install Our Library & Frameworks

Download and unzip the latest version of libUAirship into the same directory as your project.

Required Libraries

The core library requires your application to link against the following Frameworks:

libUAirship-<version>.a
CFNetwork.framework
CoreGraphics.framework
Foundation.framework
MobileCoreServices.framework
Security.framework
SystemConfiguration.framework
UIKit.framework
libz.dylib
libsqlite3.dylib
CoreTelephony.framework
CoreLocation.framework
MessageUI.framework (only required for the sample UI)
AudioToolbox.framework (only required for the sample UI)
MapKit.framework (only required for the sample UI)

Create AirshipConfig.plist

The library uses a .plist configuration file named AirshipConfig.plist to manage your production and development application profiles.

  1. Create two applications within your Urban Airship account: One for development and one for production. For example:

    1. Name_of_your_app_dev
    2. Name_of_your_app_prod
  2. Create an AirshipConfig.plist file.

  3. Set the following values to the ones in your applications:

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
      <key>inProduction</key>
      <false/>
      <key>developmentAppKey</key>
      <string>Your Development App Key</string>
      <key>developmentAppSecret</key>
      <string>Your Development App Secret</string>
      <key>productionAppKey</key>
      <string>Your Production App Key</string>
      <key>productionAppSecret</key>
      <string>Your Production App Secret</string>
    </dict>
    </plist>
    
    ../_images/testpush2.png

    If you are using development builds and testing using the Apple sandbox set inProduction to false. For App Store and Ad-Hoc builds, set it to true. You may also allow the library to auto-detect the production mode by setting detectProvisioningMode to true.

Build Settings

Header search path - Ensure that your project’s header search path includes the Airship directory (recursive).

../_images/build-settings.png

Link against the static library. Add the libUAirship.a file to the “Link Binary With Libraries” section in the Build Phases tab for your target.

../_images/linkStepVersion5.png

Add “-ObjC” linker flag to “Other Linker Flags” to prevent “selector not recognized” runtime exceptions.

../_images/linkerFlags.png

Objective C Implementation

Import the required header files
At the top of your application delegate include any required headers:
#import "UAirship.h"
#import "UAConfig.h"
#import "UAPush.h"
Initialize UAirship Instance and Register for Remote Notifications
Inside your application delegate’s application:didFinishLaunchingWithOptions: method, initialize a shared UAirship instance by calling [UAirship takeOff] or [UAirship takeoff:config]. takeoff: must be called, and return, in this method, on the main thread.
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // Populate AirshipConfig.plist with your app's info from https://go.urbanairship.com
    // or set runtime properties here.
    UAConfig *config = [UAConfig defaultConfig];

    // You can also programmatically override the plist values:
    // config.developmentAppKey = @"YourKey";
    // etc.

    // Call takeOff (which creates the UAirship singleton)
    [UAirship takeOff:config];
}

Set the desired notification types on [UAPush shared]. Sounds, alerts and badges are the default types, but if you are using Newsstand or would like a custom set of types, you can set these immediately after [UAirship takeOff] is called. The library will register to receive these types of notifications as soon as push is enabled.

// Request a custom set of notification types
[UAPush shared].notificationTypes = (UIRemoteNotificationTypeBadge |
                                      UIRemoteNotificationTypeSound |
                                      UIRemoteNotificationTypeAlert |
                                      UIRemoteNotificationTypeNewsstandContentAvailability);

Push is enabled by default, but if you would like to defer the iOS push permission prompt, you can disable notifications by default. To do so, add the following after the call to [UAirship takeOff]:

[UAPush setDefaultPushEnabledValue:NO];

To enable push later on in your application:

// This will trigger the proper registration or de-registration code in the library.
[[UAPush shared] setPushEnabled:YES];

Register Your Device

  1. Once you have this implemented, run & compile your code.
  2. Add the application to your phone.
  3. When you open the app on your phone, it will ask for permission to send notifications. If you aren’t prompted to receive notifications, you should walk back through the steps on this page.

To make sure your device token is registered:

  1. Log in to go.urbanairship.com
  2. On the left-hand sidebar, navigate to Audience ==> Device Tokens
  3. If your device token registered properly, it will appear in the Device Tokens listing.

Send a Test Notification

There are as many ways of using our HTTP-based API as there are programmers, but let’s get started as quickly as we can. Here’s an example using curl, a command-line tool that comes with OS X:

curl -X POST -u "<application key>:<master secret>" \
   -H "Content-Type: application/json" \
   --data '{"device_tokens": ["<token>"], "aps": {"alert": "Hello!"}}' \
   https://go.urbanairship.com/api/push/

This does a few things:

  • It sets the HTTP Basic Authentication header with the application key as the user name, and the master secret for the password.
  • It sets the Content-Type header to application/json, to tell our server you’re sending JSON.
  • It sets the data you’re sending, including the device token as the recipient.

You should receive a 200 response code, with no data in the body. This means that we accepted your request, and are processing it and sending it on to Apple!

If it worked: Congratulations!

If it didn’t work

In the iOS Provisioning Portal, click on App IDs and locate your application in the list. Next to it are two settings for push notifications with yellow or green status icons:

  1. Log in to your Urban Airship account
  2. Check your error console

Your Error Console provides help to debug any issues you may have as you get started. There should be reasons why the notification wasn’t received.

If you used curl to send the notification, confirm that curl is working properly by using the echo endpoint:

curl https://go.urbanairship.com/api/echo/?msg=hello

If curl is set up properly, you should receive the following response:

{
   "msg": "hello"
}

If that fails, try a different testing tool, like HTTP Client.

If it succeeds, or if you get a different testing tool, try this to send a notification.

Check the error console in the Xcode Organizer; that can sometimes have useful information. Otherwise, go back through the process, paying close attention to:

The application ID, bundle ID, provisioning profile, and SSL certificate: All of these must point to the same identifier.

The device token: make sure you copied it correctly.

Apple, StoreKit and iPhone are trademarks of Apple, Inc. Maponics Neighborhood Boundaries © Maponics 2012. DMA® is a registered service mark of The Nielsen Company. Used under License.