This article needs a technical review. How you can help.

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.


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.


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,


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



Adds a notification with the given options

String guid add(Object 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 an id for the notification that was shown. You can hold on to this to hide or update the notification at some later point.


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


Updates an existing notification

void update(String guid, Object options)


The guid you were handed when you created this notification
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.


Notifications.update(id, {
  progress: newProgress


Remove a notification from the system bar

void cancel(String guid);


The guid you were handed when you created this notification




Unregisters a handler registered using registerHandler

void unregisterHandler(String key, NotificationHandler handler);


The key this handler registered under.
The NotificationHandler to unregister.


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

void registerHandler(String key, NotificationHandler handler);


The key this handler would like to register under. Any notifications with this key will call this handler when they're clicked/cancelled.
A NotificationHandler that will be called whenver notifications with this key are clicked or cancelled.

Document Tags and Contributors

 Contributors to this page: sangecz, wbamberg, lbernd, TonyHEssex, wesj, leibovic, evilpie
 Last updated by: sangecz,