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

   1 <h1 id="informUsers">Keep Users Informed</h1>
   2
   3 <p>
   4 Users engage with multiple devices throughout the day
   5 and they like notifications keeping them informed
   6 without disrupting what's in front of them.
   7 </p>
   8
   9 <p>
  10 You can keep your users informed and help them decide
  11 when is a good time to re-engage with your app using
  12 <a href="cloudMessaging">Google Cloud Messaging (GCM)</a> and
  13 <a href="richNotifications">Rich Notifications</a> APIs.
  14 </p>
  15
  16 <p><img src="{{static}}/images/notifications.png"
  17      alt="Notifications in system user tray">
  18 </p>
  19
  20 <p class="note">
  21 <b>GCM and Rich Notifications sample</b><br>
  22 The <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/gcm-notifications">gcm-notifications sample</a>
  23 shows a simple integration between GCM and Rich Notifications API.
  24 </p>
  25
  26 <h2 id="summary_workflow">Summary of user workflow</h2>
  27
  28 <p>
  29 To keep users informed,
  30 you need a way to push new information to your users
  31 even when all your app's windows are closed or minimized.
  32 Here's a summary of the user workflow for a very simple email app
  33 (a real email app would be a lot more sophisticated),
  34 with implementation details to follow:
  35 </p>
  36
  37 <ol>
  38   <li>Register your app with GCM.</li>
  39   <li>Your app listens for new email data coming from the server.</li>
  40   <li>Your server sends new email data to a user's app.</li>
  41   <li>Google Cloud Messaging wakes up the user's app to tell it there's a new email message.</li>
  42   <li>The app parses the server data to create a notification.</li>
  43   <li>The user sees the notification in the system tray.</li>
  44 </ol>
  45
  46 <p>This workflow is one example implementation.
  47 You could choose to push messages from the server straight to the user,
  48 without using the rich notifications;
  49 you could also send notifications to users without using data from GCM.
  50 However, these two APIs are a natural fit for each other:
  51 GCM can wake up an app when new data is available server-side;
  52 rich notifications surface the information to the user.
  53 </p>
  54
  55 <h2 id="register">Register with GCM</h2>
  56
  57 <p>
  58 Register your app or extension with GCM
  59 to obtain the registraiton ID used to
  60 send messages to it:</p>
  61
  62 <pre data-filename="background.js"><code>
  63 function registerCallback(registrationId) {
  64   if (chrome.runtime.lastError) {
  65     // When the registration fails, handle the error and retry the
  66     // registration later.
  67     return;
  68   }
  69
  70   // This is YOUR_REGISTRATION_ID.
  71   // Normally you send it to the server and you will use it below to send
  72   // message.
  73   console.log(registrationId);
  74 }
  75 </code></pre>
  76
  77 <h2 id="get_data">Listen for new data</h2>
  78
  79 <p>
  80 Messages from the server are delivered via the <a href=gcm#event-onMessage>gcm.onMessage</a> event.
  81 Your app or extension must register a handler in the event page
  82 to receive this event and be able to wake up your app or extension:</p>
  83
  84 <pre data-filename="background.js"><code>
  85 // Set up a listener for GCM message event.
  86 chrome.gcm.onMessage.addListener(messageReceived);
  87 </code></pre>
  88
  89 <p class="note">
  90 <b>Enable GCM</b><br>
  91 To use GCM in your app or extension,
  92 you need to <a href="cloudMessaging#enable_gcm">enable it first</a>.
  93 </p>
  94
  95 <h2 id="send_message">Send message to app</h2>
  96
  97 <p>
  98 Use the <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/gcm-notifications">gcm-notifications sample</a>
  99 to generate a curl command to send a message to the server:
 100 </p>
 101
 102 <pre>
 103 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
 104 </pre>
 105
 106 <p>
 107 GCM servers route the message to all instances of Chrome running apps
 108 or extensions with one of the registration IDs.
 109 As long as Chrome is running, even if the extension or app is not running,
 110 the app or extension's event page is woken up to deliver a message.</p>
 111 </p>
 112
 113 <h2 id="create_notification">Create notification</h2>
 114
 115 <p>
 116 The <code>messageReceived</code> event handler goes in your event page
 117 (see <a href="#get_data">Listen for new data</a> above).
 118 When the GCM service sends a message,
 119 the event handler creates a notification:
 120 </p>
 121
 122 <pre>
 123   function messageReceived(message) {
 124     // A message is an object with a data property that
 125     // consists of key-value pairs.
 126
 127     // Returns a new notification ID used in the notification.
 128     function getNotificationId() {
 129       var id = Math.floor(Math.random() * 9007199254740992) + 1;
 130       //Stores latest notification ID so that event handlers can access
 131       //notification when background page is closed.
 132       chrome.storage.local.set({'id': id});
 133       return id.toString();
 134     }
 135
 136     // Concatenate all key-value pairs to form a display string.
 137     var messageString = "";
 138     for (var key in message.data) {
 139       if (messageString != "")
 140         messageString += ", "
 141       messageString += key + ":" + message.data[key];
 142     }
 143
 144     // Pop up a notification to show the GCM message.
 145     chrome.notifications.create(getNotificationId(), {
 146       title: 'New email',
 147       iconUrl: 'mail_128.png',
 148       type: 'basic',
 149       message: messageString
 150     }, creationCallback);
 151   }
 152  </pre>