Actions are the mechanism through which notifications send messages back to the application that created them. The
service defines a number of ways in which actions can be raised (a notification being interacted with by the user,
being closed, expiring, etc.), and it is up to each application to decide if it wishes to be informed when each of
these triggers occur.
For an action to be raised when one of these triggers occurs, the application must specify an
action result for each trigger it is interested in. The application should then
listen for when these actions are raised by listening for the notification-action
event.
This event is fired once each time an action is raised, and will contain the
action result the application specified for that trigger. The application may then
use the action result to determine which trigger occurred and respond appropriately.
If an action result is not specified for a particular trigger, or it is set to
null, the application will not receive a corresponding notification-action when
that trigger occurs.
Unlike other event types, notification-action events will be buffered by the
service until the application has added a listener for this event type, at which point it will receive all buffered
notification-action events. The service will also attempt to restart the
application if it is not running when the event is fired.
For an overview of actions, consider the sample notification below:
// Create a notification with two buttons create({ // Basic info title:'Reminder', body:'Event "Weekly Meeting" is starting soon...',
// We'll use the 'customData' field to store metadata about the event customData: {eventId:'12345'},
// We want the user clicking the notification to open the associated event, so register an 'onSelect' action onSelect: {task:'view-calendar-event', target:'popup'},
buttons: [ // A button that will schedule another reminder for 5 minutes from now. Since the application will be // responsible for snoozing the event, it will need to know about the user clicking this button. By setting // a NotificationActionResult for 'onClick', the service will raise a "notification-action" event when this // button is clicked, and will pass the value of 'onClick' as the 'result' field within the event { title:'Snooze for 5 minutes', iconUrl:'https://www.example.com/timer.png', onClick: { task:'schedule-reminder', intervalMs:5 * 60 * 1000 } },
// A button that closes the notification and doesn't prompt the user about this event again. Since the // application doesn't need to do anything when the user clicks this button, we leave 'onClick' undefined // rather than specifying a NotificationActionResult. This means that no action will be raised when the // button is clicked, and hence no "notification-action" event will be fired { title:'Dismiss', iconUrl:'https://www.example.com/cancel.png' } ] });
// Create a listener that will be called for each action // Note: This handler will be used for ALL actions, from ALL notifications that are created by this application. addEventListener('notification-action', (event: NotificationActionEvent) => { const {result, notification} = event;
if (result['task'] === 'view-calendar-event') { // Open a window with full details of the associated event openEventDetails(notification.customData.eventId, result['target']); } elseif (result['task'] === 'schedule-reminder') { // Schedule a new notification scheduleReminder(notification.customData.eventId, Date.now() + result['intervalMs']); } // Etc... });
The example above uses customData to store details about the notification subject (in this case, a calendar
event), and onClick actions to inform the application about how it should respond when the user interacts with the
notification. This is our intended usage and recommended best-practice, but the service doesn't require applications
to follow this convention - application developers are free to decide how to manage notification state.
Within the notification-action handler, the application must be able to understand which notification is being
handled, and how to decide what it should do next. The example above uses an application-defined action field to
determine the correct action, but the notification's id, customData and other fields are also useful
selectors.
Actions are the mechanism through which notifications send messages back to the application that created them. The service defines a number of ways in which actions can be raised (a notification being interacted with by the user, being closed, expiring, etc.), and it is up to each application to decide if it wishes to be informed when each of these triggers occur.
For an action to be raised when one of these triggers occurs, the application must specify an action result for each trigger it is interested in. The application should then listen for when these actions are raised by listening for the
notification-action
event.This event is fired once each time an action is raised, and will contain the action result the application specified for that trigger. The application may then use the action result to determine which trigger occurred and respond appropriately.
If an action result is not specified for a particular trigger, or it is set to
null
, the application will not receive a correspondingnotification-action
when that trigger occurs.Unlike other event types,
notification-action
events will be buffered by the service until the application has added a listener for this event type, at which point it will receive all bufferednotification-action
events. The service will also attempt to restart the application if it is not running when the event is fired.For an overview of actions, consider the sample notification below:
The example above uses
customData
to store details about the notification subject (in this case, a calendar event), andonClick
actions to inform the application about how it should respond when the user interacts with the notification. This is our intended usage and recommended best-practice, but the service doesn't require applications to follow this convention - application developers are free to decide how to manage notification state.Within the
notification-action
handler, the application must be able to understand which notification is being handled, and how to decide what it should do next. The example above uses an application-definedaction
field to determine the correct action, but the notification'sid
,customData
and other fields are also useful selectors.