Requirements
Prerequisite knowledge
Experience building games for iOS with Flash Builder or Flash Professional and Adobe AIR will help you make the most of this article.
Required products
Flash Builder (Download trial)
Adobe Animate CC
Adobe AIR SDK
Additional required other products
Milkman Games EasyPush Notifications Extension for iOS
User level
Intermediate

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

 
Configuring your app in the iOS Provisioning Portal

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.
Figure 1. Setting up a new App ID in Provisioning Portal.
Figure 1. Setting up a new App ID in Provisioning Portal.
 
  1. 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.
 
  1. Back on the App IDs list, scroll down and locate the ID you just created. Click Configure (see Figure 2).
Figure 2. Click Configure for your new App ID.
Figure 2. Click Configure for your new App ID.
 
 
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.
 
  1. Click Enable For Apple Push Notification Service.
  2. Click the Configure button next to Development Push SSL Certificate (see Figure 3).
Figure 3. Select Configure for your Development Push SSL Certificate.
Figure 3. Select Configure for your Development Push SSL Certificate.
 
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.
 
Figure 4. The Apple Push Notification service SSL Certificate Assistant.
Figure 4. The Apple Push Notification service SSL Certificate Assistant.
 
  1. 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".
  2. 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.
  3. 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.
  4. 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.
Figure 5. Configuring a Development Provisioning Profile.
Figure 5. Configuring a Development Provisioning Profile.
 
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.
 

 
Configuring your app for use with Urban Airship

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).
Figure 6. Uploading an SSL Certificate to Urban Airship.
Figure 6. Uploading an SSL Certificate to Urban Airship.
 
  1. Click Create Your App.
  2. 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.
Figure 7. Locating your Urban Airship Application Key.
Figure 7. Locating your Urban Airship Application Key.
 

 
Installing the AIR 3.3 SDK

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:
sudo cp -Rp /Applications/Adobe\ Flash\ Builder\ 4.6/sdks/AIR33SDK/ /Applications/Adobe\ Flash\ Builder\ 4.6/sdks/4.6.0/
  1. 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) .
  2. Open Flash Builder and choose Project > Properties > Flex Compiler > Configure Flex SDKs.
  3. Click Add and navigate to the new folder location.
The most time consuming part is done. Now you're ready to write some code!
 

 
Including the EasyPush Notifications API Library

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.

 
Getting started with the API

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:
import com.milkmangames.nativeextensions.*; import com.milkmangames.nativeextensions.events.*;
  1. 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.
     
if(EasyPush.isSupported() && EasyPush.areNotificationsAvailable()) { // "YOUR_AIRSHIP_KEY” - put your application key from urban airship here // "YOUR_AIRSHIP_SECRET” - put the app secret from urban airship here // true – sets development mode to ON. Set to false only when publishing for app store. // true – enables automatic badge number tracking on the icon (optional) // true – will automatically show alert boxes when a push is received. EasyPush.initAirship("YOUR_AIRSHIP_KEY”,”YOUR_AIRSHIP_SECRET”,”airship”,true,true,true); } else { trace("Push is not supported or is turned off...”); return; }
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!
 

 
Settings tags, quiet time, and aliases (optional)

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:
 
// sets the user's alias to "bob@internet.com”. // You'd want to be sure this is unique to your user though! EasyPush.airship.updateAlias("bob@internet.com”);
 
Setting tags
You can set tags to assign users to logical groups so that you can send selective push notifications to them later.
 
// create a vector array of tags var tags:Vector.<String>=new Vector.<String>(); tags.push("advanced"); tags.push("gamer"); EasyPush.airship.setAirshipTags(tags);
 
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:
 
//Setting quiet time for next 15 minutes... var now:Date=new Date(); var inFifteen:Date=new Date(); inFifteen.setTime(now.millisecondsUTC+(15*60*1000)); EasyPush.airship.setQuietTime(now,inFifteen);

 
Handling push events (optional)

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:
 
EasyPush.airship.addEventListener(PNAEvent.TOKEN_REGISTERED,onTokenRegistered); EasyPush.airship.addEventListener(PNAEvent.TOKEN_REGISTRATION_FAILED,onRegFailed); EasyPush.airship.addEventListener(PNAEvent.TYPES_DISABLED,onTokenTypesDisabled); function onTokenRegistered(e:PNAEvent):void { trace("token was registered: "+e.token); } function onRegFailed(e:PNAEvent):void { trace("reg failed: "+e.errorId+"="+e.errorMsg); } function onTokenTypesDisabled(e:PNAEvent):void { trace(“some types disabled:”+e.disabledTypes); }
 
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.
 
EasyPush.airship.addEventListener(PNAEvent.ALERT_DISMISSED,onAlertDismissed); EasyPush.airship.addEventListener(PNAEvent.FOREGROUND_NOTIFICATION,onNotification); EasyPush.airship.addEventListener(PNAEvent.RESUMED_FROM_NOTIFICATION,onNotification); function onNotification(e:PNAEvent):void { trace(“new notification, type+"="+e.rawPayload+","+e.badgeValue+","+e.title); } function onAlertDismissed(e:PNAEvent):void { trace(“Alert dismissed, payload="+e.rawPayload+","+e.badgeValue+","+e.title); }

 
Updating your application descriptor file

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:
<application xmlns="http://ns.adobe.com/air/application/3.3">
  1. Include a link to the extension in the descriptor:
<extensions> <extensionID>com.milkmangames.extensions.EasyPush</extensionID> </extensions>
  1. Make sure that your <id> property exactly matches the App ID you created in the iOS Provisioning Portal.
  2. 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:
<iPhone> <InfoAdditions> <![CDATA[ <key>UIDeviceFamily</key> <array> <string>1</string> <string>2</string> </array> ]]> </InfoAdditions> <Entitlements> <![CDATA[ <key>application-identifier</key> <string>Q942RZTE24.com.yourcompany.yourgame</string> <key>aps-environment</key> <string>development</string> <key>get-task-allow</key> <true/> <key>keychain-access-groups</key> <array> <string>Q994RZTE24.com.milkmangames.pushexample</string> </array> ]]> </Entitlements> </iPhone>
  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.

 
Building the application

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:
 
c:\dev\air_sdk_33\bin\adt -package -target ipa-test-interpreter -storetype pkcs12 -keystore YOURKEYSTOREFILE.P12 -storepass YOURPASSWORD -provisioning-profile YOUR_MOBILEPROVISION_FILE.mobileprovision myapp.ipa myapp.xml myapp.swf -extdir .
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.
 

 
Sending a test notification with Urban Airship

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).
Figure 8. Locating your Urban Airship device token.
Figure 8. Locating your Urban Airship device token.
 
  1. 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).
Figure 9. Authoring a test push notification.
Figure 9. Authoring a test push notification.
 
That's it! The notification should trigger on your device. To send a notification to multiple devices, use the Send Broadcast option instead.
 

 
Where to go from here

Now that you have push notifications up and running in your app, you may want to explore these other native extension tutorials:
 
For additional extensions, see More Native Extensions from Milkman Games.