Merge "Removing traces out outdated GCM training class." into mnc-preview-docs
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 @@
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 @@
<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 @@
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=