Notifications.jsm

The Notifications.jsm JavaScript code module offers utility routines dealing with showing system notifications in Fennec. It duplicates some of what is available in the nsIAlertService already, but exposes to more advanced Android functionality.

Components.utils.import("resource://gre/modules/Notifications.jsm");

Basic usage

Notifications.jsm exports a Notification object that can be used to show, update, and cancel notifications.

The API allows you to register a handler with the Notifications object at startup. The handler object is called whenever a notification is tapped or cancelled, and passed the original cookies object. Notifications should pass in a handlerKey when they are created to ensure the right handlers are notified when they are clicked.

Example:

const MY_KEY = "this is my key";
// Added in Firefox 33
let myHandler = {
  onClick: function(cookie) { },
  onCancel: function(cookie) { },
  onButtonClick: function(buttonId,cookie) { }
};
Notifications.registerHandler(MY_KEY, myHandler);
var buttons=[{buttonId:"Pause",title:"Pause",icon:"drawable://pause"}];
let id = Notifications.create({
  icon: "drawable://stop",
  title: "Stop!"
  message: "This is a stop message",
  handlerKey: MY_KEY,
  buttons:buttons
});
...
Notifications.cancel(id);
Notifications.unregisterHandler(MY_KEY, myHandler);

Method overview

Methods

Notifications.create()

Adds a notification with the given options

String guid add(Object options);

Parameters

options

A set of options describing the notification

Option	Description
icon	An icon to show in the system tray.  MANDATORY
title	An title to show in the notification tray and in the system bar.  MANDATORY
message	A message to show in the notification tray
priority	An integer (-2 to +2) to describe the priority of this notification.
buttons	An array of buttons to show on the notification. Maximum of three.
ongoing	Boolean describing whether this notification is ongoing. Ongoing notifications can't be swiped away by the user, and use a service to try and hold Fennec open until the ongoing process (for instance a WebRTC session) is done.
progress	An integer between 0 and 100 (or NaN for indeterminate notification) describing the progress of this notification.
cookie	A cookie that's passed back to the onClick/onCancel/onButtonClick handlers. In Firefox 33+, the API was adjusted to better handle notifications that are clicked when Fennec is no longer running. For those notifications its better to use only serializable properties.
handleKey	A key that's used to determine who to notify when the notification is clicked or cancelled.

Returns

guid

Returns an id for the notification that was shown. You can hold on to this to hide or update the notification at some later point.

Example

var id = Notifications.create({
  title: "My title",
  message: "My message",
  icon: "drawable://stop",
});

update()

Updates an existing notification

void update(String guid, Object options)

Parameters

guid

The guid you were handed when you created this notification

options

Same as the options argument that was passed to the create method. Any options you don't specify will be refilled from the original options you passed in when the Notification was created. i.e. You don't need to update every option every time you call update.

Example

Notifications.update(id, {
  progress: newProgress
});

cancel()

Remove a notification from the system bar

void cancel(String guid);

Parameters

guid

The guid you were handed when you created this notification

Example

Notifications.cancel(id);

unregisterHandler()

Unregisters a handler registered using registerHandler

void unregisterHandler(String key, NotificationHandler handler);

Parameters

key

The key this handler registered under.

handler

The NotificationHandler to unregister.

registerHandler()

Register a handler to be notified when notifications with a given key are clicked or cancelled

void registerHandler(String key, NotificationHandler handler);

Parameters

key

The key this handler would like to register under. Any notifications with this key will call this handler when they're clicked/cancelled.

handler

A NotificationHandler that will be called whenver notifications with this key are clicked or cancelled.