Update to Google Cloud Messaging document

chrome/common/extensions/docs/templates/articles/cloudMessaging.html

Index: chrome/common/extensions/docs/templates/articles/cloudMessaging.html
diff --git a/chrome/common/extensions/docs/templates/articles/cloudMessaging.html b/chrome/common/extensions/docs/templates/articles/cloudMessaging.html
index a50500fc9902ded75f801191830711b405396406..bc36cb9b651b961f692ff15efd8a5e17ba4c780b 100644
--- a/chrome/common/extensions/docs/templates/articles/cloudMessaging.html
+++ b/chrome/common/extensions/docs/templates/articles/cloudMessaging.html
@@ -1,383 +1,344 @@
-<meta name="doc-family" content="apps">
-<h1 id="gcm">Google Cloud Messaging</h1>
-
-<p>Google Cloud Messaging (GCM) is a service for both Android-powered device and
-Chrome instances to send and receive message data from servers.
-The <a href="gcm">chrome.gcm API</a> allows the Chrome apps or extensions
-to access the GCM service for the signed-in Chrome users.
-The service works even if an app or extension isn't currently running.
-For example, calendar updates could be pushed
-to users even when their calendar app isn't open. </p>
-
-<p>To use both API and service, you must agree to the <a href="https://developers.google.com/terms/">Google APIs Terms of
-Service</a> and <a href="https://developers.google.com/cloud/terms/">Google Cloud Platform Terms
-of Service</a>.</p>
-
-<p>This document describes how to set up and use GCM. For additional information
-see the reference documentation for the <a href="gcm">GCM Chrome API</a> and
-the <a href="http://developer.android.com/google/gcm/index.html">GCM Service</a>. To get
-help with GCM or to give us feedback, please see
-<a href="#feedback">Feedback</a>.</p>
-
-<p class="note"><strong>API Samples</strong>: Want to play with the code? Check out the
-<a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/samples/gcm-notifications">gcm-notifications</a>
-sample.</p>
-
-<h2 id="enable_gcm">Enable GCM</h2>
-
-<p>To use GCM for your app or extension, do the following:</p>
-
-<ol>
-<li>Upload your app or extension client to the <a href="https://developers.google.com/chrome/web-store/docs/publish">Chrome Web
-Store</a>.</li>
-<li>A user installs your app or extension.</li>
-<li>Your app or extension client requests a registration ID using $(ref:gcm.register)
-function and sends this ID to your server together with information
-identifying the user. For more details, please see <a href="#obtain_registration_id">Obtain registration
-ID</a>.</li>
-</ol>
-
-<h2 id="receive_a_message">Receive a message</h2>
-
-<p>At a glance, receiving a message works like this:</p>
-
-<ol>
-<li>Your app or extension client should register a handler to receive the
-$(ref:gcm.onMessage) event.</li>
-<li>When your server sends a message to the user, it specifies all of the
-registration IDs that are related to that user and passes the message to the
-GCM service.</li>
-<li>GCM servers route the message to all instances of Chrome running apps or
-extensions with one of the registration IDs.</li>
-<li>When the message arrives on the client, Chrome starts the app or extension,
-if it is not already running, and calls the registered handler to process the
-message.</li>
-</ol>
-
-<p>For more details, please see <a href="#receive_messages">Receive messages</a>.</p>
-
-<h2 id="send_a_message">Send a message</h2>
-
-<p>At a glance, sending a message works like this:</p>
-
-<ol>
-<li>Your app or extension generates a unique message ID, so that it is possible
-to find out which message failed to be queued or delivered.</li>
-<li>Your app or extension calls $(ref:gcm.send) function with an object containing
-message ID, destination ID that identifies the server, and data that consist
-of a list of key value pairs. In this step you can also provide an optional
-time-to-live for the message.</li>
-<li>The callback passed to $(ref:gcm.send) function will be called to notify the
-result. Your app or extension should check $(ref:runtime.lastError) to find out if
-the message has been successfully queued for delivery. Please refer to <a href="#error_reference">Error
-reference</a> for possible error codes that could be
-returned.</li>
-<li>In cases that the queued message could not be delivered to the GCM server,
-like network error, a $(ref:gcm.onSendError) event will be fired. Your app or
-extension can listen to this event and react to it, e.g. by trying to resend
-the message. Please refer to <a href="#error_reference">Error reference</a> for
-possible error codes that could be returned.</li>
-</ol>
-
-<p>For more details, please see <a href="#send_messages">Send messages</a>.</p>
-
-<p class="note"><strong>Display messages in rich notifications format:</strong><br>
-GCM and rich notifications API are a natural fit;
-Use GCM to send and receive message data; use rich notifications to display
-the data in the user's system tray
-(see <a href="inform_users">Keep Users Informed</a>).</p>
-
-<h2 id="set_up_project">Set up project</h2>
-
-<h3 id="create_google_api_project">Create Google API project</h3>
-
-<ol>
-<li>Login to the <a href="https://cloud.google.com/console/project">Google Developers
-Console</a> using the same Google Account that you will use to upload your app or extension.</li>
-<li>If you haven't created an API project yet, click <strong>Create Project</strong>.</li>
-<li>Supply a project name and click <strong>Create</strong>.</li>
-<li>Once the project has been created, a page appears that displays your project
-number. For example, <strong>Project Number: 670330094152</strong>.</li>
-<li>Copy down your project number. You will use it later on as the GCM sender ID.</li>
-</ol>
-
-<h3 id="enable_the_gcm_service">Enable the GCM service</h3>
-
-<ol>
-<li>In the sidebar on the left, select <strong>APIs &amp; auth</strong>.</li>
-<li>In the displayed list of APIs, turn the <strong>Google Cloud Messaging for
-Android</strong> toggle to ON.</li>
-</ol>
-
-<h2 id="set_up_chrome_app_or_extension">Set up Chrome App or Extension</h2>
-
-<h3 id="add_permission_to_manifest">Add permission to manifest</h3>
-
-<p>To use the gcm service, you must declare the <code>gcm</code> permission in
-<code>manifest.json</code>.</p>
-
-<pre data-filename="manifest.json"><code>
-"permissions": [
-  "gcm", "storage", ...
-]
-</code></pre>
-
-<p>Please note that the <code>storage</code> permission is also provided here because the
-sample codes below needs to persist some data via the
-<a href="storage">chrome.storage</a> API.</p>
-
-<h2 id="write_chrome_app_or_extension">Write Chrome App or Extension</h2>
-
-<h3 id="obtain_registration_id">Obtain registration ID</h3>
-
-<p>Your app or extension needs to register with GCM servers before it can receive
-messages. When an app or extension registers, it receives a registration ID.
-This is achieved by calling $(ref:gcm.register) and specifying a list of senders
-identified by project numbers from Google Developers Console. Your app or
-extension should pass a callback function to verify that the registration was
-successful. If successful, the received registration ID should be sent back to
-your application server in a secure way, for example, via https. Otherwise, your
-app or extension should handle the error identified by
-<code>chrome.runtime.lastError</code> and retry later.</p>
-
-<p>If your app or extension wishes to receive messages from the different senders,
-it can call $(ref:gcm.register) again with the new sender list and the new
-registration ID will be returned.</p>
-
-<pre data-filename="background.js"><code>
-function registerCallback(registrationId) {
-  if (chrome.runtime.lastError) {
-    // When the registration fails, handle the error and retry the
-    // registration later.
-    return;
-  }
-
-  // Send the registration ID to your application server.
-  sendRegistrationId(function(succeed) {
-    // Once the registration ID is received by your server,
-    // set the flag such that register will not be invoked
-    // next time when the app starts up.
-    if (succeed)
-      chrome.storage.local.set({registered: true});
-  });
-}
-
-function sendRegistrationId(callback) {
-  // Send the registration ID to your application server
-  // in a secure way.
-}
-
-chrome.runtime.onStartup.addListener(function() {
-  chrome.storage.local.get("registered", function(result) {
-    // If already registered, bail out.
-    if (result["registered"])
-      return;
-
-    // Up to 100 senders are allowed.
-    var senderIds = ["Your-Sender-ID"];
-    chrome.gcm.register(senderIds, registerCallback);
-  });
-});
-</code></pre>
-
-<p>If your app or extension is installed in different profiles and/or in different
-Chrome instances, each of them will receive a different registration ID.</p>
-
-<p>Your app or extension could call $(ref:gcm.unregister) to revoke the registration ID.
-The unregistration should only be done in rare cases, such as if your app or
-extension does not want to receive further messages, or the registration ID is
-suspected to be compromised.</p>
-
-<pre data-filename="background.js"><code>
-function unregisterCallback() {
-  if (chrome.runtime.lastError) {
-    // When the unregistration fails, handle the error and retry
-    // the unregistration later.
-    return;
-  }
-}
-
-chrome.gcm.unregister(unregisterCallback);
-</code></pre>
-
-<p>Your app or extension is automatically unregistered from the GCM service when a
-user uninstalls it.</p>
-
-<h3 id="receive_messages">Receive messages</h3>
-
-<p>When your server sends a message to the user, it specifies all of the
-registration IDs that are related to that user and passes the message to the GCM
-service. GCM servers route the message to all instances of Chrome running apps
-or extensions with one of the registration IDs. If your app or extension has
-been installed in more than one profiles in a single Chrome instance, all of
-them can receive messages independently based on their unique registration IDs.</p>
-
-<p>Messages from the server are delivered via the $(ref:gcm.onMessage) event. Your app
-or extension must register a handler to receive this event.</p>
-
-<pre data-filename="background.js"><code>
-chrome.gcm.onMessage.addListener(function(message) {
-  // A message is an object with a data property that
-  // consists of key-value pairs.
-});
-</code></pre>
-
-<p>As long as Chrome is running, even if the extension or app is not running, it is
-woken up to deliver a message.</p>
-
-<h3 id="send_messages">Send messages</h3>
-
-<p>To send messages upstream, your app or extension should call $(ref:gcm.send) with an
-object containing:</p>
-
-<ul>
-<li>Message ID that identifies the message when it fails to be queued or
-delivered. The message ID can be any kind of string. However, it is
-recommended to stay unique across the lifetime of your app or extension, even
-after it restarts. If you use the same message ID, there may be a chance that
-the previous message gets overridden. If an auto-increment counter is used to
-create the message ID, your app or extension should persist the counter value
-via <a href="storage">chrome.storage</a> API and restore it when the app
-reloads.</li>
-<li>Destination ID that identifies the server. This is the project number from the
-Google Developers Console plus the suffix "@gcm.googleapis.com".</li>
-<li>Data that consist of a list of string-to-string key value pairs (up to 4KB
-total).</li>
-<li>Time-to-live (TTL, optional). This property value must be a duration from 0 to
-2,419,200 seconds (4 weeks) and it corresponds to the maximum period of time
-for which GCM will store and try to deliver the message. If this property is
-not set, it is default to the maximum value. When a TTL is set to 0, GCM will
-try to deliver the message immediately. If the immediate effort fails, the
-message will be discarded.</li>
-</ul>
-
-<p>When the callback passed in $(ref:gcm.send) is called without runtime error, it does
-not mean that the message was already delivered to the GCM server. Rather, it
-means that it was queued for delivery. If the message fails to reach the
-destination within the specified TTL period, for example due to network error,
-the $(ref:gcm.onSendError) will be fired.</p>
-
-<pre data-filename="background.js"><code>
-// Substitute your own sender ID here. This is the project
-// number you got from the Google Developers Console.
-var senderId = "Your-Sender-ID";
-
-// Make the message ID unique across the lifetime of your app.
-// One way to achieve this is to use the auto-increment counter
-// that is persisted to local storage.
-
-// Message ID is saved to and restored from local storage.
-var messageId = 0;
-chrome.storage.local.get("messageId", function(result) {
-  if (chrome.runtime.lastError)
-    return;
-  messageId = parseInt(result["messageId"]);
-  if (isNaN(messageId))
-    messageId = 0;
-});
-
-// Sets up an event listener for send error.
-chrome.gcm.onSendError.addListener(sendError);
-
-// Returns a new ID to identify the message.
-function getMessageId() {
-  messageId++;
-  chrome.storage.local.set({messageId: messageId});
-  return messageId.toString();
-}
-
-function sendMessage() {
-  var message = {
-    messageId: getMessageId(),
-    destinationId: senderId + "@gcm.googleapis.com",
-    timeToLive: 86400,    // 1 day
-    data: {
-      "key1": "value1",
-      "key2": "value2"
-    }
-  };
-  chrome.gcm.send(message, function(messageId) {
-    if (chrome.runtime.lastError) {
-      // Some error occurred. Fail gracefully or try to send
-      // again.
-      return;
-    }
-
-    // The message has been accepted for delivery. If the message
-    // can not reach the destination, onSendError event will be
-    // fired.
-  });
-}
-
-function sendError(error) {
-  console.log("Message " + error.messageId +
-      " failed to be sent: " + error.errorMessage);
-}
-</code></pre>
-
-<h3 id="messages_deleted_event">Messages deleted event</h3>
-
-<p>GCM will store up to 100 non-collapsible messages. After that, all messages are
-discarded from GCM, and an event $(ref:gcm.onMessagesDeleted) will be fired, which
-tells the client that it falls behind. Your app or extension should respond by
-syncing with your application server to recover the discarded messages.</p>
-
-<pre data-filename="background.js"><code>
-chrome.gcm.onMessagesDeleted.addListener(messagesDeleted);
-
-function messagesDeleted() {
-  // All messages have been discarded from GCM. Sync with
-  // your application server to recover from the situation.
-}
-</code></pre>
-
-<h3 id="collapsible_messages">Collapsible messages</h3>
-
-<p>GCM messages are often a tickle, telling the app or extension to contact the
-server for fresh data. In GCM, it's possible to create collapsible messages for
-this situation, wherein new messages replace older ones. When a collapse key is
-provided and multiple messages are queued up in the GCM servers for the same
-user, only the last one with any given collapse key is delivered to your app or
-extension. As a result the <code>message</code> object passed to the $(ref:gcm.onMessage) event
-will contain a <code>collapseKey</code>field. For more details about sending collapsible
-messages, please refer to <a href="http://developer.android.com/google/gcm/adv.html#collapsible">GCM Advance
-Topics</a>.</p>
-
-<h2 id="publish_your_app">Publish your app</h2>
-
-<p>To use the GCM service, you must publish your app in the <a href="https://developers.google.com/chrome/web-store/docs/publish">Chrome Web
-Store</a>.</p>
-
-<h2 id="error_reference">Error reference</h2>
-
-<p>An error could occur when a gcm API function is called. Your app or extension
-should check $(ref:runtime.lastError) for more information in your callback. The
-error code will also be passed as a parameter to $(ref:gcm.onSendError) event.</p>
-
-<p>Here's a brief summary of the gcm errors:</p>
-
-<ul>
-<li><strong>Function was called with invalid parameters</strong>: this could happen when gcm
-functions are called with bad parameters.</li>
-<li><strong>Profile was not signed in</strong>: this could happen when gcm functions are called
-from a profile that was not signed in.</li>
-<li><strong>Asynchronous operation is pending</strong>: this could happen when certain gcm
-function is called again without waiting for the callback passed in previous
-function to be called.</li>
-<li><strong>Network error occurred</strong>: this could happen when GCM server fails to reach
-due to network problem, like losing Internet connection.</li>
-<li><strong>Server error occurred</strong>: this could happen when GCM server fails to reach
-due to server problem, like server busy.</li>
-<li><strong>Time-to-live exceeded</strong>: this could happen when a message could not be
-delivered within the specific time-to-live period.</li>
-<li><strong>Unknown error occurred</strong>: this could happen due to any other internal
-errors.</li>
-</ul>
-
-<h2 id="feedback">Feedback</h2>
-
-<p>You can provide feedback about Google Cloud Messaging and the
-<a href="gcm">chrome.gcm API</a> through
-the Google Group <a href="https://groups.google.com/forum/#!forum/gcm-for-chrome-feedback">GCM for Chrome
-Feedback</a>.
-Use this group to ask for help, file bug reports, and request features.</p>
+<meta name="doc-family" content="apps">
+<h1 id="gcm">Google Cloud Messaging</h1>
+
+<p>Google Cloud Messaging (GCM) is a service for both Android-powered devices and
+Chrome instances to send and receive message data from servers. The
+<a href="gcm.html">chrome.gcm</a> API allows the Chrome apps or extensions to access
+the GCM service for the signed-in Chrome users. The service works even if an app
+or extension isn't currently running. For example, calendar updates could be
+pushed to users even when their calendar app isn't open. </p>
+
+<p>To use both API and service, you must agree to the <a href="https://developers.google.com/terms/">Google APIs Terms of
+Service</a> and <a href="https://developers.google.com/cloud/terms/">Google Cloud Platform Terms
+of Service</a>.</p>
+
+<p>This document describes how to set up and use GCM. For additional information
+see the reference documentation for the <a href="gcm.html">chrome.gcm</a> API and
+the <a href="http://developer.android.com/google/gcm/index.html">GCM Service</a>. To get
+help with GCM or to give us feedback, please see
+<a href="#feedback">Feedback</a>.</p>
+
+<p class="note"><strong>API Samples</strong>: Want to play with the code? Check out the
+<a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/samples/gcm-notifications">gcm-notifications</a>
+sample.</p>
+
+<h2 id="set_up_project">Set up project</h2>
+
+<h3 id="create_google_api_project">Create Google API project</h3>
+
+<ol>
+<li>Login to the <a href="https://cloud.google.com/console/project">Google Developers
+Console</a> using the same Google
+Account that you will use to upload your app or extension.</li>
+<li>If you haven't created an API project yet, click <strong>Create Project</strong>.</li>
+<li>Supply a project name and click <strong>Create</strong>.</li>
+<li>Once the project has been created, a page appears that displays your project
+number. For example, <strong>Project Number: 670330094152</strong>.</li>
+<li>Copy down your project number. You will use it later on as the GCM sender ID.</li>
+</ol>
+
+<h3 id="enable_the_gcm_service">Enable the GCM service</h3>
+
+<ol>
+<li>In the sidebar on the left, select <strong>APIs</strong> under <strong>APIs &amp; auth</strong>.</li>
+<li>In the displayed list of APIs, turn the <strong>Google Cloud Messaging for
+Android</strong> toggle to ON.</li>
+</ol>
+
+<h2 id="set_up_chrome_app_or_extension">Set up Chrome App or Extension</h2>
+
+<h3 id="add_permission_to_manifest">Add permission to manifest</h3>
+
+<p>To use the gcm service, you must declare the <code>gcm</code> permission in
+<code>manifest.json</code>.</p>
+
+<pre data-filename="manifest.json"><code>
+"permissions": [
+  "gcm", ... // Other permissions, like "storage"
+]
+</code></pre>
+
+<p>Please note that running sample code below requires the <code>storage</code> permission as
+well in order to persist some data via the <a href="storage.html">chrome.storage</a>
+API.</p>
+
+<h2 id="write_chrome_app_or_extension">Write Chrome App or Extension</h2>
+
+<h3 id="obtain_gcm_registration_id">Obtain GCM registration ID</h3>
+
+<p>Your app or extension needs to register with GCM servers before it can receive
+messages. This is achieved by calling $(ref:gcm.register) and passing a list of
+senders identified by project numbers from <a href="https://cloud.google.com/console/project">Google Developers
+Console</a>. Your app or extension should
+pass a callback function to verify if the registration succeeded or not, by
+checking whether the error is set on <code>chrome.runtime.lastError</code> property. If the
+registration is successful, an app or extension receives a registration ID,
+which should be sent back to your application server in a secure way, for
+example, via https. Otherwise, your app or extension should handle the error
+identified by <code>chrome.runtime.lastError</code> and retry later.</p>
+
+<p>If your app or extension wishes to receive messages from the different senders,
+it can call $(ref:gcm.register) again with the new sender list and the new
+registration ID will be returned.</p>
+
+<pre data-filename="background.js"><code>
+function registerCallback(registrationId) {
+  if (chrome.runtime.lastError) {
+    // When the registration fails, handle the error and retry the
+    // registration later.
+    return;
+  }
+
+  // Send the registration ID to your application server.
+  sendRegistrationId(function(succeed) {
+    // Once the registration ID is received by your server,
+    // set the flag such that register will not be invoked
+    // next time when the app starts up.
+    if (succeed)
+      chrome.storage.local.set({registered: true});
+  });
+}
+
+function sendRegistrationId(callback) {
+  // Send the registration ID to your application server
+  // in a secure way.
+}
+
+chrome.runtime.onStartup.addListener(function() {
+  chrome.storage.local.get("registered", function(result) {
+    // If already registered, bail out.
+    if (result["registered"])
+      return;
+
+    // Up to 100 senders are allowed.
+    var senderIds = ["Your-Sender-ID"];
+    chrome.gcm.register(senderIds, registerCallback);
+  });
+});
+</code></pre>
+
+<p>If your app or extension is installed in different profiles and/or in different
+Chrome instances, each of them will receive a different registration ID.</p>
+
+<p>Your app or extension could call $(ref:gcm.unregister) to revoke the registration ID.
+The unregistration should only be done in rare cases, such as if your app or
+extension does not want to receive further messages, or the registration ID is
+suspected to be compromised.</p>
+
+<pre data-filename="background.js"><code>
+function unregisterCallback() {
+  if (chrome.runtime.lastError) {
+    // When the unregistration fails, handle the error and retry
+    // the unregistration later.
+    return;
+  }
+}
+
+chrome.gcm.unregister(unregisterCallback);
+</code></pre>
+
+<p>Your app or extension is automatically unregistered from the GCM service when a
+user uninstalls it.</p>
+
+<h3 id="receive_messages">Receive messages</h3>
+
+<p>When your server wants to send a message to the user, it needs to connect to a
+GCM connection server in one of two ways as described

