The only free and fully functional Android GCM native extension for Adobe AIR

September 22, 2012

Overview

This tutorial is about native extension for Adobe AIR and GCM (Google Cloud Messaging) which is a free service provided by Google that allows messages to be pushed to devices of your app users. If anyone is interested in more information on how to create an Android app capable of reception of GCM messages please check out this article on Google dev portal: GCM Tutorial.

In the course of development of  a new social drawing app “Sketch Guess”, we wanted to add an ability for the server to notify players when important events occur in the game and display the appropriate view when the application resumes or restarts (the “fetch message payload after app just launched” capability is only implemented in our own solution so far). While there is an abundance of Adobe AIR native extensions for iOS, there was definitely a gap to be filled for Android applications.

The only way to proceed was to create our own extension which I’m going to provide here for download along with a fully functional example application and a set of instructions below.

The extension is made for Adobe SDK 4.6 + AIR SDK 3.1 . Although, I’m sure it’ll work with 4.5 and 3.0 or newer versions. My weapon of choice in developing Air things is Intellij 10 or 11, so I won’t be providing exact procedures to link to “.ane” when you setup the project since that varies from environment to environment.

Anyway, first things first. Please download the archive which contains extension and the example application from here. The package also contains APK which can be installed to any Android 2.2 +  right away and tested (it uses GCM sender ID of one of our test apps).

Actual extension “gcm.ane” is located in “ane/” folder and can’t be used right away for your own project (the usage can be seen in example application).

Compile and run example application

After downloading create a project for the example application in the IDE of your choice (Intellij, Flash Builder, Flash Develop, Flash CS) and use the following class as the main/application class:

“com.afterisk.gcmdemo.GCMExample” and the output swf file as “GCMExample.swf ” (I’m using ‘bin’ folder as output folder).

In dependencies of your project, specify a new library that includes “gcm.ane”. That should get rid of all the missing references application has. If you are using Flash Builder older than 4.6 or Intellij 10 you might want to duplicate gcm.ane and rename it into “gcm.swc” in order for the compiler to recognize the references.

Create a run configuration (to run on device) that uses the provided “gcm-air-app.xml” descriptor file, connect your device via USB and compile. That is really all that’s needed!

Use extension in your own application.

First you need to obtain your own Sender ID it’s on the lower part of your application page on Android Development Console. It looks like this:

GCM Sender ID

In order to obtain for your app you need to go here and follow Google’s instructions. Once that is done, replace the value of public static const GCM_SENDER_ID:String with your own senderID.

Now, insert the following part of provided application xml into your own application xml (things that need to be updated with your own data are highlighted):

<!-- Specify Android specific tags that get passed to AndroidManifest.xml file. -->

<!--[<span class="hiddenSpellError" pre="">CDATA</span>[-->

<!-- App receives GCM messages. -->

<!-- GCM connects to Google Services. -->

<!-- GCM requires a Google account. -->

<!-- Keeps the processor from sleeping when a message is received. -->

]]>

<!-- End of the schema for adding the android specific tags in AndroidManifest.xml file -->

Where you see “air.com.afterisk.gcmdemo” in descriptor xml you must update it with the ID you are using for the application and prepend it with “air.” (You need to do this because all AIR applications are added “air.” in front of the package name.)

Example of application id:

<id>com.mygreatcompany.myawsomeapp</id>

The references to that in GCM part of manifest should be:

<permission android:name=”air.com.mygreatcompany.myawsomeapp.permission.C2D_MESSAGE” android:protectionLevel=”signature” />
<uses-permission android:name=”air.com.mygreatcompany.myawsomeapp.permission.C2D_MESSAGE” />

….

<category android:name=”air.com.mygreatcompany.myawsomeapp” />

If you entered everything correctly you can create a run configuration and run the app on your device while using your own sender ID!

Sending and Receiving

There are certain parameters that this native extension expects to receive:

“title” – a title of message that shows in notification bar (optional).

“alert” – a message shown to users in notification bar, when notification is received and the application is either in the background or not running.

“type” – type of notification. You can put any string data into it, this parameter will be sent to client as a part of String typed message when application launches or resumes from notification.

“id” – same as “type,” another piece of data that is sent as part of String message (again, anything can be placed into it!).

Here is a PHP example showing construction of GCM payload (full class attached):

$message = array('title' => 'Sketch Guess', 'alert' => $user . ' created a new sketch!', 'type' => 'sketch_created', 'id' => $gameid);

$fields = array('registration_ids' => $registration_ids, 'data' => $message);

In AIR, if you trace your GCMEvent message property it will look something like this: “type: the_value_of_type_parameter,  id:  the-value_of_id_parameter”.

You can parse it however you like. Here is my example of the GCMEvent.MESSAGE “message” property parsing:

var pairs:Array = (message.split(","));
var space:RegExp = /"/g;
_notificationType = String(String(pairs[0]).split(":")[1]).replace(space, "");
_id = String(String(pairs[1]).split(":")[1]).replace(space, "");

Update:
This extension will send events wether the app is in the background or not to determine your app status use the following events, and handle GCM events apppropriately:

NativeApplication.nativeApplication.addEventListener(Event.ACTIVATE, handleActivate, false, 0, true);
NativeApplication.nativeApplication.addEventListener(Event.DEACTIVATE, handleDeactivate, false, 0, true); 

Based on the parameters of “id” or “type” you can now show an appropriate view to your users.

The example of fully working GCM messaging on Android can be seen in our new drawing game:

I hope the extension we created will help you with GCM messaging implementation.

Good luck!

Download

Again, here is GCM Extension and Example download link.

PHP Class to push messages to GCM service: GCM.php

GitHub address: https://github.com/AfteriskInc/AirGCM

Written by afterisktech Posted in Development, Technical Tagged with actionscript, adobe air, afterisk, android, as3, flash, gcm, mobile, native extension, push notifications, sketch guess