Notifications API (PR #76)

1. Terminology

Some terms used in this specification are defined in the DOM, Fetch, HTML, IDL, URL and Vibration API Standards. [DOM] [FETCH] [HTML] [WEBIDL] [URL] [VIBRATION]

2. Notifications

A notification is an abstract representation of something that happened, such as the delivery of a message.

A notification has an associated title which is a DOMString.

A notification has an associated body which is a DOMString.

A notification has an associated direction which is one of auto, ltr, and rtl.

A notification has an associated language which is a DOMString representing either a valid BCP 47 language tag or the empty string.

A notification has an associated tag which is a DOMString.

A notification has an associated data.

A notification has an associated timestamp which is a DOMTimeStamp representing the time, in milliseconds since 00:00:00 UTC on 1 January 1970, of the event for which the notification was created.

Timestamps can be used to indicate the time at which a notification is actual. For example, this could be in the past when a notification is used for a message that couldn’t immediately be delivered because the device was offline, or in the future for a meeting that is about to start.

A notification has an associated origin.

A notification has an associated renotify preference flag which is initially unset. When set indicates that the end user should be alerted after the replace steps have run.

A notification has an associated silent preference flag which is initially unset. When set indicates that no sounds or vibrations should be made.

A notification has an associated screen off preference flag which is initially unset. When set indicates that the screen of the device should not be enabled.

A notification has an associated require interaction preference flag which is initially unset. When set, indicates that on devices with a sufficiently large screen, the notification should remain readily available until the user activates or dismisses the notification.

A notification has an associated sticky preference flag which is initially unset. When set indicates that the end user should not be able to easily clear the notification Only makes sense for persistent notifications.

A notification can have an associated icon URL, icon resource, sound URL, sound resource, vibration pattern, and service worker registration.

A notification can have an associated badge URL and badge resource. A badge resource may be used to represent the notification when there is not enough space to display the notification itself. It may also be displayed inside the notification, but then it should have less visual priority than the icon resource.

Developers are encouraged to not convey information through an icon, badge, sound, or vibration pattern that is not otherwise accessible to the end user.

A notification has an associated list of zero or more actions. Each action has an associated title and action name and can have an associated action icon URL and action icon resource. Users may activate actions, as alternatives to activating the notification itself. The user agent must determine the maximum number of actions supported, within the constraints of the notification platform.

Since display of actions is platform-dependent, developers are encouraged to make sure that any action a user can invoke from a notification is also available within the web application.

Some platforms may modify an action icon resource to better match the platform’s visual style before displaying it to the user, for example by rounding the corners or painting it in a specific color. It is recommended to use an icon that handles such cases gracefully and does not lose important information through, e.g., loss of color or clipped corners.

A non-persistent notification is a notification without an associated service worker registration.

A persistent notification is a notification with an associated service worker registration.

A notification is considered to be replaceable if there is a notification in the list of notifications whose tag is not the empty string and equals the notification’s tag, and whose origin is same origin with notification’s origin.

To create a notification, given a title, options, and optionally a serviceWorkerRegistration, run these steps:

1. Let notification be a new notification.

2. If a serviceWorkerRegistration was provided, set notification’s service worker registration to serviceWorkerRegistration.

3. If a serviceWorkerRegistration was not provided and options’s actions is not empty, throw a TypeError exception.

   Actions are only currently supported for persistent notifications.

4. If options’s silent is true, and either options’s sound is present or options’s vibrate is present, throw a TypeError exception.

5. If options’s renotify is true and options’s tag is the empty string, throw a TypeError exception.

6. Set notification’s data to a structured clone of options’s data. Rethrow any exceptions.

7. Set notification’s title to options’s title.

8. Set notification’s direction to options’s dir.

9. Set notification’s language to options’s lang.

10. Set notification’s origin to the entry settings object’s origin.

11. Set notification’s body to options’s body.

12. Set notification’s tag to options’s tag.

13. Let baseURL be the API base URL specified by the entry settings object. Or incumbent?

14. Run the icon URL selection steps, providing options’s icons, options’s icon, and baseURL, and if that does not return null, set notification’s icon URL to the return value. (Otherwise icon URL is not set.)

15. Run the icon URL selection steps, providing options’s badges, options’s badge, and baseURL, and if that does not return null, set notification’s badge URL to the return value. (Otherwise badge URL is not set.)

16. If options’s sound is present, parse it using baseURL, and if that does not return failure, set notification’s sound URL to the return value. (Otherwise sound URL is not set.)

17. If options’s vibrate is present, validate and normalize it and set notification’s vibration pattern to the return value. (Otherwise vibration pattern is not set.)

18. If options’s timestamp is present, set notification’s timestamp to the value. Otherwise, set notification’s timestamp to the number of milliseconds that passed between 00:00:00 UTC on 1 January 1970 and the time at which the Notification constructor was called.

19. If options’s renotify is true, set notification’s renotify preference flag.

20. If options’s silent is true, set notification’s silent preference flag.

21. If options’s noscreen is true, set notification’s screen off preference flag.

22. If options’s requireInteraction is true, set notification’s require interaction preference flag.

23. If options’s sticky is true, set notification’s sticky preference flag.

24. Set notification’s list of actions to an empty list, then for each entry in options’s actions, up to the maximum number of actions supported (skip any excess entries), perform the following steps:

    1. Let action be a new action.

    2. Set action’s action name to the entry’s action.

    3. Set action’s title to the entry’s title.

    4. Run the icon URL selection steps, providing entry’s icons, entry’s icon, and baseURL, and if that does not return null, set actions’s action icon URL to the return value. (Otherwise action icon URL is not set.)

    5. Append action to notification’s list of actions.

25. Return notification.

2.1. Lifetime and UI integration

The user agent must keep a list of notifications that consists of zero or more notifications.

User agents should run the close steps for a non-persistent notification a couple of seconds after they have been created.

User agents should not display non-persistent notification in a platform’s "notification center" (if available).

User agents should persist persistent notifications until they are removed from the list of notifications.

A persistent notification could have the close() method invoked of one of its Notification objects.

User agents should display persistent notifications in a platform’s "notification center" (if available).

2.2. Permission model

Notifications can only be displayed if the user (or user agent on behalf of the user) has granted permission. The permission to show notifications for a given origin is 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.

2.3. Direction

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, body, and the title of each of its actions. 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, body and the title of each of the actions, 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 direction also determines the relative order in which the notification’s actions should be displayed to the user, if the notification platform displays them side by side.

2.4. Language

The notification’s language specifies the primary language for the notification’s title, body and the title of each of its actions. Its value is a string. The empty string indicates that the primary language is unknown. Any other string must be interpreted as a language tag. Validity or well-formedness are not enforced. [LANG]

Developers are encouraged to only use valid language tags.

2.5. Resources

The fetch steps for a given notification notification are:

1. If the notification platform supports icons, fetch notification’s icon URL, if icon URL is set.

   Then, in parallel:

   1. Wait for the response.

   2. If the response’s internal response’s type is default, attempt to decode the resource as image.

   3. If the image format is supported, set notification’s icon resource to the decoded resource. (Otherwise notification has no icon resource.)

2. If the notification platform supports badges, fetch notification’s badge URL, if badge URL is set.

   Then, in parallel:

   1. Wait for the response.

   2. If the response’s internal response’s type is default, attempt to decode the resource as image.

   3. If the image format is supported, set notification’s badge resource to the decoded resource. (Otherwise notification has no badge resource.)

3. If the notification platform supports actions and action icons, then for each action in notification’s list of actions fetch action’s action icon URL, if action icon URL is set.

   Then, in parallel:

   1. Wait for the response.

   2. If the response’s internal response’s type is default, attempt to decode the resource as image.

   3. If the image format is supported, set action’s action icon resource to the decoded resource. (Otherwise action has no action icon resource.)

4. If the notification platform supports sounds, and the notification is either not replaceable or has the renotify preference flag set, fetch notification’s sound URL if it has been set.

   Then, in parallel:

   1. Wait for the response.

   2. If the response’s internal response’s type is default, attempt to decode the resource as sound.

   3. If the sound format is supported, set notification’s sound resource to the decoded resource. (Otherwise notification has no sound resource.)

2.6. Showing a notification

The show steps for a given notification notification are:

1. If notification is replaceable, run the replace steps for that notification and notification, and then terminate these steps.

2. Otherwise, run the display steps for notification.

2.7. Activating a notification

When a notification notification, or one of its actions, is activated by the user, assuming the underlying notification platform supports activation, the user agent must (unless otherwise specified) run these steps:

1. If notification is a persistent notification, run these substeps:

   1. Let action be the empty string.

   2. If one of notification’s actions was activated by the user, set action to that action’s action name string.

   3. Let callback be an algorithm that when invoked with a global, fires a service worker notification event named notificationclick given notification and action on global.

   4. Then run Handle Functional Event with notification’s service worker registration and callback.

2. Otherwise, queue a task to run these substeps:

   1. Fire an event named click with its cancelable attribute initialized to true on the Notification object representing notification.

      User agents are encouraged to make window.focus() work from within the event listener for the event named click.

   2. If the event’s canceled flag is unset, the user agent should bring the notification’s related browsing context’s viewport into focus.

Throughout the web platform "activate" is intentionally misnamed as "click".

2.8. 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:

1. If notification is not in the list of notifications, terminate these steps.

2. If notification is a persistent notification and notification was closed by the user, run these substeps:

   1. Let callback be an algorithm that when invoked with a global, fires a service worker notification event named notificationclose given notification on global.

   2. Then run Handle Functional Event with notification’s service worker registration and callback.

3. Remove notification from the list of notifications.

2.9. Displaying notifications

The display steps for a given notification are:

1. Wait for any fetches to complete and notification’s icon resource, badge resource, and sound resource to be set (if any), as well as the action icon resources for the notification’s actions (if any).

2. Display notification on the device (e.g., by calling the appropriate notification platform API).

3. Run the alert steps for notification.

4. Append notification to the list of notifications.

2.10. Replacing a notification

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

1. Wait for any fetches to complete and notification’s icon resource, badge resource, and sound resource to be set (if any), as well as the action icon resources for the notification’s actions (if any).

2. Replace old with new, in the same position, in the list of notifications.

3. If notification’s renotify preference flag has been set, perform the alert steps for 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 and has no side effects, such as playing sounds or vibrating the device again, unless the renotify preference flag is set.

2.11. Alerting the user

The alert steps for alerting the user about a given notification are:

1. Play the notification’s sound resource, if any.

2. Perform vibration using notification’s vibration pattern, if any.

2.12. Selecting an icon URL

The user agent should select the most suitable icon while balancing multiple goals and constraints: high quality icon display, screen size, and availability of resources like memory and bandwidth.

The icon URL selection steps for selecting a URL given a list icons of type NotificationIconOptions, a fallbackURLString of type USVString, and base URL baseURL are:

1. Let selectedURL and selectedIcon be null.

2. For each icon in icons run these substeps:

   1. Let iconURL be the result of parsing icon’s src using baseURL. If iconURL is failure, abort these substeps for this icon.

   2. Let parsedSizes be the result of parsing icon’s sizes.

   3. If icon is considered by the implementation to be more suitable than selectedIcon, taking into account whether icon’s type is valid and supported, as well as the value of parsedSizes, then set selectedURL to iconURL and set selectedIcon to icon.

3. If selectedURL is null, parse fallbackURLString using baseURL, and if that does not return failure, set selectedURL to the return value.

4. Return selectedURL.

3. API

[Constructor(DOMString title, optional NotificationOptions options),
 Exposed=(Window,Worker)]
interface Notification : EventTarget {
  static readonly attribute NotificationPermission permission;
  [Exposed=Window] static Promise<NotificationPermission> requestPermission(optional NotificationPermissionCallback deprecatedCallback);

  static readonly attribute unsigned long maxActions;

  attribute EventHandler onclick;
  attribute EventHandler onerror;

  readonly attribute DOMString title;
  readonly attribute NotificationDirection dir;
  readonly attribute DOMString lang;
  readonly attribute DOMString body;
  readonly attribute DOMString tag;
  readonly attribute USVString icon;
  readonly attribute USVString badge;
  readonly attribute USVString sound;
  [SameObject] readonly attribute FrozenArray<unsigned long> vibrate;
  readonly attribute DOMTimeStamp timestamp;
  readonly attribute boolean renotify;
  readonly attribute boolean silent;
  readonly attribute boolean noscreen;
  readonly attribute boolean requireInteraction;
  readonly attribute boolean sticky;
  [SameObject] readonly attribute any data;
  [SameObject] readonly attribute FrozenArray<NotificationAction> actions;

  void close();
};

dictionary NotificationOptions {
  NotificationDirection dir = "auto";
  DOMString lang = "";
  DOMString body = "";
  DOMString tag = "";
  USVString icon;
  sequence<NotificationIconOptions> icons = [];
  USVString badge;
  sequence<NotificationIconOptions> badges = [];
  USVString sound;
  VibratePattern vibrate;
  DOMTimeStamp timestamp;
  boolean renotify = false;
  boolean silent = false;
  boolean noscreen = false;
  boolean requireInteraction = false;
  boolean sticky = false;
  any data = null;
  sequence<NotificationActionOptions> actions = [];
};

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

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

interface NotificationAction {
  readonly attribute DOMString action;
  readonly attribute DOMString title;
  readonly attribute USVString icon;
};

dictionary NotificationActionOptions {
  required DOMString action;
  required DOMString title;
  USVString icon;
  sequence<NotificationIconOptions> icons = [];
};

dictionary NotificationIconOptions {
  required USVString src;
  DOMString type;
  DOMString sizes;
};

callback NotificationPermissionCallback = void (NotificationPermission permission);

A non-persistent notification is represented by one Notification object and can be created through Notification's constructor.

A persistent notification is represented by zero or more Notification objects and can be created through the showNotification() method.

3.1. Garbage collection

A Notification object must not be garbage collected while its corresponding notification is in the list of notifications and the Notification object in question has an event listener whose type is click or error.

3.2. Constructors

The Notification(title, options) constructor, when invoked, must (unless otherwise indicated) run these steps:

1. If options’s sticky is present, throw a TypeError exception.

2. If the entry settings object’s global object is a ServiceWorkerGlobalScope object, throw a TypeError exception.

3. Let notification be the result of creating a notification given title and options. Rethrow any exceptions.

4. Let n be a new Notification object associated with notification.

5. Run these substeps in parallel:

   1. If permission for notification’s origin is not "granted", queue a task to fire an event named error on n, and terminate these substeps.

   2. Run the fetch steps for notification.

   3. Run the show steps for notification.

6. Return n.

3.3. Static members

The static permission attribute’s getter must return permission for the entry settings object’s origin.

If you edit standards please refrain from copying the above. Synchronous permissions are like synchronous IO, a bad idea.

The static requestPermission(deprecatedCallback) method, when invoked, must run these steps:

1. Let promise be a new promise.

2. Run these substeps in parallel:

   1. Let permission be permission for entry settings object’s origin.

   2. If permission is "default", ask the user whether showing notifications for the entry settings object’s origin is acceptable. If it is, set permission to "granted", and "denied" otherwise.

   3. Queue a task to run these subsubsteps:

      1. Set permission for the entry settings object’s origin to permission.

      2. If deprecatedCallback is given, invoke deprecatedCallback with permission as single argument. If this throws an exception, report the exception.

      3. Fullfil promise with permission.

3. Return promise.

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 static maxActions attribute’s getter must return the maximum number of actions supported.

3.4. Object members

The following are the event handlers (and their corresponding event handler event types) that must be supported as attributes by the Notification object.

The close() method, when invoked, must run the close steps for the notification.

The title attribute’s getter must return the notification’s title.

The dir attribute’s getter must return the notification’s direction.

The lang attribute’s getter must return the notification’s language.

The body attribute’s getter must return the notification’s body.

The tag attribute’s getter must return the notification’s tag.

The icon attribute’s getter must return the notification’s icon URL, serialized, and the empty string if there is no notification’s icon URL otherwise.

The badge attribute’s getter must return the notification’s badge URL, serialized, and the empty string if there is no notification’s badge URL otherwise.

The sound attribute’s getter must return the notification’s sound URL, serialized, and the empty string if there is no notification’s sound URL otherwise.

The vibrate attribute’s getter must return the notification’s vibration pattern, if any, and the empty list otherwise.

The timestamp attribute’s getter must return the notification’s timestamp.

The renotify attribute’s getter must return the notification’s renotify preference flag.

The silent attribute’s getter must return the notification’s silent preference flag.

The noscreen attribute’s getter must return the notification’s screen off preference flag.

The requireInteraction attribute’s getter must return the notification’s require interaction preference flag.

The sticky attribute’s getter must return the notification’s sticky preference flag.

The data attribute’s getter must return a structured clone of notification’s data.

The actions attribute’s getter must return the result of the following steps:

1. Let list be an empty list of type NotificationAction.

2. For each entry in the notification’s list of actions, perform the following steps:

   1. Let action be a new NotificationAction.

   2. Set action’s action to entry’s action name.

   3. Set action’s title to entry’s title.

   4. Set action’s icon to entry’s action icon URL.

   5. Append action to list.

3. Create a frozen array from list.

3.5. Examples

3.5.1. Using events from a page

Non-persistent Notification objects dispatch events during their lifecycle, which developers can use to generate desired behaviors.

The click event dispatches when the user activates a notification.

var not = new Notification("Gebrünn Gebrünn by Paul Kalkbrenner", { icon: "newsong.svg", tag: "song" });
not.onclick = function() { displaySong(this); };

3.5.2. Using actions from a service worker

Persistent notifications fire notificationclick events on the ServiceWorkerGlobalScope.

Here a service worker shows a notification with a single "Archive" action, allowing users to perform this common task from the notification without having to open the website (for example the notification platform might show a button on the notification). The user can also activate the main body of the notification to open their inbox.

self.registration.showNotification("New mail from Alice", {
  actions: [{action: 'archive', title: "Archive"}]
});

self.addEventListener('notificationclick', function(event) {
  event.notification.close();
  if (event.action === 'archive') {
    silentlyArchiveEmail();
  } else {
    clients.openWindow("/inbox");
  }
}, false);

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

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

4. Service worker API

dictionary GetNotificationOptions {
  DOMString tag = "";
};

partial interface ServiceWorkerRegistration {
  Promise<void> showNotification(DOMString title, optional NotificationOptions options);
  Promise<sequence<Notification>> getNotifications(optional GetNotificationOptions filter);
};

[Constructor(DOMString type, NotificationEventInit eventInitDict),
 Exposed=ServiceWorker]
interface NotificationEvent : ExtendableEvent {
  readonly attribute Notification notification;
  readonly attribute DOMString action;
};

dictionary NotificationEventInit : ExtendableEventInit {
  required Notification notification;
  DOMString action = "";
};

partial interface ServiceWorkerGlobalScope {
  attribute EventHandler onnotificationclick;
  attribute EventHandler onnotificationclose;
};

The showNotification(title, options) method, when invoked, must run these steps:

1. Let promise be a new promise.

2. If the context object’s active worker is null, reject promise with a TypeError exception and return promise.

3. Let serviceWorkerRegistration be the context object.

4. Let notification be the result of creating a notification given title, options and serviceWorkerRegistration. If this threw an exception, reject promise with that exception and return promise.

5. Run these substeps in parallel:

   1. If permission for notification’s origin is not "granted", reject promise with a TypeError exception, and terminate these substeps.

   2. Otherwise, resolve promise with undefined.

   3. Run the fetch steps for notification.

   4. Run the show steps for notification.

6. Return promise.

The getNotifications(filter) method, when invoked, must run these steps:

1. Let promise be a new promise.

2. Run these substeps in parallel:

   1. Let tag be filter’s tag.

   2. Let notifications be a list of all notifications in the list of notifications whose origin is the entry settings object’s origin, whose service worker registration is the context object, and whose tag, if tag is not the empty string, is tag.

   3. Let objects be an empty JavaScript array.

   4. For each notification in notifications, in creation order, create a new Notification object representing notification and push that object to objects.

   5. Resolve promise with objects.

3. Return promise.

This method returns zero or more new Notification objects which might represent the same underlying notification of Notification objects already in existence.

To fire a service worker notification event named e given notification and action, fire an event named e with an event using the NotificationEvent interface whose notification attribute is initialized to a new Notification object representing notification, and whose action attribute is initialized to action.

The notification attribute’s getter must return the value it was initialized to.

The action attribute’s getter must return the value it was initialized to.

The following is the event handler (and its corresponding event handler event type) that must be supported as attribute by the ServiceWorkerGlobalScope object:

Acknowledgments

Thanks to Addison Phillips, Aharon (Vladimir) Lanin, Alex Russell, Anssi Kostiainen, Arkadiusz Michalski, Boris Zbarsky, David Håsäther, Doug Turner, Drew Wilson, Edward O’Connor, Ehsan Akhgari, Frederick Hirsch, Ian Hickson, Jake Archibald, James Graham, John Mellor, Jon Lee, Jonas Sicking, Michael Cooper, Michael Henretty, Michael™ Smith, Michael van Ouwerkerk, Nicolás Satragno, Olli Pettay, Peter Beverloo, Philip Jägenstedt, Reuben Morais, Rich Tibbett, Robert Bindar, 박상현 (Sanghyun Park), Simon Pieters, and timeless for being awesome.

This standard is written by Anne van Kesteren (Mozilla, annevk@annevk.nl). An earlier iteration was written by John Gregg (Google, johnnyg@google.com).

Per CC0, to the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work.

Intellectual property rights

Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). This work is licensed under a Creative Commons Attribution 4.0 International License.