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

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.

1 Introduction

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:

A corner of the user's display.

An area within the chrome of the user agent.

The "home" screen of a mobile device.

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 a click 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.

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

3 Terminology

Most terminology used in this specification is from DOM and HTML.
[DOM][HTML]

4 Model

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. For specification simplicity each
notification also has a
title direction and body direction, both of which are
initially "auto".

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 notifications platform which
natively supports queueing, or append notification to the
list of pending notifications.

4.4 Closing a notification

When a notification is closed,
either by the underlying notifications platform or by the user, the
close steps for it must be run.

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.

6 Rendering

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
title direction and body direction respectively
provide the higher-level override of rules P2 and P3 if they have a value
other than "auto".
[BIDI]

7 Examples

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.

7.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, Web Notifications 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.

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.