Using the Push Notifications native extension for iOS

Push notifications are a powerful feature for engaging users in mobile apps, enabling you to share news and updates, bring lapsed users back to your app, and even update the state of an app remotely.

Setting up push notifications can be a complicated affair, but with the EasyPush Notifications native extension for iOS, you can implement push simply and efficiently:

• Handle the server side of notifications with Urban Airship (the biggest, most reliable provider of push services) with simple setup and one million free messages per month
• Activate basic push notifications in your Adobe AIR app with just three lines of ActionScript 3 code
• Automatically display native UI popups for notifications–or design your own
• Implement custom events or design your own message format
• Jumpstart development with a complete sample application, ActionScript 3 documentation, and an illustrated guide for every step of the iOS Provisioning Portal setup process

Before you can use push notifications on iOS, you'll need to create a new App ID specifically for your push-enabled app, create a special provisioning profile for your app, and set up a back-end certificate for the server.

Create a new App ID

1. Log in to https://developer.apple.com and select iOS Dev Center.
2. In the right-hand column, select iOS Provisioning Portal.
3. Click App IDs and then click New App ID.
4. Type a description for your App ID. This will be used to easily identify the app within the Provisioning Portal, but won't be shown to users. For Bundle Seed ID, select Use Team ID. For Bundle Identifier, type an ID for your app, such as com.yourcompany.pushapp (Figure 1). Take note of this ID as you will have to use later in your AIR application descriptor file.

5. Click Submit.

Note: When you create your app in iTunes Connect before publishing to the App Store, be sure to choose this App ID so push notifications will be enabled for production.

6. Back on the App IDs list, scroll down and locate the ID you just created. Click Configure (see Figure 2).

Enable push and generate certificates

Push notifications require a special SSL certificate that allows a back-end server to manage notifications for your app. There are separate certificates for development and production. You can use these certificates with a service provider such as Urban Airship so you won't have to run your own servers.

8. Click Enable For Apple Push Notification Service.
9. Click the Configure button next to Development Push SSL Certificate (see Figure 3).

The Apple Push Notification service SSL Certificate Assistant will appear to help you generate a Certificate Signing Request (see Figure 4). You have already gone through this process when you began development to generate your Adobe AIR signing certificates; you'll need to repeat it now to generate the new Push SSL certificates.

7. Follow the on-screen instructions to create the signing request. If you need to generate your signing request from Windows, you can follow the instructions for generating a certificate signing request provided by Adobe . Be sure to give your request a logical name in the name field, such as "MyGame Development Push".
8. Click Continue, and select the Certificate Signing Request File you just created on your computer. Upload it to Apple and click Generate. A new Certificate file will be generated. Download it to your computer.
9. On iOS double-click the file to install it in the Keychain Access tool. Select My Certificates and locate the new certificate; its name should be similar to "Apple Development iOS Push Services: __YOURNEWNAMEHERE__". Right-click the new certificate and select Export. Export the file as a .p12 with an appropriate file name, such as MyGameDevPushCert.p12.
10. On Windows, refer to the instructions for converting a developer certificate into a P12 file provided by Adobe.

You'll need to repeat this process later to generate a Production SSL certificate before publishing your app to the App Store.

Create a new provisioning profile

When using push notifications, Apple requires you to generate a separate provisioning (.mobileprovision) file for each application you want to create. Be sure you've completed the steps above and waited a few minutes before creating your provisioning profile.

1. In the Provisioning Portal, click Provisioning in the left column.
2. Click New Profile on the top-right.
3. On the Development tab, type an appropriate Profile Name; for example, "MyPushGame Dev Provision". Click the checkbox next to Certificates. For the App ID, select the new App ID you created earlier (see Figure 5). Select any test devices you want to enable for this profile. Click Submit. After the profile becomes active, download the new .mobileprovision file on your computer. Be sure to give it an appropriate name so you can recall that is the development provisioning file for your particular push-enabled game.

You'll need to repeat these steps to create a Distribution Provisioning Profile, using your production SSL key, when you're ready to submit the app to the App Store.

The EasyPush Notifications native extension is designed so that it can be quickly and easily integrated with Urban Airship, a popular provider of back-end services for managing, distributing, and testing push notifications, that offers both free and affordable plans.

1. Sign up for Urban Airship at http://www.urbanairship.com . Signing up and testing are free. Sending up to one million messages per month is also free.
2. On the main page, click Manage Your Applications. If you have not created any applications yet, you'll be taken directly to the page to add a new application.
3. Type a name, upload an icon, and select a category for your app.
4. Select Push Notifications Support.
5. Click Choose File next to Apple Push Certificate, and navigate to the Development SSL certificate you generated earlier. For Certificate Password, type the password you used when exporting the certificate (see Figure 6).

