By Varun Bhatia



29 May 2012

[UPDATEInvokeEventReason.NOTIFICATION added for accessing the notification payload when application was not running in the background. Latest AIR build containing these changes available here]
Push/Remote Notifications support for iOS platform has been made available in latest release of AIR 3.4. This blogpost will cover everything you need to do to get remote/push notifications working in your AIR application: subscribing for remote notifications, configuring your application in the iOS Provisioning Portal, sending notifications to Apple’s Push Notification Service (APNS), and handling them in your application. Another detailed article discussing Push Notifications Support in AIR can be found at


Remote notifications, or server push or push notifications, describe a style of Internet-based communication where the request for a given notification is initiated by the publisher or central server. It contrasts with pull technology, where the request for the transmission of information is initiated by the receiver or client (device in our case). Push technology has the advantage over pull notifications that device battery and network bandwidth are saved when no new data is available.
Apple & Google have worked around these limitations with a push-based design. They have come up with the concept of an intermediate server, namely APNS (Apple Push Notifications Service) and Google C2DM (Cloud To Device Messaging), to handle all push notifications between the device and the third party servers. Rather than forcing your app to remain open and constantly querying for updates, device OS (iOS and Android) itself instead listens for updates and notifies your application as and when they arrive. The result is decreased processor, memory, and battery use. Additionally, instead of each app connecting to its own server, a single persistent connection is maintained between the device and the notification server (APN or C2DM). Complete details can be found here.


Basic Workflow for Push Notifications

  1. The application submits a request to the underlying OS to subscribe/register for push notifications. The application can choose the notification styles it wishes to subscribe for.
  2. The underlying OS then makes a secure connection to the APNS/C2DM, gets back a device token, and passes it to your application. [ Note that, this token is not the same as the device identifier.] This token is periodically refreshed. When the device registers for notifications again it will might a different device token. There are no guidelines on how soon the device token gets refreshed. It is therefore advisable to fetch the fresh device token on every launch of the application by subscribing for push notifications again and send it to the third party server.
  3. The application passes this token to the third party server.
  4. When the third party server wishes to send a push notification to a particular user, it grabs that user’s device token and sends it in a specially formatted payload to the APNS/C2DM.
  5. The APNS/C2DM forwards the message on to the given user’s device.


Type of Push Notifications Supported

AIR on iOS supports following three styles of notification
  1. Alert: An alert box with a custom message in displayed in the remote notification.
  2. Badge: A badge is displayed on the application icon on receiving the notification. The badge icon is always cleared on the next launch of the application.
  3. Sound: A sound is played on receiving the remote notification.


Configure Your iOS App in the Provisioning Portal

Each iOS applications that uses the APN service must have a unique application ID that uniquely identifies itself. The reason being, the APN must be able to identify the specific device on which application is installed to which the push belongs, but wildcard identifiers allow you to build multiple apps with the same provisioning profile. Create a new App ID and configure it to enable push notifications service on this App ID. A detailed tutorial on how to create a new App ID can be found here.


Push Notification Server

This article covers the details on how to set up a push notification server that communicates with APNS to send notifications. A number of third party servers are also available that allow you to send notifications to your application. These can be used initially to test push notifications during development phase until you are ready with your push notification server. UrbanAirship is one of such third party server. More details on how to use Urban Airship can be found here. The sample code below demonstrates how to send the device token to the Urban Airship.
Code Snippet

import flash.notifications.*;
// empty Vector List is returned on platforms on which none of the notification styles is supported.
if ( RemoteNotifier.supportedNotificationStyles.length > 0)
var preferredNotificationStyles:Vector. = new Vector.;


var subscribeOptions:RemoteNotifierSubscribeOptions = new RemoteNotifierSubscribeOptions();
subscribeOptions.notificationStyles = preferredNotificationStyles;

rn = new RemoteNotifier();

rn.addEventListener(RemoteNotificationEvent.TOKEN, sendDeviceTokenToServer);
rn.addEventListener(RemoteNotificationEvent.NOTIFICATION, notificationReceivedByApp);
rn.addEventListener(StatusEvent.STATUS, subscriptionFailureCallback);