[mkearney1, 2014/10/02 00:52:49]

Replace 'here' with something more descriptive, like:

"as described in the Android <a href="">Implementing GCM Server</a> document"

We will change this link to generic docs once they exist.

[jianli, 2014/10/14 18:00:43]

Done.

+<a href="http://developer.android.com/google/gcm/server.html">here</a>. The message
+specifies all of the registration IDs that are related to that user. When the
+GCM server receives the message, it routes the message to all instances of
+Chrome running apps or extensions with one of the registration IDs. If your app
+or extension has been installed in more than one profiles in a single Chrome
+instance, all of them can receive messages independently based on their unique
+registration IDs.</p>
+
+<p>Messages from the server are delivered via the $(ref:gcm.onMessage) event. Your app
+or extension must register a handler to receive this event.</p>
+
+<pre data-filename="background.js"><code>
+chrome.gcm.onMessage.addListener(function(message) {
+  // A message is an object with a data property that
+  // consists of key-value pairs.
+});
+</code></pre>
+
+<p>As long as Chrome is running, even if the extension or app is not running, it is
+woken up to deliver a message.</p>
+
+<h3 id="send_messages">Send messages</h3>
+
+<p>In addition to delivering push messages from your server to the client, the GCM
+supports sending upstream messages from the client to your server. Your server

