Update to Google Cloud Messaging document

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

-<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. <a href="gcm">GCM Chrome
-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>Please note that GCM Chrome API is experimental. It is only available to Chrome
-users on the dev channel.</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>
-
-<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 <br>
-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 gcm 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>