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

<h1 id="informUsers">Keep Users Informed</h1>

<p>
Users engage with multiple devices throughout the day
and they like notifications keeping them informed
without disrupting what's in front of them.
</p>

<p>
You can keep your users informed and help them decide
when is a good time to re-engage with your app using
<a href="cloudMessaging">Google Cloud Messaging (GCM)</a> and
<a href="richNotifications">Rich Notifications</a> APIs. 
</p>

<p><img src="{{static}}/images/notifications.png"
     alt="Notifications in system user tray">
</p>

<p class="note">
<b>GCM and Rich Notifications sample</b><br>
The <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/gcm-notifications">gcm-notifications sample</a>
shows a simple integration between GCM and Rich Notifications API. 
</p>

<h2 id="summary_workflow">Summary of user workflow</h2>

<p>
To keep users informed,
you need a way to push new information to your users
even when all your app's windows are closed or minimized.
Here's a summary of the user workflow for a very simple email app
(a real email app would be a lot more sophisticated),
with implementation details to follow:
</p>

<ol>
  <li>Register your app with GCM.</li>
  <li>Your app listens for new email data coming from the server.</li>
  <li>Your server sends new email data to a user's app.</li>
  <li>Google Cloud Messaging wakes up the user's app to tell it there's a new email message.</li>
  <li>The app parses the server data to create a notification.</li>
  <li>The user sees the notification in the system tray.</li>
</ol>

<p>This workflow is one example implementation.
You could choose to push messages from the server straight to the user,
without using the rich notifications;
you could also send notifications to users without using data from GCM.
However, these two APIs are a natural fit for each other:
GCM can wake up an app when new data is available server-side;
rich notifications surface the information to the user.
</p>

<h2 id="register">Register with GCM</h2>

<p>
Register your app or extension with GCM
to obtain the registraiton ID used to
send messages to it:</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;
  }

  // This is YOUR_REGISTRATION_ID.
  // Normally you send it to the server and you will use it below to send
  // message.
  console.log(registrationId);
}
</code></pre>

<h2 id="get_data">Listen for new data</h2>

<p>
Messages from the server are delivered via the <a href=gcm#event-onMessage>gcm.onMessage</a> event.
Your app or extension must register a handler in the event page
to receive this event and be able to wake up your app or extension:</p>

<pre data-filename="background.js"><code>
// Set up a listener for GCM message event.
chrome.gcm.onMessage.addListener(messageReceived);
</code></pre>

<p class="note">
<b>Enable GCM</b><br>
To use GCM in your app or extension,
you need to <a href="cloudMessaging#enable_gcm">enable it first</a>.
</p>

<h2 id="send_message">Send message to app</h2>

<p>
Use the <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/gcm-notifications">gcm-notifications sample</a>
to generate a curl command to send a message to the server:
</p>

<pre>
curl -H "Content-Type:application/x-www-form-urlencoded;charset=UTF-8" -H "Authorization: key=YOUR_APP_KEY" -d "registration_id=YOUR_REGISTRATION_ID" -d data.YOUR_MESSAGE_KEY=YOUR_MESSAGE_VALUE https://android.googleapis.com/gcm/send
</pre>

<p>
GCM servers route the message to all instances of Chrome running apps
or extensions with one of the registration IDs.
As long as Chrome is running, even if the extension or app is not running,
the app or extension's event page is woken up to deliver a message.</p>
</p>

<h2 id="create_notification">Create notification</h2>

<p>
The <code>messageReceived</code> event handler goes in your event page
(see <a href="#get_data">Listen for new data</a> above).
When the GCM service sends a message,
the event handler creates a notification:
</p>

<pre>
  function messageReceived(message) {
    // A message is an object with a data property that
    // consists of key-value pairs.
  
    // Returns a new notification ID used in the notification.
    function getNotificationId() {
      var id = Math.floor(Math.random() * 9007199254740992) + 1; 
      //Stores latest notification ID so that event handlers can access
      //notification when background page is closed.
      chrome.storage.local.set({'id': id});
      return id.toString();
    }
  
    // Concatenate all key-value pairs to form a display string.
    var messageString = "";
    for (var key in message.data) {
      if (messageString != "")
        messageString += ", "
      messageString += key + ":" + message.data[key];
    }
  
    // Pop up a notification to show the GCM message.
    chrome.notifications.create(getNotificationId(), {
      title: 'New email',
      iconUrl: 'mail_128.png',
      type: 'basic',
      message: messageString
    }, creationCallback);
  }
 </pre>