• Skip to main content
  • Select language
  • Skip to search
MDN Web Docs
  • Technologies
    • HTML
    • CSS
    • JavaScript
    • Graphics
    • HTTP
    • APIs / DOM
    • WebExtensions
    • MathML
  • References & Guides
    • Learn web development
    • Tutorials
    • References
    • Developer Guides
    • Accessibility
    • Game development
    • ...more docs
Add-ons
  1. MDN
  2. Mozilla
  3. Add-ons
  4. Legacy extensions for Firefox for Android
  5. Walkthrough

Walkthrough

In This Article
  1. Implementation
    1. install.rdf
    2. bootstrap.js
      1. Implementing the UI
      2. Implementing behavior
  2. Testing
    1. Setting up the environment
    2. Installing the add-on
    3. Running the add-on
    4. Logging

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, 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.

This guide walks you through the process of developing a simple add-on for Firefox for Android. The add-on adds a menu item to display the source of the current web page.

If you're familiar with developing add-ons for desktop Firefox, much of this guide will not be new to you.

The add-on is a restartless, also known as a bootstrapped, add-on: although Android add-ons don't have to be restartless, there's not much incentive to write overlay-based add-ons, since with Firefox for Android you can't create your user interface using a XUL overlay.

For some example code to get started, you can copy the native ui boilerplate add-on from github.

Implementation

To get started, created a directory called "view-source": this is where we'll keep the files for the add-on. The add-on will consist of just two files:

  • install.rdf: this contains metadata for the add-on
  • bootstrap.js: this is where all the code lives

install.rdf

Every Firefox add-on must contain an Install Manifest file named install.rdf: this contains metadata such as the add-on's identifier, its author, and its target application.

For this add-on, save the following as install.rdf directly under your "view-source" directory:

<?xml version="1.0"?>
<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:em="http://www.mozilla.org/2004/em-rdf#">
    <Description about="urn:mozilla:install-manifest">
        <em:id>view-source@mydomain.org</em:id>
        <em:type>2</em:type>
        <em:name>View Source Add-on</em:name>
        <em:version>1.0</em:version>
        <em:bootstrap>true</em:bootstrap>
        <em:description>View Source add-on for Firefox for Android (Native)</em:description>
        <em:creator>John Smith</em:creator>
        <!-- Mobile Native -->
        <em:targetApplication>
            <Description>
                <em:id>{aa3c5121-dab2-40e2-81ca-7ea25febc110}</em:id>
                <em:minVersion>25.0</em:minVersion>
                <em:maxVersion>31.*</em:maxVersion>
            </Description>
        </em:targetApplication>
    </Description>
</RDF>

To learn about all these fields and more, see the Install Manifest documentation. In particular:

  • <em:id>view-source@mydomain.org</em:id> is the unique identifier for this add-on
  • <em:bootstrap>true</em:bootstrap> indicates that this is a restartless add-on
  • <em:id>{aa3c5121-dab2-40e2-81ca-7ea25febc110}</em:id> indicates that it is aimed at Firefox for Android

bootstrap.js

Restartless add-ons must contain a file called "bootstrap.js". For more details of "bootstrap.js" refer to the bootstrapped extensions documentation.

Implementing the UI

We'll use the template "bootstrap.js" code presented in the guide to initialization and cleanup. Copy this code into a new file called "bootstrap.js",  and add implementations of the following two functions:

  • loadIntoWindow() to initialize our add-on. In this case that just means adding a new menu item to Firefox for Android's main menu.
  • unloadFromWindow() to clean up any changes we've made to Firefox. In this case that means removing the menu item.
var menuId;
function loadIntoWindow(window) {
  if (!window)
    return;
  menuId = window.NativeWindow.menu.add("View Source", null, function() {
    viewSource(window);
  });
}
function unloadFromWindow(window) {
  if (!window)
    return;
  window.NativeWindow.menu.remove(menuId);
}

We're using the NativeWindow's menu object to add the menu item.

You don't need to call loadIntoWindow() or unloadFromWindow() yourself: the template code calls them at the right time inside the startup() and shutdown() functions.

Implementing behavior

Finally we need to implement the viewSource() function. We'll use the BrowserApp addTab() method to open a new tab, loading into it the currently selected tab's URI with "view-source:" prepended to it:

function viewSource(window) {
  window.console.log("view-source@mydomain.org: displaying source for " + window.content.location.href);
  window.BrowserApp.addTab("view-source:" + window.content.location.href);
}

Add this function into "bootstrap.js", and we've finished implementing the add-on.

To package the add-on, zip up these two files and rename the result to "view-source.xpi". Note that you have to zip up the files themselves, and not their containing directory.

To see what the resulting XPI should look like, have a look at the attached example.

Testing

There are currently two ways to test a Firefox for Android add-on:

  • using the Android emulator
  • using a real Android device connected to your computer over USB

In this walkthrough we'll describe the second approach.

Setting up the environment

First you'll need an Android device capable of running Firefox for Android. Then:

  • install Firefox for Android on the device.
  • enable USB debugging on the device (step 2 of this link only)

On the development machine:

  • install the correct version of the Android SDK for your device
  • using the Android SDK, install the Android Platform Tools

Next, attach the device to the development machine via USB.

Now open up a command shell. Android Platform Tools will have installed adb in the "platform-tools" directory under the directory in which you installed the Android SDK. Make sure the "platform-tools" directory is in your path. Then type:

adb devices

You should see some output like:

List of devices attached
51800F220F01564 device

(The long hex string will be different.)

