Montag, 2. Dezember 2013

Android Push/GCM - A very simple sample

Mobile applications often get even more interesting, if there is some exchange with a server application. The usual request-response-model looks as follows: the client – the app in this case – sends a request to the server and receives a response – immediately and synchronously.


In many cases this is enough. But what does it look like, if interesting things happen on the server and the client has to be informed about it?


Regarding the client to be responsible to fetch the data, the client could be implemented to poll, i.e. ask the server regularly, if there is something new. The disadvantages are evident: if the interval is to small, unnecessary communication will happen in many cases, if the interval is to big, the information might be „not recent enough“.
So, there has to be a possibility to access the mobile devices from the server side. Finally the distributors of the mobile systems have to be responsible to do this, since only they have the information to access the devices. The options to notify the device via call or short message are not fine-grained enough, since they reach the whole device and not one single application. Therefore the providers provide so called „Push“ services, which allow to access the applications from the server side. The responsibilty to transmit the information is transfered to the server. For iPhones of course Apple provides the appropriate service. For Android the „Google Cloud Messaging“ (GCM) is a part of the so-called „Google Play Services“. These further contain other interfaces to Google services, e.g. Google Maps, Google+ or the In-App-Payment.


The mobile application has to register as a potential receiver for push messages (1, 2) and provide the connection data to the server component (3). Using the identification of the client, the server is able to notify a relevant information (4) to the push service (5). This is responsible for submitting it soon to the mobile device (6).
To demonstrate this topic as simple as possible, I will present an app that transfers its communication data directly to the GCM service. This example only makes sense for demonstration purposes. At least I can't imagine an application that could reasonably notify itself via the Push service. At most the notification of the app on another device would be a possibility. But from an architectual point of view this would simply replace the server component in the case described above.


