Desktop Notifications

Contents

1. Manifest
   1. h3Name
2. Communicating with other views
   1. h3Name
3. Examples
   1. h3Name
4. API
   1. h3Name
5. API reference
   1. Properties
      1. propertyName
   2. Methods
      1. methodName
   3. Events
      1. eventName
   4. Types
      1. id

Use desktop notifications to notify users that something important has happened. Notifications appear outside the browser window. As the following snapshots show, the details of how notifications look and where they're shown depend on the platform.

You create the notification window using a bit of JavaScript and, optionally, an HTML page packaged inside your extension.

Manifest

You can request the notification permission in the extension manifest, like this:

{
  "name": "My extension",
  ...
  "permissions": [
    "notifications"
  ],
  ...
}

Note: Extensions that declare the notifications permission are always allowed to create notifications. There is no need to call webkitNotifications.checkPermission().

Communicating with other views

You can communicate between a notification and other views in your extension using getBackgroundPage() and getViews(). For example:

// Inside a notification...
chrome.extension.getBackgroundPage().doThing();

// From the background page...
chrome.extension.getViews({type:"notification"}).forEach(function(win) {
  win.doOtherThing();
});

Examples

You can find a simple example of using notifications in the examples/api/notifications directory. For other examples and for help in viewing the source code, see Samples.

Also see html5rocks.com's notifications tutorial. Ignore the permission-related code; it's unnecessary if you declare the "notifications" permission.

API

The desktop notification API for extensions is the same one that is available to normal web pages. As the following code shows, you first create either a simple text notification or an HTML notification, and then you show the notification.

// Create a simple text notification:
var notification = webkitNotifications.createNotification(
  '48.png',  // icon url - can be relative
  'Hello!',  // notification title
  'Lorem ipsum...'  // notification body text
);

// Or create an HTML notification:
var notification = webkitNotifications.createHTMLNotification(
  'notification.html'  // html url - can be relative
);

// Then show the notification.
notification.show();

For complete API details, see the Desktop notifications draft specification.