Building Add-ons for Firefox on Android

Firefox on Android supports add-ons using the exact same extension system used by all other Gecko-based applications. We did not invent a new add-on system. This means that building an add-on for Firefox on Android is the same process that would be used for desktop Firefox. Add-ons that work with desktop Firefox do not automatically work in Firefox on Android. The user interfaces are just too different.

Note: Firefox on Android has a unique application identifier which must be used in install.rdf. The identifier is {aa3c5121-dab2-40e2-81ca-7ea25febc110}

The Familiar Parts

If you have made add-ons for other applications before, building one for Firefox on Android is not so different. Both classic restart-required and newer restartless add-on approaches are supported. Using the restartless approach is preferred whenever possible because the user experience is far superior to forcing an application restart when installing or removing an add-on.

• Use install.rdf and chrome.manifest register your add-on.
• Use JavaScript to create scripts and components for use in your add-on.
• Access web content directly, just as you would in desktop Firefox using browser.contentWindow and browser.contentDocument. There is no multi-process (e10s) in Firefox for Android.
• Services like nsIPromptService and nsIAlertsService are implemented to use native Android UI.
• Use overlays to add JavaScript scripts into the browser.js scope, just as you would in desktop Firefox.

The Different Parts

The big difference you'll notice is that Firefox on Android uses a native Android user interface, instead of the typical XUL based interface found on desktop Firefox. There is no visible XUL user interface. The internal JavaScript source code, the core is browser.js, is entirely different and not compatible with desktop Firefox.

• There is no visible XUL in the UI, so using overlays to try to add or change UI is useless.
• Internal code and objects, like gBrowser, do not exist. Look at the Firefox on Android browser.js file to learn about the internals. Much of the same fundamental functionality exists.
• There is a simple JavaScript object, called NativeWindow, that allows you to manipulate parts of the native Android UI.

NativeWindow

We wanted to give add-on developers some APIs to manipulate the native Android UI, so we create a helper object called NativeWindow. The API gives you access to:

• Android Menu
• Doorhanger Notifications
• Context Menus (in web content)
• Android popup toast alerts

The basic API is here:

/*
label: menu label
icon: file:// or data: URI for an icon
callback: JS function called when menu is tapped
returns a menu ID that can be used to remove the menu
*/
menuID = NativeWindow.menu.add(label, icon, callback);
NativeWindow.menu.remove(menuID);

/*
message: displayed text
value: string based tag
buttons: array of JS objects used to create buttons in the notification
tabID: tab associated with this notification
options: JS object that has 'persistence' and 'timeout' options
*/
NativeWindow.doorhanger.show(message, value, buttons, tabID, options);
NativeWindow.doorhanger.hide(value, tabID);

/*
label: menu label
selector: JS object that has a 'matches(element)' function. Used to show the menu.
callback: JS function called when menu is tapped
returns a menu ID that can be used to remove the menu
*/
menuID = NativeWindow.contextmenu.add(label, selector, callback);
NativeWindow.contextmenu.add(menuID);

/*
message: displayed text
duration: "short" or "long"; Used for alert timeout
*/
NativeWindow.toast.show(message, duration);

TODO

• Add links to other add-on docs
• Add info on inline-options
• Add links to skeleton add-ons
• Add info on other APIs like nsIHapticFeedback
• Add some code snippets