Copyright © 2015 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
Web notifications defines an API for end-user notifications. A notification allows alerting the user outside the context of a web page of an occurrence, such as the delivery of email.
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 is the 19 May 2015 W3C Candidate Recommendation of Web Notifications. Please send comments to public-web-notification@w3.org (archived).
The W3C Web Notification Working Group is the W3C working group responsible for this specification's progress along the W3C Recommendation track. The Working Group expects to advance this specification to Recommendation status.
A specification for Notifications is also being developed at
https://notifications.spec.whatwg.org/.
Recent work there has focused on integrating notifications with Service
Workers and other new features. That specification also deprecates the
onshow
and onclose
events that are present in
this specification, under the rationale that those events lack sufficient
use cases.
Publication as a Candidate Recommendation 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.
This specification is expected to advance to Proposed Recommendation by 19 June 2015. To exit the Candidate Recommendation stage, the Web Notification Working Group will need to document a sufficient level of user-agent conformance with the requirements in the specification, as measured through the Notifications test suite.
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 display notifications to alert users outside the context of a 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 specification 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 general, the event model for notifications is best-effort; while the
Notification
object offers a click
event,
applications may enhance their functionality by listening for that event,
but cannot depend on receiving it, in case the underlying
notification platform does not provide that capability.
All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.
The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this specification are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]
Notifications should only be presented when the user has indicated they are desired; without this they could create a negative experience for the user.
Most terminology used in this specification is from DOM, HTML, IDL, and URL. [DOM] [HTML] [WEBIDL] [URL]
A notification allows alerting the user outside the context of a web page of an occurrence, such as the delivery of email.
Each notification has a title, direction, language, and an origin.
Each notification can have an associated body, tag, icon URL, and icon image.
Developers are encouraged to not convey information through an icon, sound, or vibration pattern that is not otherwise accessible to the end user.
This section is written in terms equivalent to those used in the Rendering section of HTML. [HTML]
User agents are expected to honor the Unicode semantics of the text of a
notification's title
and body. Each is expected to be treated as an independent set
of one or more bidirectional algorithm paragraphs when displayed, as defined
by the bidirectional algorithm's rules P1, P2, and P3, including, for
instance, supporting the paragraph-breaking behaviour of
U+000A LINE FEED (LF) characters. For each paragraph of the
title and body, the
notification's
direction provides the higher-level override of rules P2 and P3
if it has a value other than "auto
".
[BIDI]
The notification's language specifies the primary language for the notification's title and body. Its value is a valid BCP 47 language tag, or the empty string. The empty string indicates that the primary language is unknown. [LANG]
Notifications can only be displayed if the user (or user agent on behalf of the user) has granted permission. The permission to display notifications for a given origin can be one of three strings:
default
"
This is equivalent to "denied
", but the user has
made no explicit choice thus far.
denied
"
This means the user does not want notifications.
granted
"
This means notifications can be displayed.
There is no equivalent to "default
"
meaning "granted
". In that case
"granted
" is simply returned as there would be no reason
for the application to ask for permission.
The user agent must keep a list of pending notifications and a list of active notifications.
The show steps for a given notification are:
If permission for notification's
origin is not "granted
", cancel any ongoing
fetch for
notification's icon URL,
queue a task to
fire an event
named error
on notification, and
terminate these steps.
If there is a notification in the list of pending notifications or the list of active notifications whose tag equals notification's tag and whose origin equals notification's origin, run the replace steps for that notification and notification, and then terminate these steps.
If the device allows notifications to be displayed immediately without limitations on the number of concurrent notifications, run the display steps and terminate these steps.
If the device has limitations on the number of concurrent notifications, either immediately call to a notification platform which natively supports queueing, or append notification to the list of pending notifications.
When a notification
notification is activated by the user, assuming the underlying
notification platform supports activation, the user agent must, for each
Notification
object representing notification,
queue a task to
fire an event
named click
on the Notification
object.
Throughout the web platform "activate" is intentionally misnamed as "click".
User agents are strongly encouraged to make
window.focus()
work from within
the event listener for the event named click
as a means of focusing the
browsing context related to the notification.
When a notification is closed, either by the underlying notification platform or by the user, the close steps for it must be run.
The close steps for a given notification are:
If notification is neither in the list of pending notifications nor in the list of active notifications, terminate these steps.
Queue a task to remove
notification from either the
list of pending notifications or the
list of active notifications, and
fire an event
named close
on notification.
Whenever the list 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 can be displayed, for example due to a previous notification being dismissed, the user agent should run the display steps for the first notification in the list of pending notifications and then remove it from the list of pending notifications.
The display steps for a given notification are:
If the notification platform supports icons, notification's icon URL is set and has not yet been fetched, fetch it and wait for the resource to be fully downloaded.
Once fetching has finished and the image format is supported, set notification's icon image to the decoded resource. (Otherwise notification has no icon image.)
Queue a task to run these substeps:
Display notification on the device (e.g. by calling the appropriate notification platform).
If displaying fails (e.g. the notification platform returns an
error),
fire an event
named error
on notification and
terminate these steps.
Append notification to the list of active notifications.
Fire an event
named show
on notification.
The replace steps for replacing an old notification with a new one are:
If the notification platform supports icons, new's icon URL is set and has not yet been fetched, fetch it and wait for the resource to be fully downloaded.
Once fetching has finished and the image format is supported, set new's icon image to the decoded resource. (Otherwise new has no icon image.)
If old is in the
list of pending notifications,
queue a task to replace
old with new, in the same position, in
the list of pending notifications, and
fire an event
named close
on old.
Otherwise,
queue a task to replace
old with new, in the same position, in
the list of active notifications,
fire an event
named close
on old, and
fire an event
named show
on new.
If the notification platform does not support replacement this requirement may be addressed by running the close steps for old and then running the display steps for new.
Notification platforms are strongly encouraged to support native replacement. It is much nicer.
A notification is represented by
a Notification
object and can be created by its
constructor.
[Constructor(DOMString title, optional NotificationOptions options)] interface Notification : EventTarget { static readonly attribute NotificationPermission permission; static void requestPermission(optional NotificationPermissionCallback callback); attribute EventHandler onclick; attribute EventHandler onshow; attribute EventHandler onerror; attribute EventHandler onclose; readonly attribute DOMString title; readonly attribute NotificationDirection dir; readonly attribute DOMString lang; readonly attribute DOMString body; readonly attribute DOMString tag; readonly attribute DOMString icon; void close(); }; dictionary NotificationOptions { NotificationDirection dir = "auto"; DOMString lang = ""; DOMString body; DOMString tag; DOMString icon; }; enum NotificationPermission { "default", "denied", "granted" }; callback NotificationPermissionCallback = void (NotificationPermission permission); enum NotificationDirection { "auto", "ltr", "rtl" };
The
Notification(title, options)
constructor must run these steps:
Let notification be a new
notification represented by a
Notification
object.
Set notification's title to title.
Set notification's direction to
options's dir
.
If options's lang
is a valid
BCP 47 language tag, or the empty string, set
notification's language to
options's lang
, or set it to the empty
string otherwise. [LANG]
If options's body
is present,
set notification's body to
body
.
If options's tag
is present, set
notification's tag to tag
.
If options's icon
is present,
parse
icon
using the API base URL
specified by the entry settings object, and if that
does not return failure, set notification's icon URL to the
return value. (Otherwise icon URL is not set.)
Return notification, but continue running these steps asynchronouusly.
If the notification platform supports icons, the user agent may start fetching notification's icon URL at this point, if icon URL is set.
Run the show steps for notification.
The static
permission
attribute must return permission.
The static
requestPermission(callback)
method must run these steps:
Return, but continue running these steps asynchronously.
Let permission be permission.
If permission is "default
",
ask the user whether showing notifications for the current
origin is acceptable. If it is, set
permission to "granted
", or
"denied
" otherwise.
Queue a task to set permission to permission and invoke callback with permission as single argument if callback is given.
In designing the platform notifications are the one instance thus far where asking the user upfront makes sense. Specifications for other APIs should not use this pattern and instead employ one of the many more suitable alternatives.
The following are the event handlers
(and their corresponding
event handler event types)
that must be supported as attributes by the Notification
object.
event handler | event handler event type |
---|---|
onclick
| click
|
onshow
| show
|
onerror
| error
|
onclose
| close
|
The close()
method
must run the close steps for the
notification.
The title
attribute must return the
notification's title.
The dir
attribute must return the
notification's direction.
The lang
attribute must return the
notification's language.
The body
attribute must return the
notification's body and the empty
string otherwise.
The tag
attribute must return the
notification's tag and the empty
string otherwise.
The icon
attribute must return the
notification's icon URL,
serialized, and the
empty string otherwise.
Notification
objects dispatch events during their lifecycle,
which developers can use to generate desired behaviors.
The show
event dispatches 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.
var notification = new Notification("New Email Received", { icon: "mail.png" }) notification.onshow = function() { setTimeout(notification.close, 15000) }
The close
event dispatches when the
notification is dismissed by the user. Developers 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("Meeting about to begin", { icon: "calendar.gif", body: "Room 101" }) notification.onclose = function(event) { cancelReminders(event) }
tag
member for multiple instancesWeb 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, the notifications API provides a way for these instances to easily coordinate, by
using the tag
member.
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.
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".
tag
member for a single instanceThe tag
member 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.
// 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.
Thanks to Aharon (Vladimir) Lanin, Alex Russell, David Håsäther, Doug Turner, Drew Wilson, Jake Archibald, Edward O'Connor, Frederick Hirsch, Ian Hickson, James Graham, Jon Lee, Jonas Sicking, Michael Cooper, Michael Henretty, Olli Pettay, and Simon Pieters for being awesome. Special thanks to Anne van Kesteren for his continuing work on the WHATWG's Notifications API Standard.