[mkearney1, 2014/10/02 00:52:49]

Same as comment above. Replace 'here' with something more descriptive, like:

"as described in the Android <a href="GCM Cloud Connection Server"></a>
document"

We will change this link to generic docs once they exist.

[jianli, 2014/10/14 18:00:43]

Done.

+should be set up to connect to GCM Cloud Connection Server as described
+<a href="http://developer.android.com/google/gcm/ccs.html">here</a>.</p>
+
+<p>To send messages upstream, your app or extension should call $(ref:gcm.send) with an
+object containing:</p>
+
+<ul>
+<li>Message ID that identifies the message when it fails to be queued or
+delivered. The message ID can be any kind of string. However, it is
+recommended to stay unique across the lifetime of your app or extension, even
+after it restarts. If you use the same message ID, there may be a chance that
+the previous message gets overridden. If an auto-increment counter is used to
+create the message ID, your app or extension should persist the counter value
+via <a href="storage.html">chrome.storage</a> API and restore it when the app
+reloads.</li>
+<li>Destination ID that identifies the server. This is the project number from the
+<a href="https://cloud.google.com/console/project">Google Developers Console</a> plus the
+suffix "@gcm.googleapis.com".</li>
+<li>Data that consist of a list of string-to-string key value pairs (up to 4KB
+total).</li>
+<li>Time-to-live (TTL, optional). This property value must be a duration from 0 to
+86,400 seconds (1 day) and it corresponds to the maximum period of time for
+which GCM will store and try to deliver the message. If this property is not
+set, it is default to the maximum value. When a TTL is set to 0, GCM will try
+to deliver the message immediately. If the immediate effort fails, the message
+will be discarded.</li>
+</ul>
+
+<p>When the callback passed in $(ref:gcm.send) is called without runtime error, it does
+not mean that the message was already delivered to the GCM server. Rather, it
+means that it was queued for delivery. Your app or extension should check and
+handle <code>chrome.runtime.lastError</code>. Please refer to <a href="#error_reference">Error
+reference</a> for possible error codes that could be
+returned.</p>
+
+<p>If the message fails to reach the destination within the specified TTL period,
+for example due to network error, the $(ref:gcm.onSendError) will be fired. Your app
+or extension can listen to this event and react to it, e.g. by trying to resend
+the message. Please refer to <a href="#error_reference">Error reference</a> for
+possible error codes that could be returned.</p>
+
+<pre data-filename="background.js"><code>
+// Substitute your own sender ID here. This is the project
+// number you got from the Google Developers Console.
+var senderId = "Your-Sender-ID";
+
+// Make the message ID unique across the lifetime of your app.
+// One way to achieve this is to use the auto-increment counter
+// that is persisted to local storage.
+
+// Message ID is saved to and restored from local storage.
+var messageId = 0;
+chrome.storage.local.get("messageId", function(result) {
+  if (chrome.runtime.lastError)
+    return;
+  messageId = parseInt(result["messageId"]);
+  if (isNaN(messageId))
+    messageId = 0;
+});
+
+// Sets up an event listener for send error.
+chrome.gcm.onSendError.addListener(sendError);
+
+// Returns a new ID to identify the message.
+function getMessageId() {
+  messageId++;
+  chrome.storage.local.set({messageId: messageId});
+  return messageId.toString();
+}
+
+function sendMessage() {
+  var message = {
+    messageId: getMessageId(),
+    destinationId: senderId + "@gcm.googleapis.com",
+    timeToLive: 86400,    // 1 day
+    data: {
+      "key1": "value1",
+      "key2": "value2"
+    }
+  };
+  chrome.gcm.send(message, function(messageId) {
+    if (chrome.runtime.lastError) {
+      // Some error occurred. Fail gracefully or try to send
+      // again.
+      return;
+    }
+
+    // The message has been accepted for delivery. If the message
+    // can not reach the destination, onSendError event will be
+    // fired.
+  });
+}
+
+function sendError(error) {
+  console.log("Message " + error.messageId +
+      " failed to be sent: " + error.errorMessage);
+</code></pre>
+
+<blockquote>
+  <p>}</p>
+</blockquote>
+
+<h2 id="advanced_topics">Advanced Topics</h2>
+
+<h3 id="messages_deleted_event">Messages deleted event</h3>
+
+<p>GCM will store up to 100 non-collapsible messages that are sent from your server
+to your client. After that, all messages are discarded from GCM, and an event
+$(ref:gcm.onMessagesDeleted) will be fired, which tells the client that it falls
+behind. Your app or extension should respond by syncing with your application
+server to recover the discarded messages.</p>
+
+<pre data-filename="background.js"><code>
+chrome.gcm.onMessagesDeleted.addListener(messagesDeleted);
+
+function messagesDeleted() {
+  // All messages have been discarded from GCM. Sync with
+  // your application server to recover from the situation.
+}
+</code></pre>
+
+<h3 id="collapsible_messages">Collapsible messages</h3>
+
+<p>GCM messages are often a tickle, telling the app or extension to contact the
+server for fresh data. In GCM, it's possible to create collapsible messages for
+this situation, wherein new messages replace older ones. When a collapse key is
+provided and multiple messages are queued up in the GCM servers for the same
+user, only the last one with any given collapse key is delivered to your app or
+extension. As a result the <code>message</code> object passed to the $(ref:gcm.onMessage) event
+will contain a <code>collapseKey</code>field. For more details about sending collapsible
+messages, please refer to <a href="http://developer.android.com/google/gcm/adv.html#collapsible">GCM Advance
+Topics</a>.</p>
+
+<h3 id="implement_gcm_server">Implement GCM Server</h3>
+

