Web Notifications

This document defines an API for displaying simple notifications to the user.

Status of this Document

This document is an Editor's Draft and is not suitable for purposes other than reviewing the specification being developed.

1. Definitions

ambient notification: A notification which appears and disappears automatically without user action.
interactive notification: A notification which can receive events from user actions and deliver them to the application which created the notification.
persistent notification: A notification which is displayed until the user explicitly dismisses it.
notification platform: A notification platform is a system outside the user agent which provides desktop notifications. Examples include Growl on MacOS, NotifyOSD on Linux, and the Windows notification API.
simple notification: A notification which consists only of an icon and one or two lines of text.
web notification: A notification which consists of Web platform content, such as HTML or SVG.

2. 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.

3. Introduction

This section is not normative.

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.

3.1. 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.

4. Permissions

Permission must be granted by the user before the user agent is allowed to show notifications. Permissions are granted separately for each security origin, as defined in [ORIGIN].

The current notification permission level is one of the string values 'ALLOWED', 'DENIED', and 'DEFAULT'.

5. The Notification interface

The Notification interface represents a single notification to be shown to the user. It extends the EventTarget interface defined in [DOMEVENTS].

the Notification interface

interface Notification : EventTarget {

  void               close();
           attribute Function   onclick;
           attribute Function   onshow;
           attribute Function   onerror;
           attribute Function   onclose;
           attribute DOMString  tag;
           attribute DOMString  dir;
};

Attributes

dir of type DOMString

The dir attribute specifies the directionality of the notification.

onclick of type Function

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.

onclose of type Function

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

onerror of type Function

An event listener function corresponding to the event type "error". This event fires if the notification cannot be displayed to the user because of an error.

onshow of type Function

An event listener function corresponding to the event type "show". The show event must fire 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, and the event represents only that the user agent has attempted to show the notification.

tag of type DOMString

The tag value identifies this notification for possible 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 tag value to be shown simultaneously.

See below for an example of using notification tags.

Methods

close

Requests the user agent to close this notification. If the notification has already been displayed, the user agent must remove it from the display; otherwise, the user agent must prevent it from being displayed.

No Parameters
No Return Value
No Exceptions

5.1. Directionality

The dir attribute of the Notification interface specifies the directionality of the notification. It is an enumerated attribute with the following keywords:

The ltr keyword, which indicates that the contents of the notification are left-to-right text.
The rtl keyword, which indicates that the contents of the notification are right-to-left text.
The auto keyword, which indicates that the directionality of the notification is to be determined programmatically, as described below.

If unspecified the attribute has the value auto.

If the notification's dir attribute is auto, its title and body must be split into paragraphs and the directionality of each paragraph determined from its content independently of the others as specified by the Unicode bidirectional algorithm's rule P1, P2, and P3. [BIDI]

The user agent should reflect the directionality of the notification, for each paragraph of the title and body, in the underlying notification platform if that platform supports it.

