GCM for Chrome documentation

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

+<meta name="doc-family" content="apps">
+<h1 id="gcmForChrome">Google Cloud Messaging for Chrome</h1>
+
+<h2 id="t1">Overview</h2>

[mkearney1, 2014/02/04 21:23:45]

This content doesn't need to be in an overview (h2). Just have it follow the h1.

[jianli, 2014/02/05 22:04:56]

Done.

+
+<p>Google Cloud Messaging for Chrome (GCM) is a service for signed-in Chrome users
+that helps developers send and receive message data from servers to their Chrome
+apps and extensions. 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. The service could also be used to send
+upstream messages to the server.</p>

[mkearney1, 2014/02/04 21:23:45]

Is there a working sample for new GCM? There definitely should be!

[jianli, 2014/02/05 22:04:56]

We don't have sample yet. We are definitely going to publish a sample app on
gitpub at later time, probably before publishing the document.

+

[mkearney1, 2014/02/04 21:23:45]

You don't mention anywhere that this version of GCM is dev channel only. Is that
because it won't be for long?

[jianli, 2014/02/05 22:04:56]

We're going to ship GCM API to stable channel for M35. This document will be
published sometime after M35 branch point (3/31). Do we need to mention that GCM
API is dev channel only. Once it hits stable channel, we will update the
document to remove this sentence. Right?

+<p>This document describes how to set up and use GCM. For additional information
+see the reference documentation for the <a href="gcm.html">GCM Chrome API</a> and
+the <a href="http://developer.android.com/google/gcm/index.html">GCM Service</a>. To get

[mkearney1, 2014/02/04 21:23:45]

Why are we pointing to android docs instead of gcm_server.html?

[jianli, 2014/02/05 22:04:56]

Our existing documentation for GCM service at
http://developer.chrome.com/apps/gcm_server.html is for pushing messaging. We're
now using Android GCM service. This is the reason I point to it.

+help with GCM or to give us feedback, see <a href="#feedback">Feedback</a>.</p>

[mkearney1, 2014/02/04 21:23:45]

Why have we removed the Feedback section?

[jianli, 2014/02/05 22:04:56]

This is due to conversion error. Fixed.

+

[mkearney1, 2014/02/04 21:23:45]

Make headers consistent!

Suggestion-- h3 should be h2 and read:

Enable GCM

[jianli, 2014/02/05 22:04:56]

Done.

+<h3 id="t2">How to enable GCM</h3>
+
+<p>To use GCM for your app or extension, do the following:</p>
+
+<ol>
+<li>Upload your app or extension client to the Chrome Web Store.</li>

[mkearney1, 2014/02/04 21:23:45]

Link to webstore/publish.html.

[jianli, 2014/02/05 22:04:56]

Done.

+<li>A user installs your app or extension.</li>
+<li>Your app or extension client requests a registration ID using $ref:gcm.register

[mkearney1, 2014/02/04 21:23:45]

Link to related doc (obtaining registration ID) for more information.

[jianli, 2014/02/05 22:04:56]

Done.

+function and sends this ID to your server together with information
+identifying the user.</li>
+</ol>
+
+<h3 id="t3">How to receive a message</h3>

[mkearney1, 2014/02/04 21:23:45]

Make headers consistent!

Suggestion-- h3 should be h2 and read:

Receive a message

[jianli, 2014/02/05 22:04:56]

If we get rid of <h2>Overview</h2> and promote "Receive a message" to h2. It
seems to be get easily confused with "Receive messages" in "Write Chrome App or
Extension" h2 section. Here we want to summarize what to do to receive a
message. And "Receive messages" gives the details steps and sample code on how
to do it? How are we going to organize these sections in better way?

+
+<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 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>

[mkearney1, 2014/02/04 21:23:45]

Link to related doc (Receiving messages).

[jianli, 2014/02/05 22:04:56]

Done.

+</ol>
+
+<h3 id="t4">How to send a message</h3>

[mkearney1, 2014/02/04 21:23:45]

Make headers consistent!

Suggestion-- h3 should be h2 and read:

Send a message

[jianli, 2014/02/05 22:04:56]

Done.

+
+<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

[mkearney1, 2014/02/04 21:23:45]

Link to related doc (Sending messages).

[jianli, 2014/02/05 22:04:56]

Done.

+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.</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.</li>

[mkearney1, 2014/02/04 21:23:45]

Link to Error reference section.

[jianli, 2014/02/05 22:04:56]

