Copyright © 2011 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This document defines an API for displaying simple notifications to the user.
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.
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 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.
Notifications should only be presented when the user has indicated they are desired; without this they could create a negative experience for the user.
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.
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;
};
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.
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
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 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.
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.
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.
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.
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.
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 |
Notification Notification ( in DOMString iconUrl, in DOMString title, in DOMString body);
Returns a new simple notification object with the provided content.
| Parameter | Type | Description |
|---|---|---|
| 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. |
When the Notification() constructor is invoked, the user agent must return a new Notification object.
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.
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.
When a user agent is to display a notification, the user agent should perform the following steps:
iconUrl using the algorithm defined in [HTML5].
error event on the notification
object and stop executing this algorithm.
show event on the notification object.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.
error event on the new notification
object and stop executing this algorithm, returning the error information. The old notification is not affected.
close event on the old notification object.show event on the new notification object.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();