Web Notifications

Requirements and use cases

This specification must meet the following requirements:

An implementation which uses only the existing notification platforms in major platforms to display notifications must be able to comply with the specification.
The specification must allow compliant implementations regardless of platform or device.
The specification must provide controls to users in order to prevent unwanted notifications to be displayed.
The specification must define an event model for interactive notifications.
The specification must address security issues.
The specification should not require any implementation to display persistent notifications.
The specification should be compatible with other Web technologies, such as HTML and SVG.

The specification attempts to address the following use cases:

An application alerts the user "you've got mail" in the form of an ambient notification, with no interaction necessary.
An application alerts the user "you've got mail" as an interactive notification which allows the user to easily return to the inbox.
A calendar application alerts the user for an upcoming meeting, and allows the user to easily specify a "snooze" delay of several possible time periods.
A system alerts the user "your printer is out of paper".
An application with multiple simultaneous execution contexts (like a multi-tab email application) wants to show notifications without creating duplicate notifications.

Introduction

This specification provides an API to generate simple notifications to alert users outside of the web page. It does not specify exactly how a user agent should display these notifications; the best presentation depends on the device where the user agent is run. When this specificiation refers to displaying notifications on the "desktop", it generally refers to some static display area outside the web page, but may take several forms, including:

a corner of the user's display,
an area within the chrome of the user agent,
the "home" screen of a mobile device,
et al.

This specification does not define exactly how the user agent should display the notification, and the API is designed to be flexible with respect to presentation options.

This specification is designed to be compatible with existing notification platforms as much as possible, but also to be platform-independent. Since the common platforms do not provide the same functionality, this spec will indicate what events are guaranteed and which are not. In particular, notifications as specified here only can contain text and icon content. In the future, notifications generated from Web content may wish to contain Web content themselves, but that is outside the scope of this document.

In general, the event model for notifications is best-effort; while the Notification object offers an "onclick" event, applications may enhance their functionality by listening for that event, but must not depend on receiving it, in case the underlying notification platform does not provide that capability.

Security

Notifications should only be presented when the user has indicated they are desired; without this they could create a negative experience for the user.

The Notification interface

The Notification interface represents a single notification to be shown to the user. It extends the EventTarget interface defined in [[!DOM-LEVEL-3-EVENTS]].

void show()

Requests the user agent to show the notification to the user. Depending on desktop space, user idleness, or other factors as determined by the user agent, this may happen immediately or be postponed, but must eventually be done, following the algorithm for queueing a notification below.

A user agent must not show any notifications if notification permission is denied. If notification permission is denied when show() is invoked, an error event must be fired on this notification object.

void cancel()

Requests the user agent to not show this notification. If the notification has already been displayed, the user agent must remove it from the display; if it has not yet be displayed, the user agent must prevent its being displayed.

Notification Notification ()

Returns a new simple notification object with the provided content.

DOMString iconUrl: URL of the icon to be shown with this notification. The parameter must be resolved relative to the current document base URL or worker script URL.
DOMString title: Primary text, or title, of the notification. The user agent may ignore any markup in this string and treat it as plain text.
DOMString body: Secondary text, or body, of the notification. The user agent may ignore any markup in this string and treat it as plain text.

When the Notification() constructor is invoked, the user agent must return a new Notification object.

attribute Function onclick

An event listener function corresponding to the event type "click". This event listener is must be invoked when the user clicks on a notification.

This event is not guaranteed if the underlying notification platform does not support receiving click events.

attribute Function onshow

An event listener function corresponding to the event type "show". This event listener must be invoked after the show() method is called, at the point when the notification actually becomes visible to the user.

If the underlying notification platform does not show the notification immediately, this event may precede the notification becoming visible; however the notification will never become visible before this event is dispatched.

attribute Function onerror

An event listener function corresponding to the event type "error". This event listener must be invoked after the show() method is called, if the notification cannot be displayed to the user because of an error.

attribute Function onclose

