Notifications.jsm

Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.

Starting from Firefox 53, no new legacy add-ons will be accepted on addons.mozilla.org (AMO) for desktop Firefox and Firefox for Android.

Starting from Firefox 57, WebExtensions will be the only supported extension type. Desktop Firefox and Firefox for Android will not load other extension types.

Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to WebExtensions if they can. See the "Compatibility Milestones" document for more information.

A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.

Note: Notifications.jsm is still under development. The API may change. Use with care!

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

id = create(options) Create a new notifcation.
update(id, options) Update an existing notification.
cancel(id) Cancel an exsting notification
registerHandler(key, handler) Register a handler to be notified when a notification is clicked/cancelled
unregisterHandler(key, handler) Unregister a handler registered using registerHandler

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.
 

Document Tags and Contributors

 Last updated by: rebloor,