[mkearney1, 2014/10/02 00:52:49]

Again, make sure to state specifically that you are linking to Android docs, and
put in the actual title of those docs (as described above). Do this for all
three hrefs below.

[jianli, 2014/10/14 18:00:43]

Done.

+<p>Currently GCM provides two connection servers:
+<a href="http://developer.android.com/google/gcm/http.html">HTTP</a> and
+<a href="http://developer.android.com/google/gcm/ccs.html">CCS</a> (XMPP). You can use them
+separately or in tandem. Please refer to <a href="http://developer.android.com/google/gcm/server.html">GCM
+Server</a> for details.</p>
+
+<h2 id="error_reference">Error reference</h2>
+
+<p>An error could occur when a gcm API function is called. Your app or extension
+should check <code>chrome.runtime.lastError</code> for more information in your callback.
+The error code will also be passed as a parameter to $(ref:gcm.onSendError) event.</p>
+
+<p>Here's a brief summary of the gcm errors:</p>
+
+<ul>
+<li><strong>Function was called with invalid parameters</strong>: this could happen when gcm
+functions are called with bad parameters.</li>
+<li><strong>Profile was not signed in</strong>: this could happen when gcm functions are called
+from a profile that was not signed in.</li>
+<li><strong>Asynchronous operation is pending</strong>: this could happen when certain gcm
+function is called again without waiting for the callback passed in previous
+function to be called.</li>
+<li><strong>Network error occurred</strong>: this could happen when GCM server fails to reach
+due to network problem, like losing Internet connection.</li>
+<li><strong>Server error occurred</strong>: this could happen when GCM server fails to reach
+due to server problem, like server busy.</li>
+<li><strong>Time-to-live exceeded</strong>: this could happen when a message could not be
+delivered within the specific time-to-live period.</li>
+<li><strong>Unknown error occurred</strong>: this could happen due to any other internal
+errors.</li>
+</ul>
+
+<h2 id="feedback">Feedback</h2>
+
+<p>You can provide feedback about Google Cloud Messaging and the
+<a href="gcm.html">chrome.gcm</a> API through the Google Group <a href="https://groups.google.com/forum/#!forum/gcm-for-chrome-feedback">GCM for Chrome
+Feedback</a>. Use
+this group to ask for help, file bug reports, and request features.</p>