Done.

+</ol>
+

[mkearney1, 2014/02/04 21:23:45]

Make headers consistent!

Slight rewording of title:

Set up project

[jianli, 2014/02/05 22:04:56]

Done.

+<h2 id="t5">Setting up Project</h2>
+
+<h3 id="t6">Creating a Google API project</h3>

[mkearney1, 2014/02/04 21:23:45]

Make headers consistent!

Slight rewording of title:

Create Google API Project

[jianli, 2014/02/05 22:04:56]

Done.

+
+<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="t7">Enabling the GCM service</h3>

[mkearney1, 2014/02/04 21:23:45]

Enable the GCM service

[jianli, 2014/02/05 22:04:56]

Done.

+
+<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 Chrome
+API</strong> toggle to ON.</li>

[mkearney1, 2014/02/04 21:23:45]

Is it worth mentioning the terms of service here? Also, have those terms
changed, and if so, the doc may need to be updated! Last update, September 2012.

[jianli, 2014/02/05 22:04:56]

I added the text to mention TOS at the beginning of this doc.

I do not think we need a separate a specific TOS. Instead, we should refer to
both standard TOS for API and Cloud service.

+</ol>
+
+<h2 id="t8">Setting up Chrome app or extension</h2>

[mkearney1, 2014/02/04 21:23:45]

Set up Chrome App or Extension

[jianli, 2014/02/05 22:04:56]

Done.

+
+<h3 id="t9">Adding permission to manifest</h3>
+

[mkearney1, 2014/02/04 21:23:45]

Add permission to manifest

[jianli, 2014/02/05 22:04:56]

Done.

+<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",

[mkearney1, 2014/02/04 21:23:45]

The , looks funny here without the ...

[jianli, 2014/02/05 22:04:56]

Done.

+]
+</code></pre>
+
+<h2 id="t10">Writing Chrome app or extension</h2>

[mkearney1, 2014/02/04 21:23:45]

Write Chrome App or Extension

[jianli, 2014/02/05 22:04:56]

Done.

+
+<h3 id="t11">Obtaining registration ID</h3>

[mkearney1, 2014/02/04 21:23:45]

Obtain registration ID

[jianli, 2014/02/05 22:04:56]

Done.

+
+<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,
+that is linked to your app or extension that is installed to this profile.</p>
+
+<p>When a user installs your app or extension, the client needs to call
+$ref:gcm.register and specify the list of senders (project IDs from Google
+Developers Console). Your app or extension should pass a callback function to
+verify that registration was successful and send the registration ID back to
+your application server. For example, your app or extension could send an XHR
+request to a RESTful API on your server. Whatever method your app or extension
+uses to send the registration ID to the server, it must be secured (https, for
+instance).</p>
+
+<p>When registration fails, the app or extension should retry the failed operation
+using exponential back-off. In exponential back-off, each time there is a
+failure, it should wait twice the previous amount of time before trying again.</p>
+
+<pre><code>
+chrome.runtime.onInstalled.addListener(function() {
+  // Up to 100 senders are allowed.
+  var senderIds = ["Your-Sender-ID"];
+
+  chrome.gcm.register(senderIds, function(registrationId) {
+    if (chrome.runtime.lastError) {
+      // When registration fails, try to register again using
+      // exponential back-off.
+      return;
+    }
+
+    // Send the registration ID to your application server.
+
+    // You can cache the registration ID here, but it is not
+    // necessary, as GCM API will do it for you. You can get
+    // back the same ID by calling gcm.register again with
+    // same sender IDs.
+  });
+});
+</code></pre>
+

[mkearney1, 2014/02/04 21:23:45]

Weird couple of sentences here. How about:

Your app or extension is automatically unregistered from the GCM service when a
user uninstalls it. You can't unregister using the GCM API.

[jianli, 2014/02/05 22:04:56]

Done.

+<p>Unregistration is not supported in gcm API. Your app or extension will be
+automatically unregistered from the GCM server when it is uninstalled.</p>
+

[mkearney1, 2014/02/04 21:23:45]

Receive messages

[jianli, 2014/02/05 22:04:56]

Done.

+<h3 id="t12">Receiving 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 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 $ref:gcm.onMessage event. Your app or

[mkearney1, 2014/02/04 21:23:45]

Nit-- via the instead of just via.

[jianli, 2014/02/05 22:04:56]

Done.

