notifications.spec.whatwg.orgNotifications API Standard

Notifications API Living Standard — Last Updated 4 April 2024 Participate: GitHub whatwg/notifications ( new issue , open issues ) Chat on Matrix Commits: GitHub whatwg/notifications/commits Snapshot as of this commit @notifyapi Tests: web-platform-tests notifications/ ( ongoing work ) Translations (non-normative) : 日本語 简体中文 Abstract This standard defines an API to display notifications to the end user, typically outside the top-level browsing context’s viewport. It is designed to be compatible with existing notification systems, while remaining platform-independent. Table of Contents 1 Terminology 2 Notifications 2.1 Lifetime and UI integration 2.2 Permissions integration 2.3 Direction 2.4 Language 2.5 Resources 2.6 Showing a notification 2.7 Activating a notification 2.8 Closing a notification 2.9 Alerting the user 3 API 3.1 Garbage collection 3.2 Constructors 3.3 Static members 3.4 Object members 3.5 Examples 3.5.1 Using events from a page 3.5.2 Using actions from a service worker 3.5.3 Using the tag member for multiple instances 3.5.4 Using the tag member for a single instance 4 Service worker API Acknowledgments Intellectual property rights Index Terms defined by this specification Terms defined by reference References Normative References IDL Index 1. Terminology This specification depends on the Infra Standard. [INFRA] Some terms used in this specification are defined in the DOM, Fetch, High Resolution Time, HTML, IDL, Service Workers, URL, and Vibration API Standards. [DOM] [FETCH] [HR-TIME] [HTML] [WEBIDL] [SERVICE-WORKERS] [URL] [VIBRATION] 2. Notifications A notification is an abstract representation of something that happened, such as the delivery of a message. A notification can have an associated service worker registration . 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 an EpochTimeStamp representing the time. 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 boolean, which is initially false. When true, indicates that the end user should be alerted after the show steps have run with a new notification that has the same tag as an existing notification. A notification has an associated silent preference boolean or null, which is initially null. When true, indicates that no sounds or vibrations should be made. When null, indicates that producing sounds or vibrations should be left to platform conventions. A notification has an associated require interaction preference boolean, which is initially false. When true, 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 can have these associated graphics: an image URL , icon URL , and badge URL ; and their corresponding image resource , icon resource , and badge resource . An image resource is a picture shown as part of the content of the notification , and should be displayed with higher visual priority than the icon resource and badge resource , though it may be displayed in fewer circumstances. An icon resource is an image that reinforces the notification (such as an icon, or a photo of the sender). A badge resource is an icon representing the web application, or the category of the notification if the web application sends a wide variety of notifications . It 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 image resource and icon resource . A notification has an associated vibration pattern , which is initially « ». Developers are encouraged to not convey information through an image , icon , badge , or vibration pattern that is not otherwise accessible to the end user, especially since notification platforms that do not support these features might ignore them. A notification has an associated list of zero or more actions . Each action has an associated title and name and can have an associated icon URL and 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 might modify an 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. Developers are encouraged 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 . To create a notification , given a string title , NotificationOptions dictionary options , environment settings object settings , and optionally a ServiceWorkerRegistration object serviceWorkerRegistration , run these steps: Let notification be a new notification . If a serviceWorkerRegistration was provided, then set notification ’s service worker registration to serviceWorkerRegistration . If a serviceWorkerRegistration was not provided and options [" actions "] is not empty , then throw a TypeError . Actions are only currently supported for persistent notifications . If options [" silent "] is true and options [" vibrate "] exists , then throw a TypeError . If options [" renotify "] is true and options [" tag "] is the empty string, then throw a TypeError . Set notification ’s data to StructuredSerializeForStorage ( options [" data "]). Set notification ’s title to title . Set notification ’s direction to options [" dir "]. Set notification ’s language to options [" lang "]. Set notification ’s origin to settings ’s origin . Set notification ’s body to options [" body "]. Set notification ’s tag to options [" tag "]. Let baseURL be settings ’s API base URL . If options [" image "] exists , then parse it using baseURL , and if that does not return failure, set notification ’s image URL to the return value. (Otherwise image URL is not set.) If options [" icon "] exists , then parse it using baseURL , and if that does not return failure, set notification ’s icon URL to the return value. (Otherwise icon URL is not set.) If options [" badge "] exists , then parse it using baseURL , and if that does not return failure, set notification ’s badge URL to the return value. (Otherwise badge URL is not set.) If options [" vibrate "] exists , then validate and normalize it and set notification ’s vibration pattern to the return value. If options [" timestamp "] exists , then set notification ’s timestamp to the value. Otherwise, set notification ’s timestamp to the number of milliseconds from the Unix epoch to settings ’s current wall time , rounded to the nearest integer. Set notification ’s renotify preference to options [" renotify "]. Set notification ’s silent preference to options [" silent "]....