If you do, then adb has found your device and you can get started. The Android Debug Bridge (adb) has a lot of useful commands, but in this walkthrough we'll use just two:

  • adb push: to copy the add-on to the device
  • adb logcat: to get debug output sent to the command line

Installing the add-on

You have two ways to install your addon. The simplest is to upload your xpi to your site and make it accessible via HTTP. This will always work.

The second way is via ADB, and not all devices install it well (eg: Motorola Atrix). To install the add-on this way execute an adb command like:

/path/to/adb push /path/to/view-source.xpi /mnt/sdcard/

Next, open Firefox for Android and go to file:///mnt/sdcard:

mnt.png

Tap on "view-source.xpi" and follow the prompts to install it.

Alternately, you can automate this step with the following command:

/path/to/adb shell am start -a android.intent.action.VIEW \
                            -c android.intent.category.DEFAULT \
                            -d file:///mnt/sdcard/view-source.xpi \
                            -n org.mozilla.firefox/.App

Running the add-on

To try out the add-on just show the main menu and select "View Source", and you'll see the source for the page:

 

view-source.pngpage-source.png

Logging

The adb logcat command prints the Android debug log to the command line as log messages are generated. The device generates a lot of logging, so it can help to filter the output, which you can do by piping the output through grep. For example, this command will display only debug messages from Firefox:

/path/to/adb logcat | grep Gecko

Messages you have logged using the console also appear here. To see only these messages you could prefix them with something unique and filter for that string. For example, the "view-source" add-on logs a message when it's about to open the new tab, prefixed with the add-on ID "view-source@mydomain.org":

function viewSource(window) {
  window.console.log("view-source@mydomain.org: displaying source for " + window.content.location.href);
  window.BrowserApp.addTab("view-source:" + window.content.location.href);
}

To see only these messages we can filter for the add-on ID:

/path/to/adb logcat | grep view-source@mydomain.org

This will give us output like this:

E/GeckoConsole(13176): view-source@mydomain.org: displaying source for http://www.iana.org/domains/example/

Document Tags and Contributors

Tags: 
  • Extensions
  • Mobile
 Contributors to this page: rebloor, andrewtruongmoz, wbamberg, leibovic, hallvors, MarkFinkle, SaiCharanReddy.P, miket, gal007, Sheppy, DavidWalsh, ajsb85, kmaglione, gbrown
 Last updated by: rebloor, Jun 19, 2017, 7:43:41 PM
See also
  1. Browser extensions
  2. Getting started
    1. What are extensions?
    2. Your first extension
    3. Your second extension
    4. Anatomy of an extension
    5. Example extensions
  3. How to
    1. Intercept HTTP requests
    2. Modify a web page
    3. Add a button to the toolbar
    4. Implement a settings page
  4. User interface
    1. Introduction
    2. Toolbar button
    3. Address bar button
    4. Sidebar
    5. Context menu items
    6. Options page
    7. Bundled web pages
    8. Notifications
    9. Address bar suggestions
    10. Developer tools panels
  5. Concepts
    1. Using the JavaScript APIs
    2. Content scripts
    3. Match patterns
    4. Internationalization
    5. Content Security Policy
    6. Native messaging
  6. Porting
    1. Porting a Google Chrome extension
    2. Porting a legacy Firefox extension
    3. Embedded WebExtensions
    4. Comparison with the Add-on SDK
    5. Comparison with XUL/XPCOM extensions
    6. Chrome incompatibilities
    7. Differences between desktop and Android
  7. Firefox workflow
    1. Temporary Installation in Firefox
    2. Debugging
    3. Developing for Firefox for Android
    4. Getting started with web-ext
    5. web-ext command reference
    6. Extensions and the Add-on ID
    7. Publishing your extension
  8. JavaScript APIs
    1. Browser support for JavaScript APIs
    2. alarms
    3. bookmarks
    4. browserAction
    5. browserSettings
    6. browsingData
    7. commands
    8. contextMenus
    9. contextualIdentities
    10. cookies
    11. devtools.inspectedWindow
    12. devtools.network
    13. devtools.panels
    14. downloads
    15. events
    16. extension
    17. extensionTypes
    18. history
    19. i18n
    20. identity
    21. idle
    22. management
    23. notifications
    24. omnibox
    25. pageAction
    26. permissions
    27. privacy
    28. proxy
    29. runtime
    30. sessions
    31. sidebarAction
    32. storage
    33. tabs
    34. theme
    35. topSites
    36. types
    37. webNavigation
    38. webRequest
    39. windows
  9. Manifest keys
    1. applications
    2. author
    3. background
    4. browser_action
    5. chrome_settings_overrides
    6. chrome_url_overrides
    7. commands
    8. content_scripts
    9. content_security_policy
    10. default_locale
    11. description
    12. developer
    13. devtools_page
    14. homepage_url
    15. icons
    16. incognito
    17. manifest_version
    18. name
    19. omnibox
    20. optional_permissions
    21. options_ui
    22. page_action
    23. permissions
    24. protocol_handlers
    25. short_name
    26. sidebar_action
    27. theme
    28. version
    29. web_accessible_resources
  10. Themes
  11. Publishing add-ons
  12. Guides
    1. Signing and distribution overview
    2. Submit an add-on
    3. Creating an appealing listing
    4. Review policies
    5. Developer agreement
    6. Featured add-ons
    7. Contact addons.mozilla.org
  13. Community and support
  14. Channels
    1. Add-ons blog
    2. Add-on forums
    3. Stack Overflow
    4. Development newsgroup
    5. IRC Channel
  15. Legacy add-ons
  16. Legacy technologies
    1. Add-on SDK
    2. Legacy Firefox for Android
    3. Bootstrapped extensions
    4. Overlay extensions