Using Google Cloud Messaging

Using Google Clould Messaging

ABaker is already prepared to receive notifications incoming from a GCM server. However, there are some properties you need to set in order for it to work as you need.

Requirements

• Install the Google Play Services SDK from http://developer.android.com/google/play-services/setup.html.
• You will need to create a Google API project which is required by the application in order to identify the notification sender. Please follow http://developer.android.com/google/gcm/gs.html to create your project and get your Project Number which will be used as the GCM Sender ID.
• You might also want to create an API Key needed by the GCM server to send the notifications and match with your Apps that used it's Project Number.

Implementing the client

As stated before, ABaker is already capable of handling notifications being sent by a GCM server, however you need to know the proper format of a notification and specify the Sender ID (Project Number) for it to work.

Start by opening ABaker and open the "res/values/strings.xml" file. Locate the sender_id property and change it to match your Project Number. That's it. Now you just need to know the format of the notification to allow ABaker to use it.

ABaker uses a BroadcastReceiver to receive the notifications. ABaker's implementation expects a properly formatted notification message to arrive to parse it and deliver it. The BroadcastReceiver uses two types of notifications, both are JSON formatted strings: Standard Notification and Background Download Notification.

The Standard Notification just requires the type, a title and a message as it will be displayed in the device's notification bar. A properly formatted Standard Notification message looks like the following:

{
	"notificationData" : {
		"type" : "standard-notification",
		"title" : "New Messages",
		"message" : "You have new messages."
	}
}

In this case, ABaker will use the title and message to create a textual notification to display in the notification bar of the device.

The Background Download Notification requires the type, and issueName. A properly formatted Background Download Notification looks like the following.

{
	"notificationData" : {
		"type" : "background-download",
		"issueName" : "latest"
	}
}

In this case, ABaker will check the issueName key, which is either "latest" or the name of the issue to be downloaded, such as "magazineJune2014". In the case of "latest", ABaker will download the latest issue ordered by the "date" field in the "shelf.json" previously downloaded.

When sending notifications from your GCM server, keep in mind the format required by ABaker for the process to work correctly.

Implementing the server

To implement the GCM server, you will need the API Key created before to sign your notifications and match the devices that use your application with the Sender ID properly configured.

The way the GCM works, your server implementation will not send the notifications directly to your clients devices, instead, you send the notifications to the GCM connection server, which will handle the notifications payload and deliver it to the devices.

For your GCM server to work and communicate with the GCM connection server, you must send the Registration IDs of all the devices you want to send the notifications to the connection server.

Now, how do you get the Registration IDs of all those devices? Easy, ABaker has a property called post_apns_token_url in the "res/values/strings.xml" file. This property is a URL endpoint that you can use to send the Registration ID generated for the device.

Don't worry, the send Registration ID request is done by ABaker automatically, just be sure that your implementation of that endpoint URL can handle HTTP POST request, and receive the following parameters:

• app_id: obtained from ABaker's app_id property in "res/values/strings.xml".
• user_id: obtained from the user's Google Account.
• apns_token: obtained automatically from ABaker when the device tries to register to GCM.
• device: in ABaker's case, this will always be ANDROID.

That endpoint URL (also implemented by you) for the Registration IDs needs to store at least the apns_token value (maybe in a database) sent by ABaker in order for your GCM server to send that information to the GCM connection server.

To stablish the communication between your GCM server and the GCM connection server, you must send a POST request with the formatted notification data, also including in the same request the following headers:

• Authorization: key=MY_PROJECT_API_KEY
• Content-Type: application/json
• Content-length: BYTES_LENGTH

Authorization is used to sign your request to match your Project Number. Content-Type is application/json because you will be sending a JSON formatted string. And Content-length is the size of the content itself in bytes.

With the notification data payload, the proper HTTP headers and the Registration IDs to send the notifications to, you are ready to start sending notifications to your clients.

GCM server implementation code example

Take a look at this example code in PHP that uses the settings explained above to send notifications:

First, define variables (or constants if you will) for your project's API Key and the GCM connection server endpoint:

$ANDROID_API_KEY = 'AIzaSyAJ1C-nWX6IWdkxa2FDu3-VgH7FFwUHlmc';
$androidEndpoint = 'https://android.googleapis.com/gcm/send';

Second, build your Registration IDs array to include all the IDs you want to send the notifications to, in this example we are using hardcoded and non-working Registration IDs. You might want to obtain these from a database or wherever you are storing the Registration IDs:

$registrationIds = array(
	'APA91bGJ55dDnrloHtMwCxdpL5_6TDQ9WSHb_VxzRrUFNmYDxjE1OrLrnN13PImx6OpbgtkCW6WDaisBybsen7RG0QrZoz6gIYSTS4IDkUiWy0LlW_KrdpaA8T7RPTe8_VAN31sN3n2wN4LlVVCbhNvwcMxsKJO8KW',
	'APA91bGJ55dDnrloHtMwCxdpL5_6TDQ9WSHb_VxzRrUFNmYDxjE1OrLrnN13PImx6OpbgtkCW6WDaisBybsen7RG0QrZoz6gIYSTS4IDkUiWy0LlW_KrdpaA8T7RPTe8_VAN31sN3n2wN4LlVVCbhNvwcMxsNLO2CE'
);

Third, build your JSON-formatted notification data payload, in this case we use the "collapse_key" to group multiple notifications received by the device:

$json = json_encode(array(
	"collapse_key" => "New Magazine Available",
	"data" => array(
		"notificationData" => array(
			'type' => 'standard-notification',
			'title' => 'New Messages',
			'message' => 'You have new messages'
		)),
	"registration_ids" => $registrationIds
));

Fourth, build your HTTP headers needed for the GCM connection server:

$headers = array(
	'Authorization: key=' . $ANDROID_API_KEY,
	'Content-Type: application/json',
	'Content-length: ' . strlen($json)
);

Fifth, send the request. In this example we use cURL (http://curl.haxx.se/libcurl/php/):

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $androidEndpoint);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
$response = curl_exec($ch);
curl_close($ch);

Sixth, print the response of the GCM connection server to verify the results:

var_dump($response);

Testing the process

To test the notifications process you need to build and run ABaker with the proper Sender ID (Project Number) set in the "res/values/strings.xml". When running, ABaker will generate the Registration ID and try to send it to the post_apns_token_url URL also configured in "res/values/strings.xml" via POST request.

Another method for knowing your Registration ID when running the application is checking the logs and filtering by "Registration ID". You will see the generated Registration ID.

After doing that, implement the code example explained above and execute it either in a web browser or a console with the command php my_gcm_server_script.php.

If you did everything correctly, you will see the notification arrived and showed up in your device's notification bar.