notifications.spec.whatwg.orgNotifications API Standard

Notifications API Living Standard — Last Updated 29 September 2020 Participate: GitHub whatwg/notifications ( new issue , open issues ) IRC: #whatwg on Freenode 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 Permission model 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, HTML, IDL, Service Workers, URL, and Vibration API Standards. [DOM] [FETCH] [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 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 show steps have run with a new notification that has the same tag as an existing notification. 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 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 can have these associated graphics: an image URL , icon URL , and badge URL ; and their corresponding image resource , icon resource , and badge resource . ⚠ MDN Notification/image In only one current engine. Firefox None Safari ? Chrome 53+ Opera 40+ Edge 79+ Edge (Legacy) 18 IE None Firefox for Android None iOS Safari None Chrome for Android 53+ Android WebView None Samsung Internet 6.0+ Opera Mobile 41+ 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 can have a vibration pattern . 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 title , options , and optionally a serviceWorkerRegistration , run these steps: Let notification be a new notification . If a serviceWorkerRegistration was provided, set notification ’s service worker registration to serviceWorkerRegistration . 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 . If options ’s silent is true and options ’s vibrate is present, throw a TypeError exception. If options ’s renotify is true and options ’s tag is the empty string, throw a TypeError exception. Set notification ’s data to StructuredSerializeForStorage ( options ’s data ). Rethrow any exceptions. Set notification ’s title to title . Set notification ’s direction to options ’s dir . Set notification ’s language to options ’s lang . Set notification ’s origin to the entry settings object ’s origin . Set notification ’s body to options ’s body . Set notification ’s tag to options ’s tag . Let baseURL be the API base URL specified by the entry settings object . Or incumbent? If options ’s image is present, 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 ’s icon is present, 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 ’s badge is present, 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 ’s vibrate is present, validate and normalize it and set notification ’s vibration pattern to the return value. (Otherwise vibration pattern is not set.) 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 tim...