Web Notifications

3.1. Security

Notifications should only be presented when the user has indicated they are desired; without this they could create a negative experience for the user.

5.1. Directionality

The dir attribute of the Notification interface specifies the directionality of the notification. It is an enumerated attribute with the following keywords:

• The ltr keyword, which indicates that the contents of the notification are left-to-right text.
• The rtl keyword, which indicates that the contents of the notification are right-to-left text.
• The auto keyword, which indicates that the directionality of the notification is to be determined programmatically, as described below.

In environments where the global object is represented by the Window object, if the notification's dir attribute is auto, the directionality must be the same as the Document object associated with the global Window object. In other environments, if the notification's dir attribute is auto, the directionality should be ltr.

The user agent should reflect the directionality of the notification in the underlying notification platform if that platform supports it.

5.2. Event handler attributes

The following are event handler attributes (and their corresponding event handler event types, as defined by [HTML5]) that must be supported as DOM attributes by the Notification object.

5.3. Constructors

  Notification Notification(in DOMString iconUrl, in DOMString title, in DOMString body);

When the Notification() constructor is invoked, the user agent must return a new Notification object.

6.1. Queueing notifications

If the device allows notifications to displayed immediately without limitations on the number of concurrent notifications, it must display a notification immediately whenever show is called and notification permission is allowed.

If the device does have limitations on the number of concurrent notifications, when show is called and notification permission is allowed, the user agent must either immediately call to a notifications platform which supports queueing, or use the following algorithm.

The user agent must keep a queue of pending notifications and a list of active notifications.

1. Get the replacement id of the notification to be shown, and let it be replaceId.
2. If replaceId is defined, examine all the notifications in the list of active notifications. If any notification in the list has the same source origin and has replacement id equal to replaceId, do the following steps and then terminate this algorithm. Let existing be the notification in the list which matches.
   1. Replace existing with the new notification using the replacing a notification algorithm.
   2. If the replacement returned error information, stop.
   3. Remove existing from the list of active notifications.
   4. Add the new notification to the list of active notifications.
3. Add the notification to the queue of pending notifications.
4. Wait until there is available space on the device.
5. Display the first notification in the queue of pending notifications using the displaying a notification algorithm.

When the available display space changes on the device such that a new notification may be displayed, for example due to a previous notification being dismissed, the user agent should display the first notification in the queue using the procedure described above.

6.2. Displaying notifications

When a user agent is to display a notification, the user agent should perform the following steps:

1. Fetch the resource given by iconUrl using the algorithm defined in [HTML5].
2. If the fetch algorithm returns error information, fire the error event on the notification object and stop executing this algorithm.
3. Fire the show event on the notification object.
4. Show the notification on the device, such as by calling the appropriate notification platform.

6.3. Replacing a notification

When a user agent is to replace a notification, the user agent should perform the following steps. Let old be the notification to be replaced by new.

1. Fetch the icon resource in new using the algorithm defined in [HTML5].
2. If the fetch algorithm returns error information, fire the error event on the new notification object and stop executing this algorithm, returning the error information. The old notification is not affected.
3. Fire the close event on the old notification object.
4. Fire the show event on the new notification object.
5. If the underlying notification platform supports replacement, replace old with new on the device.
6. If the underlying notification platform does not support replacment, remove old from the device and show new on the device.

7.1. Using events

Notification objects dispatch events during their lifecycle, which authors can use to generate desired behaviors.

The show event occurs when the notification is shown to the user -- this may be at some time after the show() method is called in the case of limited display space and a queue.

In the following example, this event is used to guarantee that regardless of when the notification is shown, it is displayed for only 15 seconds.

var notification = new Notification("mail.png", "New Email Received");
notification.onshow = function() { setTimeout(notification.cancel(), 15000); }
notification.show();

The close events occurs when the notification is dismissed by the user. Authors may use this event to perform actions when notifications are acknowledged.

In the following example, when a meeting reminder notification is acknowledged, the application suppresses other forms of reminders.

var notification = new Notification("calendar.png", "Meeting about to begin", "Room 101");
notification.onclose = function() { cancelReminders(event); }
notification.show();