6. Click Create Your App.
7. Take note of your Application Key and Application Secret (see Figure 7). You'll need both these values later to set up Urban Airship with ActionScript 3.

The EasyPush Notifications native extension requires the AIR 3.3 SDK or a later version. You can download the latest AIR SDK from http://www.adobe.com/special/products/air/sdk/. If you haven't already installed the AIR 3.3 SDK for your Flash Professional CS6 or Flash Builder IDE, follow the instructions below.

Enabling the AIR 3.3 SDK in Flash Professional CS6

1. Unzip the AIR 3.3 SDK package on your hard drive.
2. Launch Flash Professional CS6.
3. Choose Help > Manage AIR SDK.
4. Click the Plus (+) Button and navigate to the location of the unzipped AIR SDK.
5. Click OK.
6. Choose File > Publish Settings.
7. Select the AIR 3.3 SDK for iOS as the Target.

Enabling the AIR 3.3 SDK in Flash Builder 4.6 on Windows

1. Unzip the AIR 3.3 SDK package on your hard drive.
2. Close Flash Builder.
3. Locate the Flash Builder SDK directory. On Windows, this is typically c:\Program Files\Adobe\Adobe Flash Builder 4.6\sdks.
4. Make a copy of the current Flex SDK directory, and give it a descriptive name. For instance, copy the 4.6.0 SDK folder inside /sdks and name the copy 4.6.0_AIR33.
5. Copy and paste the contents of the AIR 3.3 SDK into the 4.6.0_AIR33 directory. Accept all changes.
6. Edit the flex-sdk-description.xml file inside the new directory, and change the value of the <name> tag to Flex 4.6.0 (AIR 3.3) .
7. Open Flash Builder and choose Project > Properties > Flex Compiler > Configure Flex SDKs.
8. Click Add and navigate to the new folder location.

Enabling the AIR 3.3 SDK in Flash Builder 4.6 on OS X

1. Copy the contents AIR 3.3 SDK package to your hard drive.
2. Close Flash Builder.
3. Locate the Flash Builder SDK directory. On iOS, it is typically /Applications/Adobe Flash Builder 4.6/sdks/.
4. Create a new folder inside the /Flash Builder 4.6/sdks/ folder named AIR33SDK and copy the contents of the AIR3.3 SDK package that you downloaded in step 1 into it.
5. Open the Terminal, and merge the AIR 3.3 SDK files into your current SDK directory:

6. Edit the flex-sdk-description.xml file inside the new directory, and change the value of the <name> tag to Flex 4.6.0 (AIR 3.3) .
7. Open Flash Builder and choose Project > Properties > Flex Compiler > Configure Flex SDKs.
8. Click Add and navigate to the new folder location.

The most time consuming part is done. Now you're ready to write some code!

The next step is to add the com.milkmangames.extensions.EasyPush.ane file (or EasyPushAPI.swc for FlashDevelop) to your project. These files can be found in the extension folder of the EasyPush Notifications extension package.

In Flash Professional CS6:

1. Choose File > Publish Settings > Flash > ActionScript 3.0 Settings
2. Click the wrench icon next to Script for ActionScript Settings.
3. Select the Library Path tab.
4. Click Browse For Native Extension (ANE) File and select com.milkmangames.extensions.EasyPush.ane.
5. Choose File > Publish Settings.
6. Select the AIR for iOS 3.3 target.

In Flash Builder 4.6:

1. Go to Project Properties (right-click your project in Package Explorer and select Properties).
2. Select ActionScript Build Path and click the Native Extensions tab.
3. Click Add ANE and navigate to the com.milkmangames.extensions.EasyPush.ane file.

In FlashDevelop:

1. Copy the EasyPushAPI.swc file to your project folder.
2. In the explorer panel, right-click the SWC and select Add To Library.
3. Right-click the SWC file in the explorer panel again, select Options, and then select External Library.

You can start using the EasyPush Notifications extension with a few simple calls. See example/EasyPush.as for a full example class.

Follow these steps to get started:

1. Import the API Classes:

2. To make sure that push notifications are available and working on the current platform, use the isSupported() and areNotificationsAvailable() methods. If they return false , your app won't be able to use push notifications (either the device does not support them or the user has disabled them.)

   If notifications are supported and available, you can initialize Urban Airship by calling the initAirship() method. This should be the very first thing your code does after the app starts to ensure any messages are properly received.

The initAirship() method takes six parameters. The first two are your app's Application Key and Secret, which you get from the Urban Airship website as described earlier. The third string value is reserved for future API use; you can use any string here.

The next three Boolean parameters are developmentMode , autoBadge , and autoAlertBox , in that order.