// calling subscribe method without any subscribe options automatically subscribes // for all notification styles supported on that platform
protected function subscriptionFailureCallback(event:StatusEvent):void
trace("Received Status event for registrationFailure with code:" + event.code + " and level:" + event.level + "\n");
protected function sendDeviceTokenToServer(event:RemoteNotificationEvent):void
trace("Received " + event.type + " with tokenString:" + event.tokenId + "\n");
var urlRequest:URLRequest;
var urlLoader:URLLoader = new URLLoader();
var urlString:String = "" + event.tokenId;
urlRequest = new URLRequest(urlString);
urlRequest.authenticate = true;
urlRequest.method = URLRequestMethod.PUT;
URLRequestDefaults.setLoginCredentialsForHost("","","") ;
urlLoader.addEventListener(IOErrorEvent.IO_ERROR, onError);
urlLoader.addEventListener(Event.COMPLETE, onComplete);
urlLoader.addEventListener(HTTPStatusEvent.HTTP_STATUS, onStatus);
protected function notificationReceivedByApp(event:RemoteNotificationEvent):void
trace("Received RemoteNotificationEvent.RECEIVED\n");
for (var i:String in
trace("Key:value pair " + i + ":" +[i] + "\n");

When is RemoteNotificationEvent.NOTIFICATION event dispatched?
RemoteNotificationEvent.NOTIFICATION event is dispatched only in the following two cases:
  1. The application was in foreground when remote notification was received.
  2. The application was not in foreground when notification was received and as a result of the presented notification, the user taps the action button of the alert.


If the notification is delivered when the application isn’t running in the foreground, the system presents the notification, displaying an alert, badging an icon, perhaps playing a sound. And hence the event will not be dispatched. In other words, this event will NEVER be fired if application was in background(sleeping/dead).
For cases, when application is not running when notification was received and is launched on receiving the notification by pressing the launch button in the alert window or touching the banner alert, application is fired with InvokeEventReason set to InvokeEventReason.NOTIFICATION. The notification payload can be accessed in the first argument of the event object. You need to attach listener to InvokeEvent to check for the InvokeEventReason and arguments passed with it. The following code demonstrates the use case.

protected function onInvokeEvent(event:InvokeEvent):void
         trace(“Invokehandler called …. \n”);
         trace(“reason: “ + event.reason + “\n”);
        if( event.reason == InvokeEventReason.NOTIFICATION)
            var payload:Object = Object(event.arguments[0]);
              for (var i:String in payload)
                    trace(“Key:value pair “ + i + “:” + payload[i] + “\n”);

The above changes are only available from AIR 3.5 onwards and hence require swf-version set to 18 in Flash Builder Compiler settings.


How to handle RemoteNotificationEvent.TOKEN event?

RemoteNotificationEvent.TOKEN is dispatched upon successful subscription of push notifications by the application. The application now needs to send the App ID/ token received in to his server via URL request. Since App ID is periodically refreshed by APNS, it is, therefore, advisable to subscribe for push notifications service on every launch of the application and send it to the third party server (depending on the cellular/wifi data availaibility). An application will not be able to receive push notifications once the APNS refreshes the App ID and the refreshed App ID is not available with the third party server sending push notifications to the application. For example:- if a user restores a backup to a device other than the one that the backup was created for, he/she must launch the application at least once to receive notifications again (assuming application subscribes for push notifications at every launch ).


Packaging the Application with Correct Entitlements

The application identifier of the AIR app must be same as the application identifier mentioned in the  provisioning profile.


Application requiring push notifications support also need to package their app with following Entitlements. These entitlements can be put in the Entitlements tag under InfoAdditions tag.


For submitting the app to App Store with Push Notifications enabled, one needs to set the aps-environment tag mentioned above to production. The developer must use the provisioning profile with Push notifications enabled. One can cross check the Entitlements of the signed app using the following command.

codesign -d --entitlements - <YourAppName>.app

Also, remember to compile the swf with –swf-version=17 as an additional compiler argument.


Notification Payload Sample for iOS

Each push notification carries with it a payload. The payload specifies how users are to be alerted to the data waiting to be downloaded to the client application. The maximum size allowed for a notification payload is 256 bytes; Apple Push Notification Service refuses any notification that exceeds this limit. Remember that delivery of notifications is “best effort” and is not guaranteed. For each notification, providers must compose a JSON dictionary object that strictly adheres to RFC 4627. This dictionary must contain another dictionary identified by the key aps. The aps dictionary contains one or more properties that specify the following actions:
  • An alert message to display to the user.
  • A number to badge the application icon with.
  • A sound to play.


The payload in the following example specifies that device should display an alert message with both Close and View buttons. It also request that the application icon be badged with 9 and that a bundled alert sound be played when the notification is delivered.

"aps" : {
"alert" : "You have received new emails.",
"badge" : 9,
"sound" : "mailAlert.aiff"


How to Send Localized Remote Notifications to your Application?

The client application can store in its bundle the alert message strings translated for each localization it supports. The provider specifies the loc-key and loc-args properties in the aps dictionary of the notification payload. When the device receives the notification, it uses the aps dictionary properties to find and format the string localized for the current language which it then displays to the user. Localized strings must reside in the file called Localizable.strings in the appropriate .lproj folder. Each entry in this file has a key and a localized string value, the string can have format specifiers for the substitution of variables values.When an application asks for a particular string, it gets the resource that is localized for the language currently selected by the user.
In order to receive localized remote notifications, an AIR application must have localized key value pairs in Localizable.strings file in the /lproj folder inside the ipa. To add the Localizable.strings in the ipa, the developer just needs to mention the requested languages in the tag in the application descriptor and add the respective  .lproj folder in the adt command as follows:

<supportedLanguages>en es fr</supportedLanguages>

adt -package -target ipa-app-store -provisioning-profile <path to mobileprovision certificate> -storetype pkcs12 -keystore <path to Certificates.p12> -storepass <password> <ipa name> app.xml sample.swf en.lproj es.lproj fr.lproj

Please note that lproj folder need to present in the current directory to let the adt merge the files in appropriate lproj folder. If the lproj folder is given as a/b/c/en.lproj then adt adds this as a/b/c/en.lproj and hence localized key value pairs wont be accessible to the application.