Keep Users Informed

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

You can keep your users informed and help them decide when is a good time to re-engage with your app using Google Cloud Messaging (GCM) and Rich Notifications APIs.

Notifications in system user tray

GCM and Rich Notifications sample
The gcm-notifications sample shows a simple integration between GCM and Rich Notifications API.

Summary of user workflow

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:

  1. Register your app with GCM.
  2. Your app listens for new email data coming from the server.
  3. Your server sends new email data to a user's app.
  4. Google Cloud Messaging wakes up the user's app to tell it there's a new email message.
  5. The app parses the server data to create a notification.
  6. The user sees the notification in the system tray.

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.

Register with GCM

Register your app or extension with GCM to obtain the registraiton ID used to send messages to it:


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);
}

Listen for new data

Messages from the server are delivered via the gcm.onMessage 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:


// Set up a listener for GCM message event.
chrome.gcm.onMessage.addListener(messageReceived);

Enable GCM
To use GCM in your app or extension, you need to enable it first.

Send message to app

Use the gcm-notifications sample to generate a curl command to send a message to the server: 

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

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.

Create notification

The messageReceived event handler goes in your event page (see Listen for new data above). When the GCM service sends a message, the event handler creates a notification: 

  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);
  }