Web Notifications

Web Notifications
Web Notifications
W3C Recommendation 22 October 2015
This Version:
Latest Version:
Version History:
Previous Versions:
Editor (former):
John Gregg (
Google
johnnyg@google.com
Editor (
version):
Anne van Kesteren
Mozilla
annevk@annevk.nl
Please check the
errata
for any errors or issues reported since publication.
The English version of this specification is the only normative version. Non-normative
translations
may also be available.
W3C
MIT
ERCIM
Keio
Beihang
). W3C
liability
trademark
and
document use
rules apply.
Abstract
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.
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 is the W3C Recommendation of Web Notifications.
This document has been reviewed by
W3C
Members,
by software developers, and by other
W3C
groups
and interested parties,
and is endorsed by the Director as a
W3C
Recommendation. It is a stable document and may be used as reference
material or cited from another document.
W3C
's role in making the
Recommendation is to draw attention to the specification and to promote its
widespread deployment. This enhances the functionality and
interoperability of the Web.
The W3C
Web Notification Working Group
was the W3C working group responsible for this specification's publication
as a W3C Recommendation.
If you wish to make comments regarding this document, please send them to
public-web-notification@w3.org
archive
).
The W3C expects the functionality specified in this
Recommendation will not be affected by changes to
[DOM4]
or
[WEBIDL]
as those specifications proceed to Recommendation.
Please see also the
test suite
and
implementation report
for this specification.
A specification for Notifications is also being developed at
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.
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 document is governed by the
1 September 2015
W3C
Process Document
Table of Contents
Introduction
Conformance
2.1
Security
Terminology
Model
4.1
Direction
4.2
Language
4.3
Permission
4.4
Notification lists
4.5
Showing a notification
4.6
Activating a notification
4.7
Closing a notification
4.8
Pending notifications
4.9
Displaying notifications
4.10
Replacing a notification
API
Examples
6.1
Using events
6.2
Using the
tag
member for multiple instances
6.3
Using the
tag
member for a single instance
References
Acknowledgments
Introduction
This specification provides an API to display notifications to alert
users outside the context of a web page. When this specification refers
to displaying notifications on the "desktop", it generally refers to
some static display area outside the web page, but that 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.
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. 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 can only
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.
Conformance
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]
2.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.
Terminology
Most terminology used in this specification is from DOM, HTML, IDL, and URL.
[DOM4]
[HTML5]
[WEBIDL]
[URL]
Model
notification
allows alerting the
user outside the context of a web page that something happened, 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.
See
WCAG
for more.
4.1
Direction
This section is written in terms equivalent to those used in the
Rendering section of HTML.
[HTML5]
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 behavior 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]
4.2
Language
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]
4.3
Permission
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
4.4
Notification lists
The user agent must keep a
list of pending notifications
and
list of active notifications
4.5
Showing a notification
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
4.6
Activating a notification
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.
4.7
Closing a 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
4.8
Pending notifications
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
4.9
Displaying 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 if the image format is supported, set
notification
's
icon image
to the decoded resource.
Queue a task
to run these substeps:
Display
notification
on the device (e.g. by
making the appropriate notification platform API call).
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
4.10
Replacing a 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.
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.
API
notification
is represented by
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
. Otherwise, set it
to the empty string.
[LANG]
Set
notifications
's
origin
to the
current
origin
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.
Return
notification
, but continue running these
steps asynchronously.
If
icon URL
is set and the notification platform
supports icons, the user agent may start
fetching
the
notification
's
icon URL
at this
point.
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
or the empty
string if it has no tag.
The
icon
attribute must return the
notification
's
icon URL
serialized
, and the
empty string otherwise.
Examples
6.1
Using events
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) }
6.2
Using the
tag
member 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, 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".
6.3
Using the
tag
member for a single instance
The
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.
References
[BIDI]
Unicode Bidirectional Algorithm
, Mark Davis. Unicode Consortium.
[DOM4]
DOM
, Anne van Kesteren, Aryeh Gregor, Ms2ger et al.. W3C.
[HTML5]
HTML5
, Robin Berjon, Steve Faulkner, Travis Leithead et al.. W3C.
[LANG]
Tags for Identifying Languages; Matching of Language Tags
, Addison Phillips and Mark Davis. IETF.
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels
, Scott Bradner. IETF.
[URL]
URL
, Eric Arvidsson, Michael[tm] Smith. W3C.
[WEBIDL]
Web IDL
, Cameron McCormack. W3C.
Acknowledgments
Thanks to
Aharon (Vladimir) Lanin,
Alex Russell,
David Håsäther,
Doug Turner,
Drew Wilson,
Jake Archibald,
Theresa O'Connor,
Frederick Hirsch,
Ian Hickson,
James Graham,
Jon Lee,
Jonas Sicking,
Josh Soref,
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