Google Cloud Messaging with Payload

Google Cloud Messaging (GCM) is a free push notification service for Android handsets. After integrating GCM and collapsible messages into our Android applications in the two previous articles, let’s consider a second type of GCM push notifications: non-collapsible messages with payload.  As a reminder, there are two types of messages sent in GCM:

  1. Collapsible, “send-to-sync” messages, where new messages replace older ones in the sending queue. (i.e. the older messages are “collapsed”).
  2. Non-collapsible messages with payload, where every single message is delivered.

Each payload in non-collapsible messages is a unique content that has to be delivered and can’t be just replaced with a more recent message in the server sending queue. On the other hand, a  collapsible message can be a simple ping from the server to ask its mobile clients to sync their data.

When to use messages with payload? Instant Messaging (IM) applications come to mind. Another use case is when we need to include data into our push notifications to save our clients a round-trip to the server. An example use case would be sending daily/monthy online game rankings of top players. Instead of just notifying the Android clients to go to the server to get the information (send-to-sync), the data is included in the multicast messages themselves so that they can be directly consumed by the clients. We can easily see why collapsible messaging wouldn’t make much sense here, since we want our users to receive every single ranking we send them at the end of every week/month.

Let’s now jump into coding. As suggested in the two previous article, these code examples are modifications of the GCM Demo application available for download (client + server) and using the GCM helper library for Java.

Server Code

Creating a message with payload in server code is much like we did before for the collapsible type, except that we simply omit the collapse_key parameter.

// in imports

// Inside send method, construct a message with payload
Message message = new Message.Builder()
 .delayWhileIdle(true) // Wait for device to become active before sending.
 .addData( "rankings", "TOP 5 HIGH GAME SCORERS" )
 .addData( "1", "1. YankeeDoodle (15 Trophies)" )
 .addData( "2", "2. Billy_the_Kid (13 Trophies)" )
 .addData( "3", "3. Viper (10 Trophies)" )
 .addData( "4", "4. SilverSurfer (9 Trophies)" )
 .addData( "5", "5. Gypsy (8 Trophies)" )

Client Code

The client just retrieves the data by its keys:

// inside GCMIntentService
protected void onMessage(Context context, Intent intent) {
  // message with payload
  String message = intent.getStringExtra("rankings")  + "\n"
                 + intent.getStringExtra("1")+ "\n"
                 + intent.getStringExtra("2")+ "\n"
                 + intent.getStringExtra("3")+ "\n"
                 + intent.getStringExtra("4")+ "\n"
                 + intent.getStringExtra("5");

  displayMessage(context, message);
  // notifies user
  generateNotification(context, message);

This is how it looks like on an Android device:


These messages can contain a payload limit of 4K of data so they are not indicated for applications that need to send more than that, although it is theoretically possible to get around that limit with multiple messages and some assembly work  on the receiving Android client application. Another aspect to consider would be performance and impact on the handset’s batteries, since messages with payload are not as lightweight as their collapsible cousins. Regardless of the message type, all payload data must be String values.  So if we need to send some other type, it is up to our application to properly encode/decode the content.


This article is also available at JavaLobby.


, , , ,

  1. #1 by mark on December 13, 2012 - 8:46 pm

    You did a good job explaining some of the differences between send-to-sync and messages with payload, although I find that the distinction between the two can sometimes be blurry. Google also has more information on the difference in their docs now:

    Shameless Plug: I actually wrote a blog post yesterday shows how to send image data as part of the payload:

  2. #2 by oscar on February 25, 2015 - 9:58 pm

    Your awesome, simple and right to the point.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: