Developing extensions for Firefox for Android

You will approach the coding of an extension for Firefox for Android in the same way as you would for a desktop extension using WebExtension APIs; using a text editor or tool of your choice to write the code. However, when you get to testing and debugging your extension you need to follow a different process, this article walks you through that process.

Set up your computer and Android emulator or device

You first need to complete some one-off setup tasks on your computer and Android device.

On your development computer:

• If you want to test on your computer by running Firefox for Android in the Android emulator:
  • Install Android Studio.
  • Use the Android Studio SDK Manager or the sdkmanager command-line tool to install the Android Platform Tools.
• If you plan to test in Firefox for Android running on a device only:
  • Download and extract the standalone Android SDK Platform-Tools package to a suitable location on your computer.
  • On Windows, Mac, or Linux: Add the location into which you extracted the tools package to your operating system’s PATH environment variable.
  • Alternatively, on Mac or Linux: Link the binary to /usr/local/bin using sudo ln -s /<extract folder>/platform-tools/adb /usr/local/bin.

On your device or Android emulator:

• Install Firefox for Android and, if you wish to test the latest features, Firefox for Android Beta or Firefox Nightly for Developers.
• Open Firefox for Android and turn off signing by browsing to about:config then locating and setting xpinstall.signatures.required to false.
  

If you are using a device:

• Enable Android USB debugging on the device. You need to follow step 2 only, but note that you may have to enable the developer options if you do not see them on your device.
• Attach your device to the development computer using a USB cable and on the device, when prompted, allow USB debugging for the connection.

On your development computer:

• Open a command shell.
• Run adb devices
  You should see output similar to:
  List of devices attached
51800F220F01564 device
  Where the hex string is your device’s (or emulator’s) code. This means adb has found your device (or emulator).

Install and run your extension in Firefox for Android

In your extension ensure that you have included an application ID using the applications key in the manifest.json:

 "applications": {
    "gecko": {
       "id": "borderify@example.com"
    }
 },

Zip the content of your extension into an xpi file named to match the application ID, for example, borderify@example.com.xpi.

You now have two options for transferring and running your extension: using adb or a website.

Transfer your extension using adb

On your computer, execute /path/to/adb push /path/to/<extension file name>.xpi /mnt/sdcard/, which will transfer the extensions xpi file to your attached emulator or device.

On your Android device or in the emulator, open Firefox for Android and browse to file:///mnt/sdcard:

Tap on <extension file name>.xpi to install it. You will get a warning about the extension being blocked, tap ALLOW:

An additional warning will tell you the extension is unverified, tap INSTALL:

Your extension will start running (in this case a copy of the borderify example extension):

Transfer your extension via a website.

Upload your xpi file to your website and make it accessible over HTTP. Browse to the file and download it. Follow the installation instructions, which will be similar to those for an extension transferred using adb.

Debug your extension

You can debug your extension in WebIDE and view any manifest,json validation messages using adb logcat. To make use of these features, first set up Firefox remote debugging over USB or Wi-Fi.

Using WebIDE to debug your extension

Open WebIDE from the Developer option on the desktop Firefox menu. Once open, select your connected device from the options in the right-hand sidebar.

Now, ensure you are viewing the Main Process, then load a page in which your extension will be exercised.

If you included any console messages in your extension (using console.log()), you can see these the Console tab, and can use the console filter (highlighted below) to hide other console messages:

The Debugger tab then enables you to access the background script and any content scripts:

You can now apply breakpoints and observe the extension’s behavior.

Also, you can also target the document related to an extension page, for example, the background page of the borderify example, using the same approach described for the Browser Toolbox:

Once you have switched to an extension page, you can inspect the extension page’s DOM elements from the Inspector panel (also the "inspect node" toggle button should work as expected) and execute WebExtension API calls from the Console panel:

For more details on using WebIDE, see the WebIDE section.

Viewing manifest validation messages using the console

In addition to the console messages output through WebIDE, there may also be messages relating to the validation of the extension’s manifest.json files. These messages can be viewed using the adb logcat command. To avoid receiving other, unrelated messages, you can pipe the output through grep, filtering by the extension’s ID, for example:

/path/to/adb logcat | grep borderify@example.com

This will give output similar to this:

I/Gecko   (30440): 1496056181889    addons.xpi    WARN    Addon with ID borderify@example.com already installed, older version will be disabled

If your add-on fails to run, check these messages as they may provide information explaining why.