Depreciated version of the Webkit Notification API

Orde Saunders' avatarUpdated: Published: by Orde Saunders

Chromium and, by extension, Chrome support a Notification API that allows messages to be shown by the browser at the operating system level. These can be used to provide visible notifications even when the browser that initiated them is not visible.

This article features functional inline JavaScript examples of how to use the API.

Feature detect support

As the API is a non-standard implementation in one browser, support for the notification API should be feature detected before use: 

var notification_support = typeof window.webkitNotifications !== 'undefined';

Permission

Before showing a notification a check should be made to see if the API has permission to show notifications and, if it hasn't been granted or refused, it must be requested.

Permission status

The permission status is accessed as follows: 

window.webkitNotifications.checkPermission()

The permission can have one of three values:

0
Permission has been granted.
1
Permission has not been granted or refused.
2
Permission has been refused.

By default in Chrome permissions are controlled on a site-by-site basis and can be changed in: Settings » Advanced settings » Privacy settings » Content settings » Notifications.

Requesting permission

Permission is requested by calling window.webkitNotifications.requestPermission(). This must be bound to an interactive event handler - frequently click. The call to request permission is asynchronous and will activate the browser chrome permission dialogue.

If permission has not been granted then most methods with throw security exceptions when called.

Create a notification

When creating a notification there are two options, HTML and plain text.

Text

A text notification takes three parameters:

  1. iconUrl{String} Location of an icon to show in the notification. This will help users identify the site that issued the notification as it may be in a background tab or minimised browser.
  2. title{String} Title of the notification.
  3. body{String} Main body of the the notification.
window.webkitNotifications.createNotification(iconUrl, title, body);

HTML

Between initially drafting this article and publishing it, HTML notifications were removed from Cromium. Documented here is the behaviour of the HTML notifications immediately before they were removed.

An HTML notification took a URL as a parameter and the content of this resource was read into the notification.

window.webkitNotifications.createHTMLNotification(URL);

The notification context was limited in size on screen but did allow execution of JavaScript.

If you try to use this method now you will get the following error: Uncaught TypeError: Object #<NotificationCenter> has no method 'createHTMLNotification'

Show notification

Once the notification has been created it can be shown.

notification.show();

Cancel notification

Once a notification has been shown it can be cancelled.

notification.cancel();

Once a notification has been cancelled it must be recreated before attempting to show again.

Notification events

The notification has four event handlers that can have functions bound to them.

  • ondisplay - Triggered when the notification is shown.
  • onerror - Triggered when there is an error in the notification.
  • onclose - Triggered when the notification is closed.
  • onclick - Triggered when the notification receives a click event.
notification.onclick = function() {
  // Handle action from notification being clicked.
}

Modification

It's not possible to modify an notification once it has been shown but this behaviour can be somewhat emulated by closing the notification and re-creating and immediately showing a new notification. 

notification.cancel();
notification = window.webkitNotifications.createNotification(iconUrl, title, body);
notification.show();

Further reading