From 4e9c18f2f64aaa769588151aac5e70174861a84b Mon Sep 17 00:00:00 2001 From: Eric Gilmore Date: Wed, 3 Jun 2015 09:47:21 -0700 Subject: Removing traces out outdated GCM training class. Related redirects in change 702766. Change-Id: If9939796e01f9859511757b93482c643e15c57a7 --- docs/html/training/cloudsync/gcm.jd | 212 ---------------------------------- docs/html/training/cloudsync/index.jd | 10 +- docs/html/training/training_toc.cs | 4 - 3 files changed, 2 insertions(+), 224 deletions(-) delete mode 100644 docs/html/training/cloudsync/gcm.jd diff --git a/docs/html/training/cloudsync/gcm.jd b/docs/html/training/cloudsync/gcm.jd deleted file mode 100644 index 630337260900..000000000000 --- a/docs/html/training/cloudsync/gcm.jd +++ /dev/null @@ -1,212 +0,0 @@ -page.title=Making the Most of Google Cloud Messaging - -trainingnavtop=true - -@jd:body - -
- -
- -

Google Cloud Messaging (GCM) is a free service for sending -messages to Android devices. GCM messaging can greatly enhance the user -experience. Your application can stay up to date without wasting battery power -on waking up the radio and polling the server when there are no updates. Also, -GCM allows you to attach up to 1,000 recipients to a single message, letting you easily contact -large user bases quickly when appropriate, while minimizing the work load on -your server.

- -

This lesson covers some of the best practices -for integrating GCM into your application, and assumes you are already familiar -with basic implementation of this service. If this is not the case, you can read the GCM demo app tutorial.

- -

Send Multicast Messages Efficiently

-

One of the most useful features in GCM is support for up to 1,000 recipients for -a single message. This capability makes it much easier to send out important messages to -your entire user base. For instance, let's say you had a message that needed to -be sent to 1,000,000 of your users, and your server could handle sending out -about 500 messages per second. If you send each message with only a single -recipient, it would take 1,000,000/500 = 2,000 seconds, or around half an hour. -However, attaching 1,000 recipients to each message, the total time required to -send a message out to 1,000,000 recipients becomes (1,000,000/1,000) / 500 = 2 -seconds. This is not only useful, but important for timely data, such as natural -disaster alerts or sports scores, where a 30 minute interval might render the -information useless.

- -

Taking advantage of this functionality is easy. If you're using the GCM helper - library for Java, simply provide a List collection of -registration IDs to the send or sendNoRetry method, -instead of a single registration ID.

- -
-// This method name is completely fabricated, but you get the idea.
-List regIds = whoShouldISendThisTo(message);
-
-// If you want the SDK to automatically retry a certain number of times, use the
-// standard send method.
-MulticastResult result = sender.send(message, regIds, 5);
-
-// Otherwise, use sendNoRetry.
-MulticastResult result = sender.sendNoRetry(message, regIds);
-
- -

For those implementing GCM support in a language other than Java, construct -an HTTP POST request with the following headers:

- - -

Then encode the parameters you want into a JSON object, listing all the -registration IDs under the key registration_ids. The snippet below -serves as an example. All parameters except registration_ids are -optional, and the items nested in data represent the user-defined payload, not -GCM-defined parameters. The endpoint for this HTTP POST message will be -https://android.googleapis.com/gcm/send.

- -
-{ "collapse_key": "score_update",
-   "time_to_live": 108,
-   "delay_while_idle": true,
-   "data": {
-       "score": "4 x 8",
-       "time": "15:16.2342"
-   },
-   "registration_ids":["4", "8", "15", "16", "23", "42"]
-}
-
- -

For a more thorough overview of the format of multicast GCM messages, see the Sending - Messages section of the GCM guide. - -

Collapse Messages that Can Be Replaced

-

GCM messages are often a tickle, telling the mobile application to -contact the server for fresh data. In GCM, it's possible (and recommended) to -create collapsible messages for this situation, wherein new messages replace -older ones. Let's take the example -of sports scores. If you send out a message to all users following a certain -game with the updated score, and then 15 minutes later an updated score message -goes out, the earlier one no longer matters. For any users who haven't received -the first message yet, there's no reason to send both, and force the device to -react (and possibly alert the user) twice when only one of the messages is still -important.

- -