To gain further information there is an useful „getting startted“ tutorial available on the Google website (http://developer.android.com/google/gcm/index.html). I will restrict myself to the pure Android application.

Preparation: Google Console

In the Google Cloud Console „https://cloud.google.com/console“ there has to be created a (new) project. This one has to set under „APIs & auth / APIs“ the „Google Cloud Messaging for Android“ to „ON“. The „Project Number“ should be noted, we need it later.
A ServerKey is necessary to secure accessing the GCM service. If it is not already available (to be found at „Registered apps“ as „ServerKey“), you have to generate it. This step is quite difficult in the Google Cloud Console, as you need a SHA fingerprint – described in the tutorial. But you still have the possibility to use the „old“ Google Apis Console. („https://code.google.com/apis/console/“), where you are able to generate a ServerKey by pressing a button (at „API Access“, „Create new Server key“). The Google Apis Console tries to redirect you to the Google Cloud Console. Actually – November 2013 – it is possible to call the old Console via „Dismiss“. If this way is not available anymore, you have to do generate the key as described in the tutorial.
The ServerKey is transferred to the GCM later. The Key is the one propagated at „API KEY“ and may be copied as text. The Key should be active and „Any IP address is allowed“ should be displayed.

Preparation: Development environment

The GCM is part of the „Google Play Services“. Those have to be installed in the „Android SDK Manager“. You find them in the folder „Extras“.
To use the library in Eclipse, it has to be imported into the workspace. Just use the „File > Import“ dialog to choose „Android > Existing Android Code Into Workspace“ and enter the root folder and „Copy Projects Into Workspace“. The root folder for the Google Play Library Project is „/extras/google/google_play_services/libproject/google-play-services_lib“. To use other environments than eclipse, please consult the GCM tutorial.
For the app to be created, a new android project is created, using the Google Play Library. Therefore in the properties of the new project at „Android“ under „Library“ add the „google-play-services_lib“ project.

Preparation: Architecture

We create an app, consisting of a single activity. This just contains a button, to trigger the sending of the push message. To receive the push message, there has to be implemented a BroadcastReceiver.
In the Manifest file some permissions need to be defined:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />

<permission
        android:name="de.kluck.push.permission.C2D_MESSAGE"
        android:protectionLevel="signature" />

<uses-permission android:name="de.kluck.push.permission.C2D_MESSAGE" />
For the use of the latest version of the Google Play Library inside of the application tag the following entry is needed:

<meta-data android:name="com.google.android.gms.version" 
 android:value="@integer/google_play_services_version" />

Activity first try – very simple

Two steps are necessary at least: registering the App at GCM and triggering the push message.
For the most simple case we use an Activity containing 2 Buttons, that trigger exactly these operations. We use the button with the id „registerButton“ for registering and querying the registration id. The registration id defines, for which App the device should be accessed. Since it is an external service access, it has to be done in an AsyncTask. We need the PROJECT_NUMBER for this access. This is the one, that is shown in the Google Cloud Console – as mentioned above. So, the device registers itself for exactly this project:

String PROJECT_NUMBER = "...";
Context context;
String regid;

...

context = getApplicationContext();
View registerButton = findViewById(R.id.registerButton);
registerButton.setOnClickListener(new OnClickListener() {
 @Override
 public void onClick(View v) {
  new AsyncTask() {
   @Override
   protected String doInBackground(String... arg0) {
    String regId = null;
    try {
     String projectNumber = arg0[0];
         GoogleCloudMessaging gcm = 
      GoogleCloudMessaging.getInstance(context);
         regId = gcm.register(projectNumber);
              } catch (IOException e) {
     Log.e(TAG, "Error on register", e);
              }
    return regId;
   }
   @Override
   protected void onPostExecute(String result) {
    super.onPostExecute(result);
    regid = result;
   }
  }.execute(PROJECT_NUMBER);
     }
});
As trigger for the „real“ functionality we use a button with the id „pushButton“. Once again the call is done in a AsyncTask, that is propagated the registration id of the device, besides the API-Key of the application – received in the Google Cloud resp. Google Apis Console as described above. The latter will be hooked as Authorization Key to the HttpConnection. This should make sure, that only permitted access is possible. The RegistrationId is part of the content of the request. Besides the possibility to put the load data in an JSON string, there is the possibility to put the data right into the URI. This is not as flexible, espacially you are only able to access a single RegistrationId. In other words: you are able to give a list of RegistrationIds and the assigned devices are accessed in parallel. The „data“ part of the JSON object is not flexible at will, finally it is just a list of key value pairs.

View pushButton = findViewById(R.id.pushButton);
pushButton.setOnClickListener(new OnClickListener() {
    @Override
    public void onClick(View v) {
        new AsyncTask() {
            @Override
                protected Void doInBackground(String... arg0) {
                    try {
                        String apiKey = arg0[0];
                        String regId = arg0[1];
                        URL url =
                            new URL("https://android.googleapis.com/gcm/send");
                        HttpURLConnection connection =
                            (HttpURLConnection)url.openConnection();
                        connection.setDoOutput(true);
                        connection.setRequestMethod("POST");
                        connection.setRequestProperty("Authorization",
                            "key=" + apiKey);
                        connection.setRequestProperty("Content-Type",
                            "application/json");
                        OutputStreamWriter writer =
                            new OutputStreamWriter(
                                connection.getOutputStream());
                        writer.write("{\"registration_ids\" : [\"" + regId +
                            "\"],\"data\" : { \"action\" : \"push\"}}");
                        writer.close();

                        int responseCode = connection.getResponseCode();
                        Log.i(TAG, "responseCode: " + responseCode);
                    } catch (Exception e) {
                        Log.e(TAG, "Error on service call", e);
                    }
                    return null;
                }
            }.execute(API_KEY, regid);
        }
    });
}

BroadcastReceiver

The BroadcastReceiver to receive the push messages is defined in the Manifest file with the appropriate rights and intent-filter:

<receiver
    android:name="de.kluck.push.GcmBroadcastReceiver"
    android:permission="com.google.android.c2dm.permission.SEND" >
    <intent-filter>
        <action android:name="com.google.android.c2dm.intent.RECEIVE" />
        <category android:name="de.kluck.push" />
    </intent-filter>
</receiver>
The implementation in this example only „toasts“ the „action“ content of the Intent Extra:

public class GcmBroadcastReceiver extends WakefulBroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        Toast.makeText(context, "Result: " +
            intent.getStringExtra("action"), Toast.LENGTH_SHORT).show();
        setResultCode(Activity.RESULT_OK);
    }
}
The key value pairs of the JSON „data“ part of the HTTP request mentioned above are found in the Extras of the Intent. So you have the possibility to transfer data from the server to the device. Quantity and structure are restricted, so in many cases it will be implemented, so that for example just an id is transfered via push and the complex data is fetched via the „normal“ request-response access.

