Send notifications to clients

What is needed to setup the notifications ?

Android allows to send notifications to your client's devices by using the Google Cloud Messaging. Gindpubs uses this system to send notifications and start download of new content.

To enable your app to send notifications you need 3 basic things:

1. A Google API Project.
2. A notification receiver, also called GCM client.
3. A notification sender, also called GCM server.

Create a Google API Project.

Creating a Google API Project provides you with a KEY that is going to be used along with the app to identify the notifications that are received.

To create a project, please follow the official Google instructions: http://developer.android.com/google/gcm/gs.html

Enable Gindpubs to receive notifications.

The Gindpubs Framework is already enable to receive notifications, but, you have to modify the "sender_id" string in the strings.xml file in order to use you own Project ID.

IMPORTANT: By now ALL notifications will trigger the download of the latest issue.

Implement the GCM server.

In order to enable your server to send notifications, you have to send a POST request to https://android.googleapis.com/gcm/send including the registration IDs of the devices that use your application.

The registration IDs are stored on your server using the URL post_apns_token_url that is configured in the strings.xml on Gindpubs. You must modify the default URL to use your own. When a device uses your app, it will try to read this URL and do a request to register it's registration ID. This URL must be enabled in your server along with the functionality to save the registration ID on your database in case you want to store them for future notifications.

Google Cloud Messaging will then enqueue the notifications and start sending them as soon as the devices are ready.

The POST request must include some information on the HTTP headers, such as the KEY generated from the Google API Project, the content type and the content lenght. Besides the headers, the other information required is the registration IDs of all the devices that you want to send the notifications and some other data you want to include such as a "message". In Gindpubs the "message" is used as a text to describe the notification.

In short words, you need a POST request like the following:

Content-Type:application/json
Authorization:key=MYGOOGLEAPIPROJECTKEY
Content-length:123456789

{
  "registration_ids" : ["APA91bHun4MxP5egoKMwt2KZFBaFUH-1RYqx..."],
  "data" : {
      ...
  },
}

Example of GCM server implemented with PHP.

This example uses cURL to send the POST request and send the notifications to the GCM, which then will enqueue and send the notifications when the devices are turned on. For more information about cURL, visit: http://php.net/manual/es/book.curl.php.

$registrationIds = array("registrationId1", "registrationId2", "registrationId3");

$json = json_encode(array(
    "collapse_key" => "New Content Available",
    "data" => array("message" => "Magazine #23 Available Now!"),
    "registration_ids" => $registrationIds
));

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

// Open connection
$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);

In this example we use the registration IDs "registrationId1", "registrationId2" and "registrationId3". You could read these registration IDs from your database in your server.

Also, we use collapse_key which will group your notifications into a single one on the target device.

Remember to include the Authorization header with the corresponding API Key.

Finally, the $response variable will include the response from the GCM with the results of the notifications and a brief report of how many notifications were sent, how many failed and how many succeeded. You can read this variable, parse it and do whatever you want with it.