Setting developmentMode to true enables Development mode for your app- so that the Urban Airship server will transfer messages between its own sandbox server, and Apple's sandbox server, instead of using production URLs You'll want to set this to false when you are ready to publish to the app store.

Setting autoBadge to true will cause the notification badge number on your app's icon to be controlled automatically by Urban Airship.

Setting autoAlertBox to true will cause an AlertBox to appear in the native UI if the app receives a push while it's running. You can set it to false if you want to handle those messages with your own UI.

That's all you need for receiving basic push notifications!

Urban Airship lets you associate an alias or group of tags with a user. This is useful for targeting push notifications to a specific user or group of users.

Setting an alias

You can set an alias that's unique to the user to make them easily identifiable for push notifications. For instance, if you're using the GoViral extension to log the user into Facebook, you might want to set their alias to their Facebook ID, so you can send direct notifications to that particular user; for example:

Setting tags

You can set tags to assign users to logical groups so that you can send selective push notifications to them later.

Setting quiet time

Quiet time is a period during which notifications will not be displayed. The following example silences push notifications for the next 15 minutes:

The EasyPush Notifications native extension dispatches several events that you may want to handle.

Registration events

When the user starts your app and the extension is initialized, it will attempt to register them for notifications. As a result, either PNAEvent.TOKEN_REGISTERED or PNAEvent.TOKEN_REGISTRATION_FAILED will be dispatched. If registration succeeds, but some of the types of push requested are turned off (for instance, push messages are enabled, but not sounds), the PNAEvent.TYPES_DISABLED event will fire. The following code illustrates how these events can be handled:

Notification events

There are two scenarios for receiving notifications. Either the app was open, and a push was received ( PNAEvent.FOREGROUND_NOTIFICATION ), or the app was in the background, and the user clicked the notification to open the app ( PNAEvent.RESUMED_FROM_NOTIFICATION ). In the former case, a message box with the notification will automatically be displayed to the user, if autoAlertBox was set to true in the initAirship() call. If the user taps the OK button on this alert, PNAEvent.ALERT_DISMISSED will be dispatched.

These events contain extra information about the notifications that were sent. You can use this data to perform additional actions in your app.

In your application descriptor file, you need to specify the version of the AIR SDK you are using (3.3 or later) as well as a link to the extension. For a working example, see example/app.xml.

1. If it is not already set, set your AIR SDK version in the application descriptor:

2. Include a link to the extension in the descriptor:

3. Make sure that your <id> property exactly matches the App ID you created in the iOS Provisioning Portal.
4. You must add a special entitlements element to the application XML file and include in it the App ID you created in the iOS Provisioning Portal. The App ID consists of a string of random letters and numbers followed by your App Bundle ID. For instance, it might be something like "Q942RZTE24.com.yourcompany.yourgame". Copy this exact string twice into the <iphone> block of your application descriptor, like so:

1. Make sure you replace the App ID strings in the example above with your own values, from the iOS Provisioning Portal.
2. When you build your App Store release, you must change development to production , and remove the entire <key>get-task-allow</key><true/> line.

If you're using Flash Builder 4.6 or later, or Flash Professional CS6 or later, and have added the EasyPush Notifications extension library as described above, then you can compile as you usually do directly from the IDE. If not and you are building your app with the extension from the command line, then you'll need to specify the directory containing the com.milkmangames.nativeextensions.EasyPush.ane file.

Here is an example build command line:

Take note of the dot after -extdir . It is not a typo; it tells the adt packager to look for the extension in the current directory.

Once you've built your app and successfully installed it on your device, it's easy to send a test push notification with Urban Airship:

1. Log in to your account on http://www.urbanairship.com and select your new app.
2. Click Push on the left.
3. Select Device Tokens. You should see a token on the list for your own phone. Copy the token to the clipboard (see Figure 8).

4. Click Test Push Notifications and then click the iOS tab. For Device Token, paste the device token you just copied. For Alert, type the text of your message. If you want the alert box window to have a title, add an aTitle property to the JSON Payload (see Figure 9).

That's it! The notification should trigger on your device. To send a notification to multiple devices, use the Send Broadcast option instead.

Now that you have push notifications up and running in your app, you may want to explore these other native extension tutorials:

• Using in-app ratings with the RateBox native extension for Adobe AIR on iOS and Android
• Using native extensions in Adobe Flash Professional CS6
• Using the In-App Billing Adobe AIR native extension for Android
• Using the iOS In-App Purchase native extension for Adobe AIR
• Using the GoViral social networking extension for iOS
• Using the GameCenter Adobe AIR native extension for iOS
• Using the iAd Adobe AIR native extension for iOS

For additional extensions, see More Native Extensions from Milkman Games.