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

   1 <h1 id="richNotifications">Rich Notifications</h1>
   2
   3 <p>The <a href="https://developer.chrome.com/apps/notifications">rich notifications API</a>
   4 lets you create notifications using templates and
   5 show these notifications to users in the user's system tray:
   6 </p>
   7
   8 <p><img src="{{static}}/images/notifications.png"
   9      alt="Notifications in system user tray">
  10 </p>
  11
  12 <h2 id="look">How they look</h2>
  13
  14 <p>
  15 Rich notifications come in four different flavors:
  16 basic, image, list, and progress.
  17 All notifications include a title, message, small icon displayed
  18 to the left of the notification message, and a contextMessage field,
  19 which is displayed as a 3rd text field in a lighter color font.
  20 </p>
  21
  22 <p>
  23 A basic image:
  24 </p>
  25
  26 <p>
  27 <img src="{{static}}/images/basic_notification.png"
  28      alt="Basic notification">
  29 </p>
  30
  31 <p>
  32 List notifications display any number of list items:
  33 </p>
  34
  35 <p>
  36 <img src="{{static}}/images/list_notification.png"
  37      alt="List notification">
  38 </p>
  39
  40 <p>
  41 Image notifications include an image preview:
  42 </p>
  43
  44 <p>
  45 <img src="{{static}}/images/image_notification.png"
  46      alt="Image notification">
  47 </p>
  48
  49 Progress notifications show a progress bar:
  50 <p>
  51 <img src="{{static}}/images/progress_notification.png"
  52      alt="Progress notification">
  53 </p>
  54
  55 <h2 id="behave">How they behave</h2>
  56
  57 <p>
  58 Notifications show up in a user's system tray,
  59 and stay in the system tray until the user dismisses them.
  60 On most platforms,
  61 the bell icon is lit when there's new notifications;
  62 On ChromeOS,
  63 the system tray keeps a count of all new notifications.
  64 Once a users sees the notifications in the system tray,
  65 the count is reset to zero;
  66 </p>
  67
  68 <p>
  69 Notifications can be assigned a priority between -2 to 2.
  70 Priorities < 0 are only shown in the center;
  71 priorities > 0 are shown for increasing duration and
  72 more high priority notifications can be displayed in the system tray.
  73 </p>
  74
  75 <p>
  76 In addition to displaying information,
  77 all notification types can include up to two action items.
  78 When users click on an action item,
  79 your app can respond with the appropriate action.
  80 For example,
  81 when the user clicks on "Reply",
  82 the email app opens and the user can complete the reply:
  83 </p>
  84
  85 <p><img src="{{static}}/images/action_notification.png"
  86      alt="Action in notification">
  87 </p>
  88
  89 <h2 id="develop">How to develop them</h2>
  90
  91 <p>
  92 To use this API,
  93 call the $(ref:notifications.create) method,
  94 passing in the notification details
  95 via the <code>options</code> parameter:
  96 </p>
  97
  98 <pre>
  99 chrome.notifications.create(id, options, creationCallback);
 100 </pre>
 101
 102 <p>
 103 The $(ref:notifications.NotificationOptions) must include a
 104 $(ref:notifications.TemplateType),
 105 which defines available notification details
 106 and how those details are displayed.
 107 </p>
 108
 109 <p class="note">
 110 <b>Consider integrating with GCM!</b><br>
 111 <a href="inform_users">Keep your users informed</a> all the time,
 112 even when your app isn't opened.
 113 The <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/samples/gcm-notifications">gcm-notifications sample</a>
 114 shows a simple integration between GCM and Rich Notifications API.
 115 </p>
 116
 117 <h3 id="basic">Create basic notification</h3>
 118
 119 <p>
 120 All template types
 121 (<code>basic</code>, <code>image</code>, <code>list</code> and <code>progress</code>)
 122 must include a notification <code>title</code> and <code>message</code>,
 123 as well as an <code>iconUrl</code>, which is a link to a small icon that
 124 is displayed to the left of the notification message.
 125 </p>
 126
 127 <p>
 128 Here's an example of a <code>basic</code> template:
 129 </p>
 130
 131 <pre>
 132 var opt = {
 133   type: "basic",
 134   title: "Primary Title",
 135   message: "Primary message to display",
 136   iconUrl: "url_to_small_icon"
 137 }
 138 </pre>
 139
 140 <h3 id="image">Create image notification</h3>
 141
 142 <p>
 143 The <code>image</code>
 144 template type also includes an <code>imageUrl</code>, which is a link to
 145 an image that is previewed within the notification:
 146 </p>
 147
 148 <pre>
 149 var opt = {
 150   type: "basic",
 151   title: "Primary Title",
 152   message: "Primary message to display",
 153   iconUrl: "url_to_small_icon",
 154   imageUrl: "url_to_preview_image"
 155 }
 156 </pre>
 157
 158 <p>
 159 In Chrome Apps, due to a strict <a href="contentSecurityPolicy">Content Security Policy</a>
 160 these URLs must point to a local resource or use a
 161 <a href="app_external">blob or data URL</a>.
 162 Use a 3:2 ratio for your image; otherwise a black border frames the image.
 163 </p>
 164
 165 <h3 id="list">Create list notification</h3>
 166
 167 <p>
 168 The <code>list</code> template displays <code>items</code>
 169 in a list format:
 170 </p>
 171
 172 <pre>
 173 var opt = {
 174   type: "list",
 175   title: "Primary Title",
 176   message: "Primary message to display",
 177   iconUrl: "url_to_small_icon",
 178   items: [{ title: "Item1", message: "This is item 1."},
 179           { title: "Item2", message: "This is item 2."},
 180           { title: "Item3", message: "This is item 3."}]
 181 }
 182 </pre>
 183
 184 <h3 id="list">Create progress notification</h3>
 185
 186 <p>
 187 The <code>progress</code> template displays a progress bar where current
 188 progress ranges from 0 to 100:
 189 </p>
 190
 191 <pre>
 192 var opt = {
 193   type: "progress",
 194   title: "Primary Title",
 195   message: "Primary message to display",
 196   iconUrl: "url_to_small_icon",
 197   progress: 42
 198 }
 199 </pre>
 200
 201
 202 <h2 id="events">Listening for and responding to events</h2>
 203
 204 <p>
 205 All notifications can include event listeners and event handlers
 206 that respond to user actions (see <a href="events">chrome.events</a>).
 207 For example,
 208 you can write an event handler to respond to an
 209 $(ref:notifications.onButtonClicked) event.
 210 </p>
 211
 212 <p>Event listener:</p>
 213
 214 <pre>
 215 chrome.notifications.onButtonClicked.addListener(replyBtnClick);
 216 </pre>
 217
 218 <p>Event handler:</p>
 219
 220 <pre>
 221 function replyBtnClick {
 222         //Write function to respond to user action.
 223 }
 224 </pre>
 225
 226 <p>Consider including event listeners and handlers within the
 227   <a href="app_lifecycle#create_event_page">event page</a>,
 228 so that notifications can pop-up even when the app or extension isn't running.
 229 </p>
 230