Notifications

Availability

2.0+

You can use the Notifications object to display a web notification to the user. These web notifications appear in the Notifications list on the status bar of the home screen. Unlike alerts or pop up dialogs that appear over the browser window, notifications can be triggered at any time, even when the webpage is not the active page. For example, you can use a notification to inform the user that some long running process has completed, or to inform the user of some error in your web app.

By default, web notifications are blocked. To display notifications, you need to receive permission from the user. The Web Notifications API provides methods to check whether the user has previously granted permission, and if not, to request permission. When called, requestPermission() displays a dialog box to the user requesting permission on behalf of your web site.

Currently, the Web Notifications API specification is a working draft. As a result, the implementation of this API by the BlackBerry Browser also supports the webkit prefix. Because the specification is in flux, there may be differences between the specification and the current implementation in WebKit.

Event handlers

Property name

Description

Support level

Availability

onclick

Specifies the function to perform when the notification is clicked in the Notifications list.

Web Notifications

2.0+

onclose

Specifies the function to perform when the notification is closed.

Web Notifications

2.0+

onerror

Specifies the function to perform when an error occurs that prevents the notification from being displayed.

Web Notifications

2.0+

onshow

Specifies the function to perform when a key is pressed and released while the pointer is over an element.

Web Notifications

2.0+

Methods

Method name

Description

Support level

Availability

checkPermission()

Checks to see whether the user previously granted your website permission to display web notifications. A return value of 0 indicates that the user granted permission for your website to display notifications.

Not defined in the W3C specification.

2.0+

createNotification( DOMString url, DOMString title, DOMString body )

Creates a new notification. This method takes the following parameters:

  • url : Specifies the URL of an icon image to be displayed with the notification. This argument is ignored. The browser icon is displayed beside all web notifications displayed in the Notifications list.
  • title : Specifies the title for the notification.
  • body : Specifies the notification body. Notifications in the BlackBerry PlayBook OS are limited to text only.

Not defined in the W3C specification.

2.0+

requestPermission( Function callbackFunction )

When called, displays a dialog box displays a dialog box to request the user's permission to display web notifications. This method requires a callback function as its argument. If the user grants permission, the callback function is called. Typically, this callback function creates and shows the notification message.

Web Notifications

2.0+

show()

Displays the notification in the Notifications list on the status bar of the home screen.

Not defined in the W3C specification.

2.0+

Example

The following example illustrates how to use the Web Notifications API to display a web notification.

function sendMessage() {
	var imgPath, title, message;

    //Defines the message title and body               
	imgPath = "http://my.domain.com/images/monkey-icon.png";
	title = "Web Notification";
	message = "Sent from my cool app.";
	
	//Create a new notification and add it to the home screen 
	webkitNotifications.createNotification(imgPath, title, message).show();
}

function sendNotification(e) {
	if (window.webkitNotifications) {

		//check to see whether the user has already granted 
		//permission to display notifications 
		if (window.webkitNotifications.checkPermission() === 0) {                                                  
        	sendMessage();
		} 

		//request permission from the user to display 
        //notifications if not already granted
		else {                                                  
        	webkitNotifications.requestPermission(sendMessage);
		}
    }
	else {
		console.log("Error in sendNotification: Notifications API is undefined");
    }
} 

Last modified: 2014-03-10



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus