Addons developer guide


Support for extensions using XUL/XPCOM or the Add-on SDK was removed in Firefox 57, released November 2017. As there is no supported version of Firefox enabling these technologies, this page will be removed by December 2020.

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 (AMO) for desktop Firefox and Firefox for Android.

Starting from Firefox 57, only extensions developed using WebExtensions APIs will be supported on Desktop Firefox and Firefox for Android.

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 use WebExtensions APIs 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.


Getting Started

This guide walks you through the steps needed to make a restartless add-on for Firefox on Android. If you are familiar with building add-ons for desktop Firefox, much of this guide will be review. Firefox on Android uses native Android widgets for the browser UI so the big difference is how you interact with the browser UI.

This add-on won't do anything in particular, just show you how to hook into the new APIs. Building something useful is an exercise left to the reader.


As always, we need an install.rdf file. There is nothing new here except for the Firefox on Android app-id, but note that we do set the bootstrap flag:

<?xml version="1.0"?>
<RDF xmlns="" xmlns:em="">
    <Description about="urn:mozilla:install-manifest">
        <em:name>Simple Native Firefox Add-on</em:name>
        <em:description>A small demo add-on for Firefox on Android (Native)</em:description>
        <em:creator>John Smith</em:creator>
        <!-- Mobile Native -->

Since we are making a restartless add-on, we also need a bootstrap.js file. This file is the main entry point for the add-on. The requirements for the file are simple, but you need to add some of your own code to make sure you manage DOM windows. Here is a simple example:

const Cc = Components.classes;
const Ci = Components.interfaces;

function isNativeUI() {
  let appInfo = Cc[";1"].getService(Ci.nsIXULAppInfo);
  return (appInfo.ID == "{aa3c5121-dab2-40e2-81ca-7ea25febc110}");

function loadIntoWindow(window) {
  if (!window)
  // DO SOMETHING HERE (create UI)

function unloadFromWindow(window) {
  if (!window)
  // CLEAN UP HERE (remove the UI)

var windowListener = {
  onOpenWindow: function(aWindow) {
    // Wait for the window to finish loading
    let domWindow = aWindow.QueryInterface(Ci.nsIInterfaceRequestor).getInterface(Ci.nsIDOMWindowInternal || Ci.nsIDOMWindow);
    domWindow.addEventListener("load", function onLoad() {
      domWindow.removeEventListener("load", onLoad, false);
    }, false);
  onCloseWindow: function(aWindow) {},
  onWindowTitleChange: function(aWindow, aTitle) {}

function startup(aData, aReason) {
  let wm = Cc[";1"].getService(Ci.nsIWindowMediator);

  // Load into any existing windows
  let windows = wm.getEnumerator("navigator:browser");
  while (windows.hasMoreElements()) {
    let domWindow = windows.getNext().QueryInterface(Ci.nsIDOMWindow);

  // Load into any new windows

function shutdown(aData, aReason) {
  // When the application is shutting down we normally don't have to clean
  // up any UI changes made
  if (aReason == APP_SHUTDOWN)

  let wm = Cc[";1"].getService(Ci.nsIWindowMediator);

  // Stop listening for new windows

  // Unload from any existing windows
  let windows = wm.getEnumerator("navigator:browser");
  while (windows.hasMoreElements()) {
    let domWindow = windows.getNext().QueryInterface(Ci.nsIDOMWindow);

function install(aData, aReason) {}
function uninstall(aData, aReason) {}

This basic code has two window-based entry points: loadIntoWindow and unloadFromWindow. Think of these methods like you would window.onload and window.onunload for non-restartless add-ons. These are the places where we can add our add-on specific UI and behavior. There are many more features and utilities you can use with restartless add-ons.

I also added a helper method, isNativeUI, in case you need to check to see if the add-on is running in Native Firefox on Android or the older XUL-based version.

Adding UI

To add UI widgets in traditional add-ons, you could use XUL overlays or dynamically create XUL elements and add them to the DOM document. You can't do that in Firefox on Android since the UI is entirely native widgets. Instead, you can use an API to manipulate the native UI. The entry point for the API is a JavaScript object called NativeWindow. The API allows you to interact with several UI widgets:

  • Android Menu
  • Popup (doorhanger) Notifications
  • Context Menus (in web content)
  • Android Toast alerts

Adding/Removing a Menu Item

You can add and remove a menu item from the Android application main menu. When adding a menu, you are given a token which you can use to remove the menu:

var menuId;
function loadIntoWindow(window) {
  if (!window)
  menuId ="Show Toast", null, function() { showToast(window); });
The bootstrap script is not attached to a DOM window, so you need to pass the reference to the window to other functions if you need access to it.

Removing a menu is just as easy:

function unloadFromWindow(window) {
  if (!window)

Showing a Toast Alert

A toast alert is a simple short lived notification popup. It is useful for showing an action has completed without causing the user too much distraction. The popup closes on its own after a short or long duration.

function showToast(aWindow) {"Showing you a toast", "short");

Showing a Notification

Doorhanger notifications are slightly more complicated, and allow the user to tap buttons to make a choice. The popups are modeless so they don't require the user to explicitly close them. They are assoicated with a tab too, so switching to a different tab will hide any open notifications. Conversely, when switching back to a tab with active doorhanger notifications causes them to become visible again.

function showDoorhanger(aWindow) {
  buttons = [
      label: "Button 1",
      callback: function() {"Button 1 was tapped", "short");
    } , {
      label: "Button 2",
      callback: function() {"Button 2 was tapped", "short");
    }];"Showing a doorhanger with two button choices.", "doorhanger-test", buttons);

If you don't explicitly pass a tab ID along with the doorhanger, the selected tab is assumed. You can also pass a name along with the doorhanger, "doorhanger-test" in this example. You can use the name to hide the doorhanger programmatically, if needed:

function hideDoorhanger(aWindow) {

Adding/Removing a Context Menu

You can add and remove a menu item from the web content context menu. A context menu appears when you long-tap on an element in the webpage. Firefox already has some built-in context menus, but you can create your won too. When adding a context menu, you are given a token which you can use to remove the context menu:

var contextId;
function loadIntoWindow(window) {
  if (!window)
  contextId = window.NativeWindow.contextmenus.add(
    "Copy Link",
    function(aTarget) { copyLink(window, aTarget); }

You can see that a context menu is a bit more complicated than a simple menu. The second parameter is a selector function (think CSS selector) that let's Firefox know what type of element triggers your context menu. In the example I use the built-in link (<a>) selector. The selector is simply an object with a matches method like this:

  matches: function(aElement) {
    // return true if the element triggers your context menu or false if it doesn't
    let name = aElement.localName;
    return name == "p";

Removing a context menu is just as easy and can be done at any time, not just when unloading the add-on from a window:

function unloadFromWindow(window) {
  if (!window)

Showing Dialogs and Prompts

You can show native Android dialogs and prompt using the same nsIPromptService interface used on desktop Firefox. The implementation uses native Android dialogs instead of the XUL dialogs used on desktop.

Wrapping It Up

As with any other restartless add-on, you need to bundle the install.rdf and bootstrap.js (along with any other files you added) into an XPI file. You are now ready to install your add-on and try it out.

Installing addons on Android can be a bit tricky. There are a few different approaches that developers take. If you're comfortable putting your extension up on a public server, you can just follow a link. There are also extensions to simplify the process. If you have the Android SDK installed, you can also run a few simple adb commands to copy the extension to your phone and load it in Fennec:

adb push myAddon.xpi /sdcard/myAddon.xpi
adb shell am start -a android.intent.action.VIEW \
                   -c android.intent.category.DEFAULT \
                   -d file:///mnt/sdcard/myAddon.xpi \
                   -n org.mozilla.firefox/.App
Replace org.mozilla.firefox/.App with org.mozilla.firefox_beta for beta releases, org.mozilla.fennec_auora for Aurora builds, org.mozilla.fennec for Nightly, and org.mozilla.fennec_<your_username> for private builds.
It may occur when installing the way mentioned, the plugin be installed but does not show the changes on the browser. If this happens, try uploading the XPI to a website and accessing it from your mobile browser.