When you define a collapse key, when multiple messages are queued up in the GCM -servers for the same user, only the last one with any given collapse key is -delivered. For a situation like with sports scores, this saves the device from -doing needless work and potentially over-notifying the user. For situations -that involve a server sync (like checking email), this can cut down on the -number of syncs the device has to do. For instance, if there are 10 emails -waiting on the server, and ten "new email" GCM tickles have been sent to the -device, it only needs one, since it should only sync once.

- -

In order to use this feature, just add a collapse key to your outgoing -message. If you're using the GCM helper library, use the Message class's collapseKey(String key) method.

- -
-Message message = new Message.Builder(regId)
-    .collapseKey("game4_scores") // The key for game 4.
-    .ttl(600) // Time in seconds to keep message queued if device offline.
-    .delayWhileIdle(true) // Wait for device to become active before sending.
-    .addPayload("key1", "value1")
-    .addPayload("key2", "value2")
-    .build();
-
- -

If not using the helper library, simply add a variable to the -POST header you're constructing, with collapse_key as the field -name, and the string you're using for that set of updates as the value.

- - - -

Embed Data Directly in the GCM Message

-

Often, GCM messages are meant to be a tickle, or indication to the device -that there's fresh data waiting on a server somewhere. However, a GCM message -can be up to 4kb in size, so sometimes it makes sense to simply send the -data within the GCM message itself, so that the device doesn't need to contact the -server at all. Consider this approach for situations where all of the -following statements are true: -

- -

For instance, short messages or encoded player moves -in a turn-based network game are examples of good use-cases for data to embed directly -into a GCM message. Email is an example of a bad use-case, since messages are -often larger than 4kb, -and users don't need a GCM message for each email waiting for them on -the server.

- -

Also consider this approach when sending -multicast messages, so you don't tell every device across your user base to hit -your server for updates simultaneously.

-

This strategy isn't appropriate for sending large amounts of data, for a few -reasons:

- - -

When used appropriately, directly embedding data in the GCM message can speed -up the perceived speediness of your application, by letting it skip a round trip -to the server.

- -

React Intelligently to GCM Messages

-

Your application should not only react to incoming GCM messages, but react -intelligently. How to react depends on the context.

- -

Don't be irritating

-

When it comes to alerting your user of fresh data, it's easy to cross the line -from "useful" to "annoying". If your application uses status bar notifications, -update - your existing notification instead of creating a second one. If you -beep or vibrate to alert the user, consider setting up a timer. Don't let the -application alert more than once a minute, lest users be tempted to uninstall -your application, turn the device off, or toss it in a nearby river.

- -

Sync smarter, not harder

-

When using GCM as an indicator to the device that data needs to be downloaded -from the server, remember you have 4kb of metadata you can send along to -help your application be smart about it. For instance, if you have a feed -reading app, and your user has 100 feeds that they follow, help the device be -smart about what it downloads from the server! Look at the following examples -of what metadata is sent to your application in the GCM payload, and how the application -can react:

- diff --git a/docs/html/training/cloudsync/index.jd b/docs/html/training/cloudsync/index.jd index cf7117c3a12d..082ace5af31f 100644 --- a/docs/html/training/cloudsync/index.jd +++ b/docs/html/training/cloudsync/index.jd @@ -21,10 +21,8 @@ helps you build rich cloud-enabled apps that sync their data to a remote web service, making sure all your devices always stay in sync, and your valuable data is always backed up to the cloud.

-

This class covers different strategies for cloud enabled applications. It -covers syncing data with the cloud using your own back-end web application, and -backing up data using the cloud so that users can restore their data when -installing your application on a new device. +

This class covers strategies for backing up data using the cloud so that +users can restore their data when installing your application on a new device.

Lessons

@@ -34,9 +32,5 @@ installing your application on a new device.
Learn how to integrate the Backup API into your Android Application, so that user data such as preferences, notes, and high scores update seamlessly across all of a user's devices
-
Making the Most of Google Cloud Messaging
-
Learn how to efficiently send multicast messages, react intelligently to - incoming Google Cloud Messaging (GCM) messages, and use GCM messages to - efficiently sync with the server.
diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index 0baef147431b..ccefe7267cf9 100644 --- a/docs/html/training/training_toc.cs +++ b/docs/html/training/training_toc.cs @@ -596,10 +596,6 @@ include the action bar on devices running Android 2.1 or higher." Using the Backup API -
  • - Making the Most of Google Cloud Messaging - -