Activity second try – a little bit more clean

At the example above two things are disturbing: at first the GooglePlayServices are regarded as existing by the App. Since they are services that have to be installed seperately, the existence should be checked, before they are used. Secondly the registration of the App has to be done explicitely via pushing the button. A „real“ application should to this transparently in the background and since it is an external call, this should not be done more often then absolutely necessary.
To check if the availability of the GooglePlayServices on the device, a GooglePlayServicesUtil is available, practically containing methods for the output of the appropriate error dialogs:

private static final String TAG = "MainActivity";
private static final int PLAY_SERVICES_RESOLUTION_REQUEST = 9000;

private boolean checkPlayServices() {
    int resultCode = GooglePlayServicesUtil.isGooglePlayServicesAvailable(this);
    if (resultCode != ConnectionResult.SUCCESS) {
        if (GooglePlayServicesUtil.isUserRecoverableError(resultCode)) {
            GooglePlayServicesUtil.getErrorDialog(resultCode, this,
                PLAY_SERVICES_RESOLUTION_REQUEST).show();
        } else {
            Log.i(TAG, "This device is not supported.");
            finish();
        }
        return false;
    }
    return true;
}
Only in the case of successfully passing the test, the RegistrationId of the device can be requested via the GoogleCloudMessaging. The RegistrationId finally fixes, which App should be accessed on the device:

private static final String PROPERTY_REG_ID = "registration_id";
private static final String PROPERTY_APP_VERSION = "appVersion";

String PROJECT_NUMBER = "...";
String API_KEY = "...";

GoogleCloudMessaging gcm;
Context context;
String regid;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    // ...  

    context = getApplicationContext();
        
    // Check device for Play Services APK
    if (checkPlayServices()) {
        //  Proceed with GCM registration.
        gcm = GoogleCloudMessaging.getInstance(this);
        regid = getRegistrationId(context);

        if (regid.isEmpty()) {
            registerInBackground();
        }
    } else {
        Log.i(TAG, "No valid Google Play Services APK found.");
    }
}
According to the GCM tutorial and with the background, that the access of the GCM service should not be done with every start of the App, the RegistrationId is stored in the SharedPreferences of the app and only requested again if necessary. Namely if the app was changed significantly.

private String getRegistrationId(Context context) {
    final SharedPreferences prefs = getGCMPreferences(context);
    String registrationId = prefs.getString(PROPERTY_REG_ID, "");
    if (registrationId.isEmpty()) {
        Log.i(TAG, "Registration not found.");
        return "";
    }
    int registeredVersion = prefs.getInt(PROPERTY_APP_VERSION,
        Integer.MIN_VALUE);
    int currentVersion = getAppVersion(context);
    if (registeredVersion != currentVersion) {
        Log.i(TAG, "App version changed.");
        return "";
    }
    return registrationId;
}

private SharedPreferences getGCMPreferences(Context context) {
    return getSharedPreferences(MainActivity.class.getSimpleName(),
        Context.MODE_PRIVATE);
}

private static int getAppVersion(Context context) {
    try {
        PackageInfo packageInfo = context.getPackageManager()
            .getPackageInfo(context.getPackageName(), 0);
        return packageInfo.versionCode;
    } catch (NameNotFoundException e) {
        throw new RuntimeException("Could not get package name: " + e);
    }
}
Only if no or no actual RegistrationId is stored in the SharedPreferences, the service has to be accessed - using an asynchronous access, of course:

private void registerInBackground() {
    new AsyncTask() {
        @Override
        protected String doInBackground(Void... params) {
            String msg = "";
            try {
                if (gcm == null) {
                    gcm = GoogleCloudMessaging.getInstance(context);
                }
                regid = gcm.register(PROJECT_NUMBER);
                msg = "Device registered, registration ID=" + regid;

                storeRegistrationId(context, regid);
            } catch (IOException ex) {
                msg = "Error :" + ex.getMessage();
            }
            return msg;
        }

        @Override
        protected void onPostExecute(String msg) {
         Log.i(TAG, msg);
        }
    }.execute(null, null, null);
}

private void storeRegistrationId(Context context, String regId) {
    final SharedPreferences prefs = getGCMPreferences(context);
    int appVersion = getAppVersion(context);
    Log.i(TAG, "Saving regId on app version " + appVersion);
    SharedPreferences.Editor editor = prefs.edit();
    editor.putString(PROPERTY_REG_ID, regId);
    editor.putInt(PROPERTY_APP_VERSION, appVersion);
    editor.commit();
}
That was the administrative overhead. To really be clean, you should check the PlayServices in the onResume method of the activity, just to be sure, that the have not been unistalled meanwhile:

@Override
protected void onResume() {
    super.onResume();
    checkPlayServices();
}

Testing the App

The given app is not able to be executed in a virtual device and has to be tested on a real device. After the button is pressed there should relatively soon the Toast with the message be seen – not very exciting.

Summary

As already mentioned above, this example is unrealistic because of the lack of a server component. I hope to have demonstrated in a nutshell, what is necessary to use the push service in the App. The relevant parts of the server component are restricted to accessing an HTTP service. This has to happen analoguous to the access inside of the App.

Freitag, 29. November 2013

Android Push/GCM – Ein sehr einfaches Beispiel

Mobile Applikationen – also Apps – werden oft erst wirklich interessant, wenn ein Daten-Austausch mit einer Server Applikation erfolgt. Das übliche Request-Response-Modell sieht dann so aus, dass der Client – in diesem Fall die App – eine Anfrage (Request) an den Server sendet und sofort synchron die Antwort des Servers (Response) bekommt.


In vielen Fällen ist das völlig ausreichend. Wie sieht es aber aus, wenn interessante Dinge auf dem Server passieren und der Client darüber informiert werden muss?


Sieht man die „Hol-Schuld“ beim Client, würde der Client „pollen“, also in regelmäßigen Zeitabständen beim Server nachfragen, ob es was Neues gibt. Die Nachteile liegen auf der Hand: ist das Zeitintervall zu klein, findet in zu vielen Fällen ein unnötige Kommunikation statt, ist das Zeitintervall zu groß ist die Information unter Umständen „nicht ausreichend aktuell“.
Es muss also eine Möglichkeit geben, die mobilen Geräte seitens des Servers anzusprechen. Letztendlich kann die Erreichbarkeit der Geräte nur unter Mithilfe der Anbieter der Mobiltelefon-Systeme gewährleistet werden, da nur diese die entsprechenden Information besitzen. Die Optionen, das Gerät per Anruf oder SMS zu benachrichtigen, sind in diesem Fall nicht fein-granular genug, da sie das gesamte Gerät und nicht eine spezielle App erreichen. Daher stellen die Anbieter sogenannte „Push“-Dienste zur Verfügung, die es erlauben die Apps servergesteuert zu erreichen – die „Bring-Schuld“ liegt in diesem Fall also beim Server. Für iPhones stellt selbstverständlich Apple den entsprechenden Service zur Verfügung, für Android ist das als „Google Cloud Messaging“ (GCM) Bestandteil der sogenannten „Google Play Services“. Darunter sind weitere Schnittstellen zu Google-Diensten zusammengefasst, wie z.B. Google Maps, Google+ oder auch für die Abwicklung von Bezahlvorgängen (In-App-Payment).


