templates/articles/richNotifications.html

<h1 id="richNotifications">Rich Notifications</h1>

<p>The <a href="https://developer.chrome.com/apps/notifications">rich notifications API</a>
lets you create notifications using templates and
show these notifications to users in the user's system tray:
</p>

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

<h2 id="look">How they look</h2>

<p>
Rich notifications come in four different flavors:
basic, image, list, and progress.
All notifications include a title, message, small icon displayed
to the left of the notification message, and a contextMessage field,
which is displayed as a 3rd text field in a lighter color font.
</p>

<p>
A basic image:
</p>

<p>
<img src="{{static}}/images/basic_notification.png"
     alt="Basic notification">
</p>

<p>
List notifications display any number of list items:
</p>

<p>
<img src="{{static}}/images/list_notification.png"
     alt="List notification">
</p>

<p>
Image notifications include an image preview:
</p>

<p>
<img src="{{static}}/images/image_notification.png"
     alt="Image notification">
</p>

Progress notifications show a progress bar:
<p>
<img src="{{static}}/images/progress_notification.png"
     alt="Progress notification">
</p>

<h2 id="behave">How they behave</h2>

<p>
Notifications show up in a user's system tray,
and stay in the system tray until the user dismisses them.
On most platforms,
the bell icon is lit when there's new notifications;
On ChromeOS,
the system tray keeps a count of all new notifications.
Once a users sees the notifications in the system tray,
the count is reset to zero;
</p>

<p>
Notifications can be assigned a priority between -2 to 2.
Priorities < 0 are only shown in the center;
priorities > 0 are shown for increasing duration and
more high priority notifications can be displayed in the system tray.
</p>

<p>
In addition to displaying information,
all notification types can include up to two action items.
When users click on an action item,
your app can respond with the appropriate action.
For example,
when the user clicks on "Reply",
the email app opens and the user can complete the reply:
</p>

<p><img src="{{static}}/images/action_notification.png"
     alt="Action in notification">
</p>

<h2 id="develop">How to develop them</h2>

<p>
To use this API,
call the $(ref:notifications.create) method,
passing in the notification details
via the <code>options</code> parameter:
</p>

<pre>
chrome.notifications.create(id, options, creationCallback);
</pre>

<p>
The $(ref:notifications.NotificationOptions) must include a
$(ref:notifications.TemplateType),
which defines available notification details
and how those details are displayed.
</p>

<p class="note">
<b>Consider integrating with GCM!</b><br>
<a href="inform_users">Keep your users informed</a> all the time,
even when your app isn't opened.
The <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/samples/gcm-notifications">gcm-notifications sample</a>
shows a simple integration between GCM and Rich Notifications API.
</p>

<h3 id="basic">Create basic notification</h3>

<p>
All template types
(<code>basic</code>, <code>image</code>, <code>list</code> and <code>progress</code>)
must include a notification <code>title</code> and <code>message</code>,
as well as an <code>iconUrl</code>, which is a link to a small icon that
is displayed to the left of the notification message.
</p>

<p>
Here's an example of a <code>basic</code> template:
</p>

<pre>
var opt = {
  type: "basic",
  title: "Primary Title",
  message: "Primary message to display",
  iconUrl: "url_to_small_icon"
}
</pre>

<h3 id="image">Create image notification</h3>

<p>
The <code>image</code>
template type also includes an <code>imageUrl</code>, which is a link to
an image that is previewed within the notification:
</p>

<pre>
var opt = {
  type: "basic",
  title: "Primary Title",
  message: "Primary message to display",
  iconUrl: "url_to_small_icon",
  imageUrl: "url_to_preview_image"
}
</pre>

<p>
In Chrome Apps, due to a strict <a href="contentSecurityPolicy">Content Security Policy</a>
these URLs must point to a local resource or use a
<a href="app_external">blob or data URL</a>.
Use a 3:2 ratio for your image; otherwise a black border frames the image.
</p>

<h3 id="list">Create list notification</h3>

<p>
The <code>list</code> template displays <code>items</code>
in a list format:
</p>

<pre>
var opt = {
  type: "list",
  title: "Primary Title",
  message: "Primary message to display",
  iconUrl: "url_to_small_icon",
  items: [{ title: "Item1", message: "This is item 1."},
          { title: "Item2", message: "This is item 2."},
          { title: "Item3", message: "This is item 3."}]
}
</pre>

<h3 id="list">Create progress notification</h3>

<p>
The <code>progress</code> template displays a progress bar where current
progress ranges from 0 to 100:
</p>

<pre>
var opt = {
  type: "progress",
  title: "Primary Title",
  message: "Primary message to display",
  iconUrl: "url_to_small_icon",
  progress: 42
}
</pre>


<h2 id="events">Listening for and responding to events</h2>

<p>
All notifications can include event listeners and event handlers
that respond to user actions (see <a href="events">chrome.events</a>).
For example,
you can write an event handler to respond to an
$(ref:notifications.onButtonClicked) event.
</p>

<p>Event listener:</p>

<pre>
chrome.notifications.onButtonClicked.addListener(replyBtnClick);
</pre>

<p>Event handler:</p>

<pre>
function replyBtnClick {
	//Write function to respond to user action.
}
</pre>

<p>Consider including event listeners and handlers within the
  <a href="app_lifecycle#create_event_page">event page</a>,
so that notifications can pop-up even when the app or extension isn't running.
</p>