Notification Triggers

# What are Notification Triggers?

Web developers can display notifications using the Web Notifications API. This feature is often used with the Push API to inform the user of time-sensitive information, such as breaking news events or received messages. Notifications are shown by running JavaScript on the user's device.

The problem with the Push API is that it's not reliable for triggering notifications which must be shown when a particular condition, like time or location, is met. An example of a time-based condition is a calendar notification that reminds you of an important meeting with your boss at 2 PM. An example of a location-based condition is a notification that reminds you to buy milk when you enter the vicinity of your grocery store. Network connectivity or battery-preserving features like doze mode can delay the delivery of push based notifications.

Notification triggers solve this problem by letting you schedule notifications with their triggering condition in advance, so that the operating system will deliver the notification at the right time even if there is no network connectivity or the device is in battery saver mode.

# Use cases

Calendar applications can use time-based notification triggers to remind a user of upcoming meetings. The default notification scheme for a calendar app could be to show a first heads-up notification one hour before a meeting and then another more urgent notification five minutes before.

A TV network might remind users that their favorite TV show is about to start or a conference live stream is about to begin.

Time zone conversion sites can use time-based notification triggers to let their users schedule alarms for telephone conferences or video calls.

# Current status

# How to use notification triggers

# Enabling via about://flags

To experiment with the Notification Triggers API locally, without an origin trial token, enable the #enable-experimental-web-platform-features flag in about://flags.

# Feature detection

You can find out if the browser supports Notification Triggers by checking for the existence of the showTrigger property:

if ('showTrigger' in Notification.prototype) {
  /* Notification Triggers supported */
}

# Scheduling a notification

Scheduling a notification is similar to showing a regular push notification, except that you need to pass a showTrigger condition property with a TimestampTrigger object as the value to the notification's options object.

const createScheduledNotification = async (tag, title, timestamp) => {
  const registration = await navigator.serviceWorker.getRegistration();
  registration.showNotification(title, {
    tag: tag,
    body: 'This notification was scheduled 30 seconds ago',
    showTrigger: new TimestampTrigger(timestamp + 30 * 1000),
  });
};

# Canceling a scheduled notification

To cancel scheduled notifications, first request a list of all notifications that match a certain tag through ServiceWorkerRegistration.getNotifications(). Note that you need to pass the includeTriggered flag for scheduled notifications to be included in the list:

const cancelScheduledNotification = async (tag) => {
  const registration = await navigator.serviceWorker.getRegistration();
  const notifications = await registration.getNotifications({
    tag: tag,
    includeTriggered: true,
  });
  notifications.forEach((notification) => notification.close());
};

# Debugging

You can use the Chrome DevTools Notifications panel to debug notifications. To start debugging, press Start recording events or Control+E (Command+E on Mac). Chrome DevTools records all notification events, including scheduled, displayed, and closed notifications, for three days, even when DevTools is closed.

# Demo

You can see Notification Triggers in action in the demo, which allows you to schedule notifications, list scheduled notifications, and cancel them. The source code is available on Glitch.

# Security and permissions

The Chrome team has designed and implemented the Notification Triggers API using the core principles defined in Controlling Access to Powerful Web Platform Features, including user control, transparency, and ergonomics. Because this API requires service workers, it also requires a secure context. Using the API requires the same permission as regular push notifications.

# User control

This API is only available in the context of a ServiceWorkerRegistration. This implies that all required data is stored in the same context and is automatically deleted when the service worker is deleted or the user deletes all site data for the origin. Blocking cookies also prevents service workers from being installed in Chrome, and therefore this API from being used. Notifications can always be disabled by the user for the site in site settings.

# Transparency

Unlike the Push API, this API does not depend on the network, which implies scheduled notifications need all required data beforehand, including image resources referenced by the badge, icon and image attributes. This means showing a scheduled notification is not observable by the developer and doesn't involve waking up the service worker until the user interacts with the notification. Consequently, there is currently no known way the developer could obtain information about the user through potentially privacy-invading approaches like IP address geolocation lookup. This design also allows the feature to optionally tap into scheduling mechanisms provided by the operating system like Android's AlarmManager, which helps preserve battery.

# Feedback

The Chrome team wants to hear about your experiences with Notification Triggers.

# Tell us about the API design

Is there something about the API that doesn't work like you expected? Or are there missing methods or properties that you need to implement your idea? Have a question or comment on the security model? File a spec issue on the Notification Triggers GitHub repo, or add your thoughts to an existing issue.

# Problem with the implementation?

Did you find a bug with Chrome's implementation? Or is the implementation different from the spec? File a bug at new.crbug.com. Be sure to include as much detail as you can, simple instructions for reproducing, and set Components to UI>Notifications. Glitch works great for sharing quick and easy bug reproductions.

# Planning to use the API?

Planning to use Notification Triggers on your site? Your public support helps us to prioritize features and shows other browser vendors how critical it is to support them. Send a tweet to @ChromiumDev using the hashtag #NotificationTriggers and let us know where and how you're using it.

# Helpful Links

• Public explainer
• Notification Triggers demo | Notification Triggers demo source
• Tracking bug
• ChromeStatus.com entry
• Blink Component: UI>Notifications

# Acknowledgements

Notification Triggers was implemented by Richard Knoll and the explainer written by Peter Beverloo, with contributions from Richard. The following people have reviewed the article: Joe Medley, Pete LePage, as well as Richard and Peter. Hero image by Lukas Blazek on Unsplash.