Die App muss sich dazu als potenzieller Empfänger von Push-Nachrichten registrieren (1, 2) und die entsprechenden Verbindungsdaten der Server-Komponente zur Verfügung stellen (3). Mit der Identifikation des Clients, kann der Server ein für den Client interessantes Ereignis (4) dem Push-Service mitteilen (5). Dieser ist dann dafür verantwortlich, dieses zeitnah dem Mobilgerät weiterzuleiten (6).
Um das Thema einfachst möglich zu demonstrieren, werde ich hier eine App vorstellen, die mit ihren Verbindungsdaten den GCM-Service direkt anspricht. Das Beispiel ist eigentlich nur zu Demonstrationszwecken sinnvoll, jedenfalls fällt mir keine Anwendung ein, für die es sinnvoll wäre, dass eine App sich selbst über GCM benachrichtigen sollte. Allenfalls die Benachrichtigung der App auf einem anderen Device wäre eine vorstellbare Möglichkeit. Diese wäre dann aber aus architektonischer Sicht letztendlich nur ein Ersatz der Server-Komponente im oberen Fall.


Für weitere Informationen gibt es bei Google es ein sehr brauchbares „Getting Started“-Tutorial (http://developer.android.com/google/gcm/index.html). Ich will mich aber auf die reine Android-App beschränken.

Vorbereitung: Google-Console

In der Google Cloud Console „https://cloud.google.com/console“ ist ein (neues) Projekt anzulegen. Für dieses muss unter „APIs &; auth / APIs“ das „Google Cloud Messaging for Android“ auf „ON“ geschaltet sein. Die „Project Number“ kann man sich schon mal merken (im Sinne von kopieren), die benötigen wir später noch.
Zur Absicherung des Zugriffs auf den GCM-Service benötigt man einen ServerKey für das Projekt. Falls dieser noch nicht vorhanden ist (zu finden bei „Registered apps“ als „ServerKey“), muss er erzeugt werden. In der Google Cloud Console ist das relativ kompliziert, da man einen SHA-Fingerprint benötigt – beschrieben im Tutorial. Noch gibt es allerdings die „alte“ Google Apis Console („https://code.google.com/apis/console/“), unter der ein ServerKey per Knopfdruck generiert werden kann (dort unter „API Access“, „Create new Server key“). Die Google Apis Console versucht, auf die Google Cloud Console weiterzuleiten. Noch – Stand November 2013 – ist es jedoch möglich, per „Dismiss“ die alte Console aufzurufen. Falls das irgendwann nicht mehr möglich ist, muss wohl der im Tutorial beschriebene Weg verwendet werden.
Der ServerKey wird später dem GCM übergeben und kann als Text herauskopiert werden. Der Key sollte aktiv sein und „Any IP address is allowed“ sollte angezeigt werden.

Vorbereitung: Entwicklungsumgebung

Das GCM ist ein Bestandteil der „Google Play Services“. Diese müssen im „Android SDK Manager“ installiert sein. Zu finden sind sie unter dem Ordner „Extras“.
Um unter Eclipse auf die Library zuzugreifen, muss sie in den Workspace importiert werden. Dazu über den „File > Import“ Dialog „Android > Existing Android Code Into Workspace“ auswählen und dort das Root Verzeichnis und „Copy Projects Into Workspace“ wählen. Das Root-Verzeichnis für das Google Play Library Project ist „/extras/google/google_play_services/libproject/google-play-services_lib“. Zum Vorgehen bei anderen Umgebungen als Eclipse: siehe GCM-Tutorial.
Für die zu erstellende App wird ein Android-Projekt angelegt, dass die Google Play Library verwendet. Dafür in den Properties des neuen Projekts im Punkt „Android“ unter „Library“ das „google-play-services_lib“ Projekt hinzufügen.

Vorbereitung: Architektur

Wir erstellen eine App, die nur aus einer Activity besteht. Diese enthält nur den Button, um das Senden des Push auszulösen. Zum Empfangen der Push-Nachricht muss ein BroadcastReceiver implementiert werden.
Im Manifest-File müssen einige permissions definiert werden:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />

<permission
        android:name="de.kluck.push.permission.C2D_MESSAGE"
        android:protectionLevel="signature" />

<uses-permission android:name="de.kluck.push.permission.C2D_MESSAGE" />
Für die neueste Version der Google Play Library muss innerhalb des application-Tags folgender Eintrag vorhanden sein:

<meta-data android:name="com.google.android.gms.version" 
 android:value="@integer/google_play_services_version" />

Activity 1. Anlauf – ganz einfach

Es sind zwei Schritte unbedingt notwendig: das Registrieren der App am GCM und das eigentlich Auslösen der Push-Nachricht.
Im einfachsten Fall verwenden wir eine Activity mit 2 Buttons, die genau diese Operationen auslösen. Wir verwenden den Button mit der Id „registerButton“ zum Registrieren und Holen der RegistrationId. Die RegistrationId legt letztendlich fest, für welche App das Device angesprochen werden soll. Da es sich um einen externen Service-Aufruf handelt, muss er in einem AsyncTask erfolgen. Dazu wird die PROJECT_NUMBER benötigt. Das ist diejenige, die in der Google Cloud Console angezeigt wird – siehe oben. Das Device registriert sich also für genau dieses Projekt:

String PROJECT_NUMBER = "...";
Context context;
String regid;

...

context = getApplicationContext();
View registerButton = findViewById(R.id.registerButton);
registerButton.setOnClickListener(new OnClickListener() {
 @Override
 public void onClick(View v) {
  new AsyncTask() {
   @Override
   protected String doInBackground(String... arg0) {
    String regId = null;
    try {
     String projectNumber = arg0[0];
         GoogleCloudMessaging gcm = 
      GoogleCloudMessaging.getInstance(context);
         regId = gcm.register(projectNumber);
              } catch (IOException e) {
     Log.e(TAG, "Error on register", e);
              }
    return regId;
   }
   @Override
   protected void onPostExecute(String result) {
    super.onPostExecute(result);
    regid = result;
   }
  }.execute(PROJECT_NUMBER);
     }
});
Als Auslöser der „eigentlichen“ Funktionalität verwenden wir einen Button mit der Id „pushButton“. Der Aufruf erfolgt auch hier in einem AsyncTask, dem die gerade erworbene RegistrationId des Devices ebenso übergeben wird, wie der API-Key der Anwendung – wie oben beschrieben aus der Google Cloud bzw. Google Apis Console zu beziehen. Letzterer wird dann als Authorization Key an die HttpConnection gehängt. Dadurch soll sichergestellt werden, dass nur berechtige Zugriffe erfolgen. Die Registration Id ist Bestandteil des Contents des Requests. Neben der hier verwendeten Möglichkeit, die Nutzdaten in einem JSON-String zu verpacken, gibt es auch die Möglichkeit, Daten direkt in der URL mitzugeben. Das ist aber nicht ganz so flexibel, insbesondere kann nur eine einzelne RegistrationId angesprochen werden. Mit anderen Worten: es kann durchaus durch Angabe einer Liste von RegistrationsIds eine ganze Reihe von Devices parallel angesprochen werden! Der „data“-Teil des JSON-Objekts ist nicht beliebig flexibel, letztlich ist es nur eine Liste von Key-Value-Paaren.

View pushButton = findViewById(R.id.pushButton);
pushButton.setOnClickListener(new OnClickListener() {
    @Override
    public void onClick(View v) {
        new AsyncTask() {
            @Override
                protected Void doInBackground(String... arg0) {
                    try {
                        String apiKey = arg0[0];
                        String regId = arg0[1];
                        URL url =
                            new URL("https://android.googleapis.com/gcm/send");
                        HttpURLConnection connection =
                            (HttpURLConnection)url.openConnection();
                        connection.setDoOutput(true);
                        connection.setRequestMethod("POST");
                        connection.setRequestProperty("Authorization",
                            "key=" + apiKey);
                        connection.setRequestProperty("Content-Type",
                            "application/json");
                        OutputStreamWriter writer =
                            new OutputStreamWriter(
                                connection.getOutputStream());
                        writer.write("{\"registration_ids\" : [\"" + regId +
                            "\"],\"data\" : { \"action\" : \"push\"}}");
                        writer.close();

                        int responseCode = connection.getResponseCode();
                        Log.i(TAG, "responseCode: " + responseCode);
                    } catch (Exception e) {
                        Log.e(TAG, "Error on service call", e);
                    }
                    return null;
                }
            }.execute(API_KEY, regid);
        }
    });
}

BroadcastReceiver

Der BroadcastReceiver zum Empfangen der Push-Nachricht wird im Manifest-File mit der entsprechenden Berechtigung und dem passenden Intent-Filter definiert:

<receiver
    android:name="de.kluck.push.GcmBroadcastReceiver"
    android:permission="com.google.android.c2dm.permission.SEND" >
    <intent-filter>
        <action android:name="com.google.android.c2dm.intent.RECEIVE" />
        <category android:name="de.kluck.push" />
    </intent-filter>
</receiver>
Die Implementierung soll für dieses Beispiel einfach nur den „action“-Betandteil des Intent-Extras „toasten“:

public class GcmBroadcastReceiver extends WakefulBroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        Toast.makeText(context, "Result: " +
            intent.getStringExtra("action"), Toast.LENGTH_SHORT).show();
        setResultCode(Activity.RESULT_OK);
    }
}
Die oben angesprochenen Key-Value-Paare des JSON-“data“-Bestandteil des HTTP-Requests finden sich tatsächlich hier in den „Extras“ des Intents wieder. Man hat so also die Möglichkeit, Daten vom Server zum Device zu transportieren. Umfang und Struktur sind zwar eingeschränkt, aber es besteht ja immer noch die Möglichkeit, beispielsweise eine Id zu übergeben und die kompletten Daten über den „normalen“ Request-Response-Weg zu holen.