5.2. 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`

5.3. Constructors

Constructing a notification

  Notification Notification(in DOMString title, in Object options);

Notification

Creates a new simple notification object with the provided content, and posts a task for it to be shown.

Parameters

title of type DOMString: Primary text, or title, of the notification. The user agent must process any markup in this string so that it appears as plain text when used as a string in the underlying notification platform.
options of type Object: Optional additional parameters. This object is a dictionary, which may contain any or all of the following keys. Any additional keys not specified here should be ignored.

iconUrl of type DOMString
The value contains the 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.

body of type DOMString
The value contains the secondary text, or body, of the notification.
The user agent must process any markup in this string so that it appears as plain text when used as a string in the underlying notification platform.

tag of type DOMString
This value must be assigned to the tag attribute of the new Notification object.

onshow of type Function
This value must be assigned to the onshow attribute of the new Notification object.

onerror of type Function
The value must be assigned to the onerror attribute of the new Notification object.

onclick of type Function
The value must be assigned to the onclick attribute of the new Notification object.

onclose of type Function
The value must be assigned to the onclose attribute of the new Notification object.
iconUrl of type DOMString: The value contains the 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.
body of type DOMString: The value contains the secondary text, or body, of the notification.
The user agent must process any markup in this string so that it appears as plain text when used as a string in the underlying notification platform.
tag of type DOMString: This value must be assigned to the tag attribute of the new Notification object.
onshow of type Function: This value must be assigned to the onshow attribute of the new Notification object.
onerror of type Function: The value must be assigned to the onerror attribute of the new Notification object.
onclick of type Function: The value must be assigned to the onclick attribute of the new Notification object.
onclose of type Function: The value must be assigned to the onclose attribute of the new Notification object.

Return Value

A new notification object.

No Exceptions

When the Notification() constructor is invoked, the user agent must return a new Notification object. The user agent must post a task to show the new notification, as specified in Showing a notification.

6. Algorithms

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

6.1. Showing a notification

When the user agent shows notification, it must proceed as follows.

If notification permissions are not allowed, the user agent must fire the error event on notification and not proceed further.

The user agent then must search for a possible replacement.

Get the tag attribute of the notification to be shown, and let it be tag.
If tag is defined, examine all the notifications in the list of active notifications and the queue of pending notifications. If any notification is found with the same source origin and has a tag attribute equal to tag, let it be called existing.

If existing was found, the user agent must replace existing with notification according to the replacing a notification algorithm, and stop.

If no replacement candidate was found, and the device allows notifications to be displayed immediately without limitations on the number of concurrent notifications, the user agent must display the notification immediately using displaying a notification algorithm, and stop.

If the device does have limitations on the number of concurrent notifications, the user agent must either immediately call to a notifications platform which natively supports queueing, or add notification to the queue of pending notifications, and proceed according to queueing notifications.

6.2. Closing a notification

When a notification is closed, either by the underlying notifications platform or by the user, the user agent must fire the close event on that notification, and remove it from the list of active notifications.

6.3. Queueing notifications

Whenever the queue of pending notifications is not empty, the user agent must wait and monitor changes in the available notification space on the device.

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, and remove that notification from the queue.

6.4. Displaying notifications

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

If iconUrl has been supplied, fetch the resource given by iconUrl using the algorithm defined in [HTML5].
If the fetch algorithm returns error information, queue a task to 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.
Add the new notification to the list of active notifications.

6.5. 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.

If new has an iconUrl specified, fetch the icon resource in new using the algorithm defined in [HTML5].
If the fetch algorithm returns error information, queue a task to 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.
If old is in the queue of pending notifications:
1. Replace old with new, in the same position, in the queue of pending notifications.
otherwise, if old is in the list of active notifications:
1. Fire the show event on the new notification object.
2. If the underlying notification platform supports replacement, replace old with new using the platform.
3. If the underlying notification platform does not support replacement, remove old using the platform and show new using the platform.
4. Remove old from the list of active notifications.
5. Add new to the list of active notifications.

7. Examples of interacting with notifications

This section is not normative.

7.1. 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 notification is created 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.

Example:

new Notification("New Email Received",
                 { iconUrl: "mail.png",
                   onshow: function() { setTimeout(notification.close(), 15000); }
                 });

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.

Example:

new Notification("Meeting about to begin",
                 { iconUrl: "calendar.gif",
                   body: "Room 101",
                   onclose: function() { cancelReminders(event); }
                 });

7.2. Using the tag attribute for multiple instances

Web applications frequently operate concurrently in multiple instances, such as when a user opens a mail application in multiple browser tabs. Since the desktop is a shared resource, Web Notifications provides a way for these instances to easily coordinate, by using the tag attribute.

Notifications which represent the same conceptual event can be tagged in the same way, and when both are shown, the user will only receive one notification.

Example:

Instance 1                                   | Instance 2
                                             |
// Instance notices there is new mail.       |
new Notification("New mail from John Doe",   |
                 { tag: 'message1' });       |
                                             |
                                             |  // Slightly later, this instance notices
                                             |  // there is new mail.
                                             |  new Notification("New mail from John Doe",
                                             |                   { tag: 'message1' });

The result of this situation, if the user agent follows the algorithms here, is a single notification "New mail from John Doe".

7.3. Using the tag attribute for a single instance

The tag attribute can also be used by a single instance of an application to keep its notifications as current as possible as state changes.

For example, if Alice is using a chat application with Bob, and Bob sends multiple messages while Alice is idle, the application may prefer that Alice not see a desktop notification for each message.

Example:

// Bob says "Hi"
new Notification("Bob: Hi", { tag: 'chat_Bob' });

// Bob says "Are you free this afternoon?"
new Notification("Bob: Hi / Are you free this afternoon?", { tag: 'chat_Bob' });

The result of this situation is a single notification; the second one replaces the first having the same tag. In a platform that queues notifications (first-in-first-out), using the tag allows the notification to also maintain its position in the queue. Platforms where the newest notifications are shown first, a similar result could be achieved using the close() method.

8. References

BIDI: Unicode Bidirectional Algorithm,
DOMEVENTS: Document Object Model (DOM) Level 3 Events Specification,
HTML5: HTML5: A vocabulary and associated APIs for HTML and XHTML,
ORIGIN: The Web Origin,
PERMISSIONS: Feature Permissions,

Web Notifications

W3C Editor's Draft 08 May 2012

Abstract

Status of this Document

Table of Contents

1. Definitions

2. Requirements and use cases

3. Introduction

3.1. Security

4. Permissions

5. The Notification interface

Attributes

Methods

5.1. Directionality

5.2. Event handler attributes

5.3. Constructors

6. Algorithms

6.1. Showing a notification

6.2. Closing a notification

6.3. Queueing notifications

6.4. Displaying notifications

6.5. Replacing a notification

7. Examples of interacting with notifications

7.1. Using events

7.2. Using the tag attribute for multiple instances

7.3. Using the tag attribute for a single instance

8. References