+extension must register a handler to receive this event when loading, similar to
+how they'd register for launch events.</p>
+
+<pre><code>
+chrome.app.runtime.onLaunched.addListener(function() {
+  chrome.gcm.onMessage.addListener(function(message) {
+    // A message is an object with a data property that
+    // consists of key-value pairs.

[mkearney1, 2014/02/04 21:23:45]

Code isn't valid. Check your blocks.

[jianli, 2014/02/05 22:04:56]

Done.

+  });
+</code></pre>
+
+<blockquote>
+  <p>});</p>

[mkearney1, 2014/02/04 21:23:45]

I think you need to remove this blockquote.

[jianli, 2014/02/05 22:04:56]

Done.

+</blockquote>
+
+<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="t13">Sending messages</h3>

[mkearney1, 2014/02/04 21:23:45]

Send messages

[jianli, 2014/02/05 22:04:56]

Done.

+
+<p>To send messages upstream, your app or extension should call $ref:gcm.send with an
+object containing:</p>
+

[mkearney1, 2014/02/04 21:23:45]

IMPORTANT-- the terminology in this bullet list doesn't match exactly the
terminology in the sample code below and it's important that it does so the
developer can map what they are reading to the sample.

[jianli, 2014/02/05 22:04:56]

Which part does not match?

+<ul>

[mkearney1, 2014/02/04 21:23:45]

You should capitalize the first letters in each bullet.

[jianli, 2014/02/05 22:04:56]

Done.

+<li>a unique message ID that identifies the message when it fails to be queued or
+delivered. The message ID should be unique across the lifetime of your app or
+extension, even after it restarts. If an auto-increment counter is used to
+create the message ID, your app or extension should persist the counter value
+via chrome.storage API and restores it when the app reloads.</li>

[mkearney1, 2014/02/04 21:23:45]

Nit-- 'restores it' should be 'restore it'.

[jianli, 2014/02/05 22:04:56]

Done.

+<li>destination ID that identifies the server. This is the project number returned
+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>

[mkearney1, 2014/02/04 21:23:45]

Nit-- Line 91 list item missing a full-stop.

[jianli, 2014/02/05 22:04:56]

Not sure I understand this. What do you mean by full-stop?

[fgorski, 2014/02/05 23:27:11]

It's a period ('.') at the end of the sentence.
                                      e.g.    ^

+<li>optional time-to-live (TTL). 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 GCM
+server, for example due to network error, the $ref:gcm.onSendError will be fired.</p>
+
+<pre><code>
+// Substitute your own sender ID here. This is the project
+// number you got from the Google Developers Console.
+var senderId = "Your-Sender-ID";
+
+// Message ID should be 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.app.runtime.onLaunched.addListener(function() {
+  chrome.storage.local.get("messageId", function(result) {
+    messageId = result["messageId"];
+  });
+});
+
+// Returns a new ID to identify the message.
+function getMessageId() {
+  messageId++;
+  chrome.storage.local.set({messageId: messageId});
+  return messageId;
+}
+
+chrome.gcm.onSendError.addListener(function(error) {
+  console.log("Message " + error.messageId +
+      " failed to be sent: " + error.errorMessage);
+}
+
+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;
+    }
+
+    // Message is accepted and queued.
+  });
+}
+</code></pre>
+
+<h3 id="t14">Maximum number of messages stored in GCM</h3>
+
+<p>GCM will store up to 100 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
+app server to recover the discarded messages.</p>
+
+<h2 id="t15">Publishing your app</h2>

[mkearney1, 2014/02/04 21:23:45]

Publish your app

[jianli, 2014/02/05 22:04:56]

Done.

+
+<p>To use the GCM service, you must publish your app in the <a href="https://developers.google.com/chrome/web-store/docs/get_started_simple">Chrome Web
+Store</a>.</p>

[mkearney1, 2014/02/04 21:23:45]

Link instead to webstore/publish.html

[jianli, 2014/02/05 22:04:56]

Done.

+
+<h2 id="t16">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"></h2>

[mkearney1, 2014/02/04 21:23:45]

Missing text! Feedback

[jianli, 2014/02/05 22:04:56]

Done.

+
+<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-v2-feedback">GCM for Chrome V2

[mkearney1, 2014/02/04 21:23:45]

There isn't a group set up for this yet!

[jianli, 2014/02/05 22:04:56]

Will create one once before we official launch the API.

+Feedback</a>.
+Use this group to ask for help, file bug reports, and request features.</p>