Activity 2. Anlauf – etwas sauberer, bitte

An dem obigen Beispiel stören zwei Dinge: zum einen werden die Google Play Services von der App als vorhanden vorausgesetzt. Da es sich um einen zu installierenden Service handelt, sollte die Existenz geprüft werden, bevor er verwendet wird. Zum anderen muss die Registrierung der App explizit per Knopfdruck erfolgen. Bei einer richtigen Anwendung sollte das transparent im Hintergrund stattfinden und da es sich um einen externen Aufruf handelt, auch nicht öfter als unbedingt notwendig.
Um das Vorhandensein der GooglePlayServices auf dem Device zu prüfen, steht ein GooglePlayServicesUtil zur Verfügung, was praktischerweise auch gleich Methoden zur Ausgabe der entsprechenden Fehler-Dialoge enthält:

private static final String TAG = "MainActivity";
private static final int PLAY_SERVICES_RESOLUTION_REQUEST = 9000;

private boolean checkPlayServices() {
    int resultCode = GooglePlayServicesUtil.isGooglePlayServicesAvailable(this);
    if (resultCode != ConnectionResult.SUCCESS) {
        if (GooglePlayServicesUtil.isUserRecoverableError(resultCode)) {
            GooglePlayServicesUtil.getErrorDialog(resultCode, this,
                PLAY_SERVICES_RESOLUTION_REQUEST).show();
        } else {
            Log.i(TAG, "This device is not supported.");
            finish();
        }
        return false;
    }
    return true;
}
Nur wenn dieser Test erfolgreich ist, kann über das GoogleCloudMessaging die RegistrationId des Devices geholt werden:

