html5-desktop-notifications v1.0.0

(draft)

HTML5 Desktop Notifications

A small library that unifies the HTML5 Notifications APIs accross different browsers including IE9 & IE10.

Content

Introduction

HTML5 Notifications API allows you to display notifications to the user for given events. There is a draft spec, but it is not currently in any standard.

Google Chrome introduces notifications in version 5 (http://caniuse.com/#feat=notifications) - supporting the old proposed APIs version. Starting from version 22, Chrome supports the lastest proposed draft version of the Notifications API, but some of the methods are not implemented or breaking the page - see below for details.

Safari 6 implements most of the APIs in proposed Notifications draft. See Safari documentation.

IE9 introduced pinned sites, a convenient way for users to access your website directly by clicking an icon on the taskbar. Pinned sites are easy to implement, too, requiring very little code. For more information about creating pinned sites, see Pinned Sites Developer Documentation. Pinned site can display icon overlays on the taskbar or highlights the taskbar button to notify user of activity. To view an icon overlay, the taskbar buttons must be in their default large icon mode. Small taskbar icons do not support icon overlays. In addition, icon overlays are visible only while the Pinned site window is running. The icon is removed from the taskbar button when the Pinned site window is closed. See Working with custom icon overlays in pinned sites.

top

Browsers Support

	<!-- Chrome -->
	<tr>
		<td>Chrome</td>
		<td>✓</td>
		<td>✓</td>
		<td>✓</td>
		<td>✓</td>
        		<td>-</td>
	</tr><!-- Chrome -->

	<!-- Safari -->
	<tr>
		<td>Safari<sup>2</sup></td>
		<td>-</td>
		<td>✓</td>
		<td>-</td>
		<td>-</td>
        		<td>-</td>
	</tr><!-- Safari -->

	<!-- Firefox -->
	<tr>
		<td>Firefox<sup>3</sup></td>
		<td>✓</td>
		<td>✓</td>
		<td>✓</td>
		<td>-</td>
			<td>✓</td>
	</tr><!-- Firefox-->
</tbody>

1 Support for IE9+ running on Windows7 or later. In addition, notifications are visible only while the Pinned site window is running. The icon is removed from the taskbar button when the Pinned site window is closed. The taskbar buttons must be in their default large icon mode, small taskbar icons do not support icon overlays.

2 Support for Safari 6

3 Support for Firefox less than version 23 only when html5-notifications plugin is installed. Recommended version is 1.2.0.1 - see the following issue: http://code.google.com/p/ff-html5notifications/issues/detail?id=58 . Firefox 23 introduced native support for html5 desktop Notifications. For MacOS Growl app is required. Firefox Mobile for Android does NOT require any plugins installed.

top

Demo

Demo page

Usage

Step 1

First, ensure that notifications are allowed to be displayed by calling notify.permissionLevel().

Step 2

If returned value is equal to notify.PERMISSION_DEFAULT, then call notify.requestPermission() to ask user to grand permissions for displaying notifications. If returned value is equal to notify.PERMISSION_GRANTED, permissions are granted and can display notifications. If returned value is equal to notify.PERMISSION_DENIED - notifications are denied. Instead, user should allow notifications or remove current domain from the list of notifications setting into browser's setting page.

Step 3

Set global configurations:

• pageVisibility - to displaying notification when page is not visible - for browsers that support pageVisibility only. Defaults to false;
• autoClose - an interval of time in ms for displaying the notification and then it is closed automatically. Defaults to 0 (notifications will not be closed automatically)

notify.config({pageVisibility: false, autoClose: 500});

Create notifications by calling notify.createNotification(). Notification title, notification body and notification icon are required parameters. Calling notify.createNotification() returns am notification object that has one method - close() - used to close manually the notificaiton.

top

API Documentation

The notify global object provides a single global namespace within which all code resides. It contains the following properties and methods:

top

Screenshots

IE9 running on Windows7:

Chrome running on Windows7:

Chrome running on MacOS:

Safari 6 running on MacOS:

Firefox with html5notifications plugin installed and running on Windows7:

Firefox Mobile running on Android:

top

Limitations

top