An event listener function corresponding to the event type "close". This event listener must be invoked after the "show" event, at the point when the notification is dismissed by the user, closed by script, or closed by the notification platform.

attribute Function replaceId

A value which identifies this notification for replacement by another notification serving the same purpose. The user agent should not allow two notifications created by the same security origin and having the same replaceId value to be shown simultaneously.

attribute Function dir

The dir attribute specifies the directionality of the notification.

Directionality

The dir attribute of the Notification interface has has all the properties of the dir attribute as defined in [[!HTML5]], however since the notification does not have a parent element, it must receive a default value elsewhere, as follows.

In environments where the global object is represented by the Window object, if the notification's directionality state is not ltr or rtl, the directionality must be the same as the Document object associated with the global Window object. In other environments, if the notification's directionality state is not ltr or rtl, the directionality should be ltr.

Event handler attributes

The following are event handler attributes (and their corresponding event handler event types, as defined by [[!HTML5]]) that must be supported as DOM attributes by the Notification object.

event handler attribute	event handler event type
`onclick`	`click`
`onshow`	`show`
`onerror`	`error`
`onclose`	`close`

Queueing and displaying notifications

Queueing notifications

If the device allows notifications to displayed immediately without limitations on the number of concurrent notifications, it must display a notification immediately whenever show is called and notification permission is allowed.

If the device does have limitations on the number of concurrent notifications, when show is called and notification permission is allowed, the user agent must either immediately call to a notifications platform which supports queueing, or use the following algorithm.

The user agent must keep a queue of pending notifications and a list of active notifications.

Get the replacement id of the notification to be shown, and let it be replaceId.
If replaceId is defined, examine all the notifications in the list of active notifications. If any notification in the list has the same source origin and has replacement id equal to replaceId, do the following steps and then terminate this algorithm. Let existing be the notification in the list which matches.
1. Replace existing with the new notification using the replacing a notification algorithm.
2. If the replacement returned error information, stop.
3. Remove existing from the list of active notifications.
4. Add the new notification to the list of active notifications.
Add the notification to the queue of pending notifications.
Wait until there is available space on the device.
Display the first notification in the queue of pending notifications using the displaying a notification algorithm.

When the available display space changes on the device such that a new notification may be displayed, for example due to a previous notification being dismissed, the user agent should display the first notification in the queue using the procedure described above.

Displaying notifications

When a user agent is to display a notification, the user agent should perform the following steps:

Fetch the resource given by iconUrl using the algorithm defined in [[!HTML5]].
If the fetch algorithm returns error information, fire the error event on the notification object and stop executing this algorithm.
Fire the show event on the notification object.
Show the notification on the device, such as by calling the appropriate notification platform.

Replacing a notification

When a user agent is to replace a notification, the user agent should perform the following steps. Let old be the notification to be replaced by new.

Fetch the icon resource in new using the algorithm defined in [[!HTML5]].
If the fetch algorithm returns error information, fire the error event on the new notification object and stop executing this algorithm, returning the error information. The old notification is not affected.
Fire the close event on the old notification object.
Fire the show event on the new notification object.
If the underlying notification platform supports replacement, replace old with new on the device.
If the underlying notification platform does not support replacment, remove old from the device and show new on the device.

Interacting with notifications

Using events

Notification objects dispatch events during their lifecycle, which authors can use to generate desired behaviors.

The show event occurs when the notification is shown to the user -- this may be at some time after the show() method is called in the case of limited display space and a queue.

In the following example, this event is used to guarantee that regardless of when the notification is shown, it is displayed for only 15 seconds.

var notification = new Notification("mail.png", "New Email Received");
notification.onshow = function() { setTimeout(notification.cancel(), 15000); }
notification.show();

The close events occurs when the notification is dismissed by the user. Authors may use this event to perform actions when notifications are acknowledged.

In the following example, when a meeting reminder notification is acknowledged, the application suppresses other forms of reminders.

var notification = new Notification("calendar.png", "Meeting about to begin", "Room 101");
notification.onclose = function() { cancelReminders(event); }
notification.show();

Definitions