W3C

Web Notifications

W3C Working Draft 14 June 2012

This Version:
http://www.w3.org/TR/2012/WD-notifications-20120614/
Latest Version:
http://www.w3.org/TR/notifications/
Latest Editors Draft:
http://dvcs.w3.org/hg/notifications/raw-file/tip/Overview.html
Version History:
http://dvcs.w3.org/hg/notifications/shortlog
Previous Version:
http://www.w3.org/TR/2011/WD-notifications-20110301/
Editors:
Anne van Kesteren (Opera Software ASA) <annevk@annevk.nl>
John Gregg (Google) <johnnyg@google.com>

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 is the 14 June 2012 W3C Working Draft of Web Notifications. Please send comments to public-web-notification@w3.org (archived).

This document was developed by the Web Notification Working Group. The Working Group expects to advance this Working Draft to Recommendation Status.

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.

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. 1 Introduction
  2. 2 Conformance
    1. 2.1 Security
  3. 3 Terminology
  4. 4 Model
    1. 4.1 Permission
    2. 4.2 Notification lists
    3. 4.3 Showing a notification
    4. 4.4 Closing a notification
    5. 4.5 Pending notifications
    6. 4.6 Displaying notifications
    7. 4.7 Replacing a notification
  5. 5 API
  6. 6 Rendering
  7. 7 Examples
    1. 7.1 Using events
    2. 7.2 Using the tag member for multiple instances
    3. 7.3 Using the tag member for a single instance
  8. References
  9. Acknowledgments

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:

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

Each notification can have an associated body, tag, and icon URL.

4.1 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.2 Notification lists

The user agent must keep a list of pending notifications and a list of active notifications.

4.3 Showing a notification

The show steps for a given notification are:

  1. If permission for the current 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.

  2. If there is a notification in the list of pending notifications or the list of active notifications whose tag equals notification's tag, run the replace steps and terminate these steps.

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

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

The close steps for a given notification are:

  1. If notification is neither in the list of pending notifications nor in the list of active notifications, terminate these steps.

  2. 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.5 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.6 Displaying notifications

The display steps for a given notification are:

  1. If the notification platform supports icons and notification's icon URL has not yet been fetched, fetch it and wait for the resource to be fully downloaded.

  2. If fetching notification's icon URL failed for some reason or the image format is not supported, queue a task to fire an event named error on notification and terminate these steps.

  3. Queue a task to display notification on the device (e.g. by calling the appropriate notification platform), append notification to the list of active notifications, and fire an event named show on notification.

4.7 Replacing a notification

The replace steps for replacing an old notification with a new one are:

  1. If the notification platform supports icons and new's icon URL has not yet been fetched, fetch it and wait for the resource to be fully downloaded.

  2. If fetching new's icon URL failed for some reason or the image format is not supported, queue a task to fire an event named error on new and terminate these steps.

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

  4. 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 removal and addition instead.

5 API

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

  [TreatNonCallableAsNull] attribute Function? onclick;
  [TreatNonCallableAsNull] attribute Function? onshow;
  [TreatNonCallableAsNull] attribute Function? onerror;
  [TreatNonCallableAsNull] attribute Function? onclose;

  void close();
};

dictionary NotificationOptions {
  NotificationDirection titleDir;
  DOMString body;
  NotificationDirection bodyDir;
  DOMString tag;
  DOMString iconUrl;
};

enum NotificationPermission {
  "default",
  "denied",
  "granted"
};

callback NotificationPermissionCallback = void (NotificationPermission permission);

enum NotificationDirection {
  "auto",
  "ltr",
  "rtl"
};

Web IDL is not yet updated to allow for static attributes.

The Notification(title, options) constructor must run these steps:

  1. Let notification be a new notification represented by a Notification object.

  2. Set notification's title to title, converted to Unicode.

  3. If options is not omitted and its titleDir member is not null, set notification's title direction to titleDir.

  4. If options is not omitted and its body is not null, set notification's body to body, converted to Unicode.

  5. If options is not omitted and its bodyDir member is not null, set notification's body direction to bodyDir.

  6. If options is not omitted and its tag is not null, set notification's tag to tag.

  7. If options is not omitted and its iconUrl is not null, set notification's icon URL to iconUrl.

  8. Return notification, but continue running these steps asynchronouusly.

  9. If the notification platform supports icons, the user agent may start fetching notification's icon URL at this point.

  10. Run the show steps for notification.

The static permission attribute must return permission.

The static requestPermission(callback) method must run these steps:

  1. Return, but continue running these steps asynchronously.

  2. Let permission be permission.

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

  4. Queue a task to set permission to permission and invoke callback with permission as single argument.

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.

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.

new Notification("New Email Received",
                 { iconUrl: "mail.png",
                   onshow: function() { setTimeout(notification.close(), 15000); }
                 });

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.

new Notification("Meeting about to begin",
                 { iconUrl: "calendar.gif",
                   body: "Room 101",
                   onclose: function() { cancelReminders(event); }
                 });

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.

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

7.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.
[DOM]
DOM4, Anne van Kesteren, Aryeh Gregor and Ms2ger. W3C.
[HTML]
HTML5, Ian Hickson. W3C.
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels, Scott Bradner. IETF.

Acknowledgments

Thanks to Aharon (Vladimir) Lanin, Alex Russell, Doug Turner, Drew Wilson, Edward O'Connor, Ian Hickson, James Graham, Jon Lee, and Jonas Sicking for being awesome.