html5-desktop-notifications

(draft)

HTML5 Desktop Notifications

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

Content

1. Introduction
2. Browsers Support
3. Demo
4. Usage
5. API Documentation
6. Screenshots
7. Limitations

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>

	Windows	MacOS	Linux	ChromeOS	Android
IE1	✓	-	-	-	-

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

² Support for Safari 6

³ 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:

• PERMISSION_DEFAULT: "default" -- "default" string value
• PERMISSION_GRANTED: "granted" -- "granted" string value
• PERMISSION_DENIED: "denied" -- "denied" string value
• isSupported: true/false -- indicates browser's notifications support.
• permissionLevel() -- check for permissions to display notifications. Returns one of the following:
  • PERMISSION_DEFAULT -- The user has not yet specified whether they approve of notifications being sent from this domain. (Chrome, Safari & Firefox)
  • PERMISSION_GRANTED
    • Chrome, Safari & Firefox: The user has given permission for notifications to be sent from this domain
    • IE9+: Page is running on pinned site window.
    • Firefox Mobile: HTML5 notifications are supported
  • PERMISSION_DENIED -- The user has denied permission for notifications to be sent from this domain. (Chrome, Safari & Firefox)
• requestPermission() -- If the permission level is default, it is likely that the user hasn’t yet been prompted to grant access to notifications from your domain. Prompt users to grand permissions by calling the requestPermission() method. This method accepts one parameter, a callback function, which executes when the user grants or denies permission. (Applies for Chrome, Safari and Firefox only. To grand permissions for IE, the site window should be pinned. As window cannot be pinned with javascript, this method gracefully do nothing for IE.)
• createNotification() -- Create a notification by calling createNotification() method: notify.createNotification(String title [, Object options]).
  • title / String / (required) -- notification's title
  • Available keys that can be included in the options object are the following:
    • body / String / -- The notification’s subtitle. For IE it provides an accessible description of the information conveyed by the icon overlay. Choose text that can be read by screen readers.
    • icon / String/Object / (required) -- The icon that will be set as a custom overlay for IE and notification displayed from Chrome running on Windows. Note that icon by default is not required for Chrome, Safari & Firefox, but is required for IE. In order to unify the implementations, the icon should be always provided in order to display notifications for all supported browsers. icon param could be String with icon's location, but it could be also an Object with the following properties: {"x16": Icon for IE only. The icon should be 16x16px *.ico format, "x32": Icon for all other browsers(Chrome on Windows, Firefox). The icon's size should be 32x32px, supported formats: jpg/png/ico}. Once again - Safari and Chrome on MacOS does not allow icon to be set. For Firefox Mobile, the icon is always Firefox icon.
    • tag -- The notification’s unique identifier. This prevents duplicate entries from appearing in Notification Center if the user has multiple instances of your website open at once. (Apply for Chrome & Safari only)
  Returns an object with the following methods:
  • close() -- call to close the notification.

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

• Notifications could not be "styled" - Only icon(for some browsers and OS), title and body could be changed.
• IE9+ supports *.ico file types only for an overlay icon. No notification title or notification description. Recommended icon size is 16px x 16px.
• For Chrome & Safari running on MacOS the icon of the notification could not be changed - it is always Chrome or Safari icon.

top