private static final String PROPERTY_REG_ID = "registration_id";
private static final String PROPERTY_APP_VERSION = "appVersion";

String PROJECT_NUMBER = "...";
String API_KEY = "...";

GoogleCloudMessaging gcm;
Context context;
String regid;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    // ...  

    context = getApplicationContext();
        
    // Check device for Play Services APK
    if (checkPlayServices()) {
        //  Proceed with GCM registration.
        gcm = GoogleCloudMessaging.getInstance(this);
        regid = getRegistrationId(context);

        if (regid.isEmpty()) {
            registerInBackground();
        }
    } else {
        Log.i(TAG, "No valid Google Play Services APK found.");
    }
}
Angelehnt an das GCM-Tutorial und mit dem Hintergrund, dass der Zugriff auf den GCM-Service nicht bei jedem Start der App erfolgen soll, wird hier die RegistrationId in den SharedPreferences der App gespeichert und nur neu geholt, wenn notwendig. Nämlich dann, wenn sich die App signifikant geändert hat.

private String getRegistrationId(Context context) {
    final SharedPreferences prefs = getGCMPreferences(context);
    String registrationId = prefs.getString(PROPERTY_REG_ID, "");
    if (registrationId.isEmpty()) {
        Log.i(TAG, "Registration not found.");
        return "";
    }
    int registeredVersion = prefs.getInt(PROPERTY_APP_VERSION,
        Integer.MIN_VALUE);
    int currentVersion = getAppVersion(context);
    if (registeredVersion != currentVersion) {
        Log.i(TAG, "App version changed.");
        return "";
    }
    return registrationId;
}

