Notifications API

References

• Notifications API

Notes

The Notifications API allows web pages to control the display of system notifications to the end user. These are outside the top-level browsing context viewport, so therefore can be displayed even when the user has switched tabs or moved to a different app. The API is designed to be compatible with existing notification systems, across different platforms.

Showing a system notification generally involves two things:

1. The user needs to grant the current origin permission to display system notifications, which is generally done when the app or site initializes, using the Notification.requestPermission() method. This method should only be called when handling a user gesture.

btn.addEventListener("click", () => {
  let promise = Notification.requestPermission();
  // wait for permission
});

The choice of accepting notifications will generally persist for the current session.

2. Next, a notification is created using the Notification() constructor. This must be passed a title argument, and can optionally be passed as an options object to specify options, such as text direction, body text, icon to display, notification sound to play, and more.

• • The Notification API spec specifies a number of additions to the ServiceWorker API, to allow service workers to fire notifications.

The Notifications API lets a web page or app send notifications that are displayed outside the page at the system level; this lets web apps send information to a user even if the application is idle or in the background.

You should only request consent to display notifications in response to a user gesture.

You can check to see if you already have permission by checking the value of the Notification.permission read only property. It can have one of three possible values:

• default
• • The user hasn't asked for permission yet, so notifications won't be displayed.
• granted
• • The user has granted permission to display notifications, after having been asked previously.
• denied
• • The user has explicitly denied permission to show notifications.

The Notfication.requestPermission() method can be used to request permission to send notifications from the user.

Creating a notification is easy; just use the Notification constructor. This constructor expects a title to display within the notification and some options to enhance the notification such as an icon or a text body.

Use close() to remove a notification that is no longer relevant to the user (e.g., the user already read the notification on the webpage, in the case of a messaging app, or the following song is already playing in a music app to notifies upon song changes).

There are 4 events that are triggered on the Notfication instance:

1. click
2. 1. Triggered when the user clicks on the notification.
2. close
3. 1. Triggered once the notification is closed.
3. error
4. 1. Triggered if something goes wrong with the notification; this is usually because the notification couldn't be displayed for some reason.
4. show
5. 1. When the notification is showed to the user

To avoid spamming the user with too many notifications, it's possible to modify the pending notifications queue, replacing single or multiple notifications with a new one. To do this, it's possible to add a tag to any new notification. If a notification already has the same tag and has bot been displayed yet, the notification replaces that previous notification.

Interfaces

Notification

• Noification.permission: A string representing the current permission to display notifications.
• Notification.maxActions: The maximum number of actions supported by the device and the User Agent.
• Notification.actions: The actions array of the notification as specified in the constructor's option parameter
• Notification.badge: A string containing the URL of an image to represent the notification when there is not enough space to display the notification itself such as, the Android Notification bar.
• Notification.body: The body string of the notification as specified in the constructor's options parameter.
• Notification.data: Returns a structured clone of the notification's data.
• Notification.icon: The URL of the image used as an icon of the notification as specified in the constructor's opions parameter.
• Notification.image: The URL of an image to be displayed as part of the notification, as specified in the constructor's options parameter.
• Notification.renotify: Specifies whether the user should be notified after a new notification replaces the old one.
• Notification.requireInteracton: A boolean value indicating that a notification should remain active until the user clicks or dismisses it, rather than closing automatically.
• Notification.silent: Specifies whether the notification should be silent
• Notification.tag: The ID of the notification as specified in the constructor's options parameter
• Notification.timestamp: Specifies a time at which a notification is created or applicable.
• Notification.title: The title of the notification as specified in the first parameter of the constructor
• Notification.vibrate: Specifies a vibration pattern for devices with vibration hardware to admit.

NotificationEvent

This interface represents a notification event dispatched on the ServiceWorkerGlobalScope of a ServiceWorker.

Methods

ServiceWorkerRegistration.showNotification()

This method creates a notification on an active service worker.

Parameters:

• title
• • Defines a title for the notification, which is shown at the top of the notification window.
• options
• • This contains all the options that you would send to the Notification() interface

ServiceWorkerRegistration.getNotifications()

The getNotifications() method returns a list of the notifications in the order that they were created from the current origin via the current service worker registration. Origins can have many active but differently-scoped service worker registrations. Notifications created by one service worker on the same origin will not be available to other active service workers on that same origin.