emp2web / notify.js

A handy wrapper for the Web Notifications API

Notify.js

A handy wrapper for using the Web Notifications API. Notify.js aims to simplify requesting user permission and associated Web Notification API events, as well as providing a few extra callbacks and convenience methods.

Online demo: https://alexgibson.github.io/notify.js/

Installation

npm install notifyjs

Note: when installed via npm the Notify.js source file is located at ./dist/notify.js.

Build

Notify.js is written in ES6 and transpiled to ES5 & UMD format using Babel and Rollup.

Install dependencies:

npm install

Then build from source:

npm run build

Usage

To initialize a web notification create a new Notify instance, passing the message title as well as any other options you wish to use.

var myNotification = new Notify('Yo dawg!', {
	body: 'This is an awesome notification',
	notifyShow: onNotifyShow
});

function onNotifyShow() {
	console.log('notification was shown!');
}

Then show the notification.

myNotification.show();

It's a good idea to make sure that you have permissions to send notifications first.

if (!Notify.needsPermission) {
    doNotification();
} else if (Notify.isSupported()) {
    Notify.requestPermission(onPermissionGranted, onPermissionDenied);
}

function onPermissionGranted() {
	console.log('Permission has been granted by the user');
	doNotification();
}

function onPermissionDenied() {
	console.warn('Permission has been denied by the user');
}

Required parameters

• title (string) - notification title

Optional parameters

All options supported in the Notifications API specification, in addition to:

• timeout: (integer) - number of seconds to close the notification automatically
• closeOnClick: (boolean) - close the notification when clicked. Useful in chrome where the notification remains open until the timeout or the x is clicked.
• notifyShow: (function) - callback when notification is shown
• notifyClose: (function) - callback when notification is closed
• notifyClick: (function) - callback when notification is clicked
• notifyError: (function) - callback when notification throws an error

Static methods and properties

• Notify.requestPermission(onPermissionGrantedCallback, onPermissionDeniedCallback) - requests permission from the user if needed and handles permission callbacks.
• Notify.isSupported - Function to test for Web Notifications API browser support
• Notify.needsPermission - Boolean property to check if permission is needed for the user to receive notifications.

Instance methods

• Notify.show - Function to display the Notify instance
• Notify.close - Function to close the Notify instance

Test

In the project root, to perform a single pass of the tests using Firefox run:

npm run test

This will also automatically build from source before running the tests.

Demo example

An easy way to run the provided demo file is to use python SimpleHTTPServer and then navigate to the /example directory:

python -m SimpleHTTPServer

Browser support

http://caniuse.com/#search=notifications