private SharedPreferences getGCMPreferences(Context context) {
    return getSharedPreferences(MainActivity.class.getSimpleName(),
        Context.MODE_PRIVATE);
}

private static int getAppVersion(Context context) {
    try {
        PackageInfo packageInfo = context.getPackageManager()
            .getPackageInfo(context.getPackageName(), 0);
        return packageInfo.versionCode;
    } catch (NameNotFoundException e) {
        throw new RuntimeException("Could not get package name: " + e);
    }
}
Nur dann, wenn keine (aktuelle) RegistrationId in den SharedPreferences hinterlegt ist, muss der Service aufgerufen werden – auch hier natürlich über einen asynchronen Aufruf.

private void registerInBackground() {
    new AsyncTask() {
        @Override
        protected String doInBackground(Void... params) {
            String msg = "";
            try {
                if (gcm == null) {
                    gcm = GoogleCloudMessaging.getInstance(context);
                }
                regid = gcm.register(PROJECT_NUMBER);
                msg = "Device registered, registration ID=" + regid;

                storeRegistrationId(context, regid);
            } catch (IOException ex) {
                msg = "Error :" + ex.getMessage();
            }
            return msg;
        }

        @Override
        protected void onPostExecute(String msg) {
         Log.i(TAG, msg);
        }
    }.execute(null, null, null);
}

private void storeRegistrationId(Context context, String regId) {
    final SharedPreferences prefs = getGCMPreferences(context);
    int appVersion = getAppVersion(context);
    Log.i(TAG, "Saving regId on app version " + appVersion);
    SharedPreferences.Editor editor = prefs.edit();
    editor.putString(PROPERTY_REG_ID, regId);
    editor.putInt(PROPERTY_APP_VERSION, appVersion);
    editor.commit();
}
Das war dann auch „schon“ der notwendige Verwaltung-Overhead. Um ganz sauber zu sein, sollte man auch noch in der onResume-Methode der Activity die PlayServices abchecken, um sicher zu stellen, dass sie nicht zwischenzeitlich deinstalliert wurden:

@Override
protected void onResume() {
    super.onResume();
    checkPlayServices();
}

Test der App

Die App ist in der vorgestellten Form nicht im Emulator lauffähig und muss daher auf einem realen Gerät getestet werden. Dort sollte nach einem Druck auf den Button relativ schnell der Toast mit der Nachricht erscheinen – ganz unspektakulär.

Fazit

Wie bereits gesagt, dieses Beispiel ist weltfremd durch den Verzicht auf eine Server-Komponente. Ich hoffe aber, damit in aller Kürze demonstriert zu haben, was seitens der Android-App notwendig ist, um den Push-Dienst zu verwenden. Die relevanten Teile der Server-Komponente wären auch nur das Ansprechen des HTTP-Dienstes, was inhaltlich völlig analog zum hier dargestellten Zugriff innerhalb der App erfolgen würde.