 Thomas Steiner [GitHub](https://github.com/tomayac) [LinkedIn](https://www.linkedin.com/in/thomassteinerlinkedin) [Mastodon](https://toot.cafe/@tomayac) [Bluesky](https://bsky.app/profile/tomayac.com) [Homepage](https://blog.tomayac.com/)
Published: October 24, 2019
> [!WARNING]
> **Warning** : The development of Notification Triggers API, part of Google's
> [capabilities project](https://developer.chrome.com/blog/capabilities.md.txt), has ended.
> It wasn't clear that we could provide consistent and reliable experiences
> across platforms
> .
>
> To create a good experience, there needs to be a mechanism for being able
> to prune stale or invalidated scheduled notifications, for example, canceled calendar events,
> without relying on the tab being open. We heard feedback that the cadence at which
> ["Periodic Background Sync](https://developer.chrome.com/docs/capabilities/periodic-background-sync.md.txt) can be used isn't sufficient, and as this is required to show a notification, the Push API isn't a good
> solution either.
## What are Notification Triggers?
Web developers can display notifications using the
[Web Notifications API](https://www.w3.org/TR/notifications/). This feature is often used with the
[Push API](https://w3c.github.io/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.
> [!NOTE]
> **Note:** For now, Chrome only supports *time-based triggers*. Additional triggers, such as location-based triggers, may be added in the future based on developer demand.
### 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 livestream 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
| Step | Status |
|---|---|
| 1. Create explainer | [Complete](https://github.com/beverloo/notification-triggers/blob/master/README.md) |
| 2. Create initial draft of specification | Not started |
| 3. **Gather feedback and iterate on design.** | **[In progress](https://developer.chrome.com/docs/web-platform/notification-triggers.md.txt#feedback)** |
| 4. Origin trial | Complete |
| 5. Launch | Not started |
## Use notification triggers
To experiment with the Notification Triggers API locally, without an origin trial token, enable the
`#enable-experimental-web-platform-features` flag in `about://flags`.
> [!NOTE]
> **Note:** Previous origin trials gave developers an opportunity to try this API.
### Feature detection
You can find out if the browser supports Notification Triggers by checking for the existence of the
`showTrigger` property:
```javascript
if ('showTrigger' in Notification.prototype) {
/* Notification Triggers supported */
}
```
### Schedule 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 `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),
});
};
> [!NOTE]
> **Note:** On desktop, notification triggers fire only if Chrome is running. On Android, they fire regardless.
### Cancel 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());
};
### Debug
You can use the [Chrome DevTools Notifications panel](https://developer.chrome.com/blog/new-in-devtools-77.md.txt#backgroundservices) 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.
 A scheduled notification.  A displayed notification.
### Demo
You could see Notification Triggers in action in a demo, which allowed you to schedule
notifications, list scheduled notifications, and cancel them.
## 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](https://chromium.googlesource.com/chromium/src/+/lkgr/docs/security/permissions-for-powerful-web-platform-features.md), 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.
As of the article date, there's 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`](https://developer.android.com/reference/android/app/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](https://github.com/beverloo/notification-triggers/issues), 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](https://new.crbug.com/). Be sure to include as much detail as you can,
instructions for reproducing, and set Components to `UI>Notifications`.
### 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](https://twitter.com/chromiumdev) using the hashtag
[`#NotificationTriggers`](https://twitter.com/search?q=%23NotificationTriggers&src=typed_query&f=live)
and let us know where and how you're using it.
## Helpful Links
- [Public explainer](https://github.com/beverloo/notification-triggers/blob/master/README.md)
- [Tracking bug](https://bugs.chromium.org/p/chromium/issues/detail?id=891339)
- [ChromeStatus.com entry](https://www.chromestatus.com/feature/5133150283890688)
- Blink Component: `UI>Notifications`
## Acknowledgements
Notification Triggers was implemented by [Richard Knoll](https://uk.linkedin.com/in/richardknoll)
and the explainer written by [Peter Beverloo](https://twitter.com/beverloo?lang=en), with
contributions from Richard. The following people reviewed the article:
[Joe Medley](https://twitter.com/medleyjp), [Pete LePage](https://twitter.com/petele), as well as
Richard and Peter.