diff options
| -rw-r--r-- | docs/html/training/cloudsync/gcm.jd | 212 | ||||
| -rw-r--r-- | docs/html/training/cloudsync/index.jd | 10 | ||||
| -rw-r--r-- | docs/html/training/training_toc.cs | 4 |
3 files changed, 2 insertions, 224 deletions
diff --git a/docs/html/training/cloudsync/gcm.jd b/docs/html/training/cloudsync/gcm.jd deleted file mode 100644 index 6303372..0000000 --- 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 - -<div id="tb-wrapper"> - <div id="tb"> - <h2>This lesson teaches you to</h2> - <ol> - <li><a href="#multicast">Send Multicast Messages Efficiently</a></li> - <li><a href="#collapse">Collapse Messages that can Be Replaced</a></li> - <li><a href="#embed">Embed Data Directly in the GCM Message</a></li> - <li><a href="#react">React Intelligently to GCM Messages</a></li> - </ol> - <h2>You should also read</h2> - <ul> - <li><a href="http://developer.android.com/google/gcm/index.html">Google - Cloud Messaging for Android</a></li> - </ul> - </div> -</div> - -<p>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.</p> - -<p>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 <a - href="{@docRoot}google/gcm/demo.html">GCM demo app tutorial</a>.</p> - -<h2 id="multicast">Send Multicast Messages Efficiently</h2> -<p>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.</p> - -<p>Taking advantage of this functionality is easy. If you're using the <a - href="{@docRoot}google/gcm/gs.html#libs">GCM helper - library</a> for Java, simply provide a <code>List<String></code> collection of -registration IDs to the <code>send</code> or <code>sendNoRetry</code> method, -instead of a single registration ID.</p> - -<pre> -// This method name is completely fabricated, but you get the idea. -List<String> 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); -</pre> - -<p>For those implementing GCM support in a language other than Java, construct -an HTTP POST request with the following headers:</p> -<ul> - <li><code>Authorization: key=YOUR_API_KEY</code></li> - <li><code>Content-type: application/json</code></li> -</ul> - -<p>Then encode the parameters you want into a JSON object, listing all the -registration IDs under the key <code>registration_ids</code>. The snippet below -serves as an example. All parameters except <code>registration_ids</code> are -optional, and the items nested in <code>data</code> represent the user-defined payload, not -GCM-defined parameters. The endpoint for this HTTP POST message will be -<code>https://android.googleapis.com/gcm/send</code>.</p> - -<pre> -{ "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"] -} -</pre> - -<p>For a more thorough overview of the format of multicast GCM messages, see the <a - href="{@docRoot}google/gcm/gcm.html#send-msg">Sending - Messages</a> section of the GCM guide.</pre> - -<h2 id="collapse">Collapse Messages that Can Be Replaced</h2> -<p>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.</p> - -<p>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.</p> - -<p>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 <code>collapseKey(String key)</code> method.</p> - -<pre> -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(); -</pre> - -<p>If not using the helper library, simply add a variable to the -POST header you're constructing, with <code>collapse_key</code> as the field -name, and the string you're using for that set of updates as the value.</p> - - - -<h2 id="embed">Embed Data Directly in the GCM Message</h2> -<p>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: -<ul> - <li>The total data fits inside the 4kb limit.</li> - <li>Each message is important, and should be preserved.</li> - <li>It doesn't make sense to collapse multiple GCM messages into a single - "new data on the server" tickle.</li> -</ul> - -<p>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.</p> - -<p>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.</p> -<p>This strategy isn't appropriate for sending large amounts of data, for a few -reasons:</p> -<ul> - <li>Rate limits are in place to prevent malicious or poorly coded apps from spamming an - individual device with messages.</li> - <li>Messages aren't guaranteed to arrive in-order.</li> - <li>Messages aren't guaranteed to arrive as fast as you send them out. Even - if the device receives one GCM message a second, at a max of 1K, that's 8kbps, or - about the speed of home dial-up internet in the early 1990's. Your app rating - on Google Play will reflect having done that to your users.</p> -</ul> - -<p>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.</p> - -<h2 id="react">React Intelligently to GCM Messages</h2> -<p>Your application should not only react to incoming GCM messages, but react -<em>intelligently</em>. How to react depends on the context.</p> - -<h3>Don't be irritating</h3> -<p>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, -<a - href="http://developer.android.com/guide/topics/ui/notifiers/notifications.html#Updating">update - your existing notification</a> 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.</p> - -<h3>Sync smarter, not harder</h3> -<p>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:</p> -<ul> - <li><code>refresh</code> — Your app basically got told to request a dump of - every feed it follows. Your app would either need to send feed requests to 100 different servers, or - if you have an aggregator on your server, send a request to retrieve, bundle - and - transmit recent data from 100 different feeds, every time one updates.</li> - <li><code>refresh</code>, <code>feedID</code> — Better: Your app knows to check - a specific feed for updates.</li> - <li><code>refresh</code>, <code>feedID</code>, <code>timestamp</code> — - Best: If the user happened to manually refresh before the GCM message - arrived, the application can compare timestamps of the most recent post, and - determine that it <em>doesn't need to do anything</em>. -</ul> diff --git a/docs/html/training/cloudsync/index.jd b/docs/html/training/cloudsync/index.jd index cf7117c..082ace5 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.</p> -<p>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. +<p>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. </p> <h2>Lessons</h2> @@ -34,9 +32,5 @@ installing your application on a new device. <dd>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</dd> - <dt><strong><a href="gcm.html">Making the Most of Google Cloud Messaging</a></strong></dt> - <dd>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.</dd> </dl> diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index 0baef14..ccefe72 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 </a> </li> - <li><a href="<?cs var:toroot ?>training/cloudsync/gcm.html"> - Making the Most of Google Cloud Messaging - </a> - </li> </ul> <li><a href="<?cs var:toroot ?>training/cloudsave/conflict-res.html" description= |