W3C

Web Notifications

W3C Working Draft 01 March 2011

This Version:
http://www.w3.org/TR/2011/WD-notifications-20110301/
Latest Published Version:
http://www.w3.org/TR/notifications/
Latest Editor's Draft:
http://dev.w3.org/2006/webapi/WebNotifications/publish/Notifications.html
Editor:
John Gregg, Google <>

Abstract

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

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document was published by the Web Notification Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-web-notification@w3.org (subscribe, archives). All feedback is welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Although this is an initial draft and the group is open to changing the design, the group has so far not received feedback asking it to do so.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Definitions

2. Requirements and use cases

This specification must meet the following requirements: The specification attempts to address the following use cases:

3. Introduction

This section is non-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:

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

This section is non-normative.

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

Permissions for notifications must be controlled using the Feature Permissions interface where Notifications are a privileged feature with unique id 'notifications'. [PERMISSIONS]

Throughout this document, "notification permission is allowed" shall mean that the permission level of the 'notifications' feature for the current security origin is USER_ALLOWED or DEFAULT_ALLOWED in the meaning of [PERMISSIONS], and "notification permission is denied" shall mean that the current permission level has some other value.

5. 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].

[Constructor]
interface Notification : EventTarget {
    void         show ();
    void         cancel ();

    attribute Function onclick;
    attribute Function onshow;
    attribute Function onerror;
    attribute Function onclose;
    attribute DOMString replaceId;
    attribute DOMString dir;
};

5.1 Methods

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.

No Parameters.
No exceptions.
Return type: 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.

No Parameters.
No exceptions.
Return type: void

5.2 Attributes

dir of type DOMString

The dir attribute specifies the directionality of the notification.

No exceptions.
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.

No exceptions.
onclose of type Function

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.

No exceptions.
onerror of type Function

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.

No exceptions.
onshow of type Function

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.

No exceptions.
replaceId of type DOMString

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.

No exceptions.

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

5.4 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.5 Constructor

    Notification Notification ( in DOMString iconUrl,  in DOMString title,  in DOMString body);

Returns a new simple notification object with the provided content.

ParameterTypeDescription
iconUrl DOMString 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.
title DOMString Primary text, or title, of the notification. The user agent may ignore any markup in this string and treat it as plain text.
body DOMString Secondary text, or body, of the notification. The user agent may ignore any markup in this string and treat it as plain text.
No exceptions.

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

6. Queueing and displaying notifications

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

  1. Get the replacement id of the notification to be shown, and let it be replaceId.
  2. 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.
  3. Add the notification to the queue of pending notifications.
  4. Wait until there is available space on the device.
  5. 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.

6.2 Displaying notifications

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

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

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

  1. Fetch the icon resource in new using the algorithm defined in [HTML5].
  2. 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.
  3. Fire the close event on the old notification object.
  4. Fire the show event on the new notification object.
  5. If the underlying notification platform supports replacement, replace old with new on the device.
  6. If the underlying notification platform does not support replacment, remove old from the device and show new on the device.

7. Interacting with notifications

This section is non-normative.

7.1 Using events

This section is non-normative.

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();

A. References

A.1 Normative references

[DOM-LEVEL-3-EVENTS]
Doug Schepers; Björn Höhrmann; Tom Pixley; Philippe Le Hégaret. Document Object Model (DOM) Level 3 Events Specification. 07 September 2010. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2010/WD-DOM-Level-3-Events-20100907
[HTML5]
Ian Hickson. HTML5. Editor’s Draft. (Work in progress.) URL: http://dev.w3.org/html5/spec/
[PERMISSIONS]
John Gregg. Feature Permissions. 12 October 2010. Editor’s Draft. (Work in progress.) URL: http://dev.w3.org/2006/webapi/WebNotifications/publish/FeaturePermissions.html