Web URL Notifications

This document defines APIs for alerting the user outside of a web page by displaying notifications with Web content provided on a URL. For a broader overview of notifications, including definitions and use cases, see Notifications Overview.

This document extends and depends on Notifications specification providing text/icon notifications [NOTIFICATIONS].

Status of this Document

This document is an Editor's Draft and is not suitable for purposes other than reviewing the specification being developed.

1. Definitions

simple notification: A notification which consists only of an icon and one or two lines of text.
web notification: A notification which consists of Web platform content, such as HTML or SVG.

2. Introduction

This section is not normative.

This specification extends the capabilities of Notifications defined in [NOTIFICATIONS] by allowing the notification to contain content supplied by a URL, such as HTML or SVG, allowing for interactive and dynamic notifications.

2.1. Permissions

Throughout this document, "notification permission is allowed" shall mean that the permission level of the 'notifications' feature for the current security origin is USER_ALLOWED or DEFAULT_ALLOWED in the meaning of [PERMISSIONS], and "notification permission is denied" shall mean that the current permission level has some other value.

3. Web notifications

In addition to displaying simple notifications, some user agents may use a notification platform that is capable of displaying notifications which contain web content, such as HTML or SVG. This supplemental interface exposes that ability.

supplemental NotificationCenter interface

[Supplemental] interface NotificationCenter {
  Notification createWebNotification(in DOMString url)
                                        raises(Exception);
};

Methods

createWebNotification

Parameters

url of type DOMString: The URL of a resource which contains content to be shown as the notification. The URL parameter must be resolved relative to the base URL of the document or worker script.

Return Value

A notification object representing the new notification.

Exceptions

Exception

If notification permissions are denied, this method will throw a SECURITY_ERR.

If the URL is invalid or cannot be resolved, a SYNTAX_ERR is raised.

3.1. Unsupported content types

This section is not normative.

User agents which use an existing notification platform and support only simple notifications may not support all types of web content. These user agents may attempt to extract simple notification content from web content such as the <title> tag of HTML content as the notification.

4. Interacting with notifications

4.1. Using window.opener

A web notification is a separate window, and script running within that context should be able to communicate to other windows, subject to the rules which generally apply to cross-domain communication.

Within a web notification, the window.opener property should be set to the window which created the notification. If the notification was created by a worker script, window.opener should be null.

The following example uses window.opener to return to the application which created the notification in response to a click, and then close the notification.

Example:

notification.html
---
New email arrived! 
<a href="#" onclick="window.opener.focus(); window.close();">
  Go to Inbox
</a>

script.js
---
var notification = window.notifications.createWebNotification("notification.html");
notification.show();

5. Queueing and displaying notifications

These algorithm supersede the corresponding algorithms in [NOTIFICATIONS], providing for the fetching of the content URL.

5.1. Displaying notifications

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

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

5.2. 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.

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

6. References

HTML5: HTML5: A vocabulary and associated APIs for HTML and XHTML,
NOTIFICATIONS: Notifications,
PERMISSIONS: Feature Permissions,