chrome.notifications

Description:	Use the `chrome.notifications` API to create rich notifications using templates and show these notifications to users in the system tray.
Availability:	Stable since Chrome 28.
Permissions:	"notifications"
Learn More:	Chrome Apps Office Hours: Rich Notifications

Note: This API is currently available on ChromeOS, Windows, and Mac.

Usage

To use this API, call the notifications.create method, passing in the notification details via the options parameter:

      chrome.notifications.create(id, options, creationCallback);

The notifications.NotificationOptions must include a notifications.TemplateType, which defines available notification details and how those details are displayed.

All template types (basic, image, and list) must include a notification title and message, as well as an iconUrl, which is a link to a small icon that is displayed to the left of the notification message. The image template type also includes an imageUrl, which is a link to an image that is previewed within the notification. Due to a strict Content Security Policy in Chrome Apps, these URLs must point to a local resource or use a data URL.

Here's an example of a basic template:

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

The list template displays items in a list format:

      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."}]
      }

Let us know if you have ideas for new templates with varying layouts by filing a crbug!

Listening for and responding to events

All notifications can include event listeners and event handlers that respond to user actions. For example, you can write an event handler to respond to an notifications.onButtonClicked event.

Consider including event listeners and handlers within the event page, so that notifications can pop-up even when the app or extension isn't running.

Summary

Types
TemplateType
PermissionLevel
NotificationOptions
Methods
create − `chrome.notifications.create(string notificationId, NotificationOptions options, function callback)`
update − `chrome.notifications.update(string notificationId, NotificationOptions options, function callback)`
clear − `chrome.notifications.clear(string notificationId, function callback)`
getAll − `chrome.notifications.getAll(function callback)`
getPermissionLevel − `chrome.notifications.getPermissionLevel(function callback)`
Events
onClosed
onClicked
onButtonClicked
onPermissionLevelChanged
onShowSettings

Types

TemplateType

Enum
`"basic"`, `"image"`, `"list"`, or `"progress"`

PermissionLevel

Enum
`"granted"`, or `"denied"`

NotificationOptions

properties

TemplateType (optional) type Which type of notification to display. Required for notifications.create method.

string (optional) iconUrl Sender's avatar, app icon, or a thumbnail for image notifications. Required for notifications.create method.

string (optional) title Title of the notification (e.g. sender name for email). Required for notifications.create method.

string (optional) message Main notification content. Required for notifications.create method.

string (optional) contextMessage Alternate notification content with a lower-weight font.

integer (optional) priority Priority ranges from -2 to 2. -2 is lowest priority. 2 is highest. Zero is default.

double (optional) eventTime A timestamp associated with the notification, in milliseconds past the epoch (e.g. Date.now() + n).

array of object

(optional) buttons

Text and icons for up to two notification action buttons.

Properties of each object

string	title
string	(optional) iconUrl

string (optional) imageUrl Image thumbnail for image-type notifications.

array of object

(optional) items

Items for multi-item notifications.

Properties of each object

string	title	Title of one item of a list notification.
string	message	Additional details about this item.

integer (optional) progress Current progress ranges from 0 to 100.

boolean (optional) isClickable Whether to show UI indicating that the app will visibly respond to clicks on the body of a notification.

Methods

create


              chrome.notifications.create(string notificationId,     NotificationOptions options, function callback)

Creates and displays a notification.

Parameters

string notificationId Identifier of the notification. If it is empty, this method generates an id. If it matches an existing notification, this method first clears that notification before proceeding with the create operation.

NotificationOptions options Contents of the notification.

function

callback

Returns the notification id (either supplied or generated) that represents the created notification.

The callback parameter should be a function that looks like this:

function(string notificationId) {...};

string

notificationId

update


              chrome.notifications.update(string notificationId,     NotificationOptions options, function callback)

Updates an existing notification.

Parameters

string notificationId The id of the notification to be updated. This is returned by notifications.create method.

NotificationOptions options Contents of the notification to update to.

function

callback

Called to indicate whether a matching notification existed.

The callback parameter should be a function that looks like this:

function(boolean wasUpdated) {...};

boolean

wasUpdated

clear


              chrome.notifications.clear(string notificationId, function callback)

Clears the specified notification.

Parameters

string notificationId The id of the notification to be cleared. This is returned by notifications.create method.

function

callback

Called to indicate whether a matching notification existed.

The callback parameter should be a function that looks like this:

function(boolean wasCleared) {...};

boolean

wasCleared

getAll


              chrome.notifications.getAll(function callback)

Retrieves all the notifications.

Parameters

function

callback

Returns the set of notification_ids currently in the system.

The callback parameter should be a function that looks like this:

function(object notifications) {...};

object

notifications

getPermissionLevel


              chrome.notifications.getPermissionLevel(function callback)

Retrieves whether the user has enabled notifications from this app or extension.

Parameters

function

callback

Returns the current permission level.

The callback parameter should be a function that looks like this:

function( PermissionLevel level) {...};

PermissionLevel

level

Events

onClosed

The notification closed, either by the system or by user action.

addListener


                    chrome.notifications.onClosed.addListener(function callback)

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(string notificationId, boolean byUser) {...};

string	notificationId
boolean	byUser

onClicked

The user clicked in a non-button area of the notification.

addListener


                    chrome.notifications.onClicked.addListener(function callback)

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(string notificationId) {...};

string

notificationId

onButtonClicked

The user pressed a button in the notification.

addListener


                    chrome.notifications.onButtonClicked.addListener(function callback)

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(string notificationId, integer buttonIndex) {...};

string	notificationId
integer	buttonIndex

onPermissionLevelChanged

The user changes the permission level.

addListener


                    chrome.notifications.onPermissionLevelChanged.addListener(function callback)

Parameters

function

callback

The callback parameter should be a function that looks like this:

function( PermissionLevel level) {...};

PermissionLevel

level

onShowSettings

The user clicked on a link for the app's notification settings.

addListener


                    chrome.notifications.onShowSettings.addListener(function callback)

Parameters
function	callback	The callback parameter should be a function that looks like this: `function() {...};`