Developing extensions for Firefox for Android

Learn more about developing extensions for Firefox for Android

In August 2020, Mozilla launched a new, reimagined Firefox for Android experience (codenamed "Fenix"). The browser for Android has been rebuilt from the ground up using GeckoView, Mozilla's mobile browsing engine.

Currently only a limited number of Recommended Extensions are supported on the release channel. However, we are continuously working on increasing support, taking into account usage and feedback to ensure we are making the most of our available resources. We will post updates to The Add-ons Blog) as plans solidify each quarter.

If you are interested in Firefox for Android 68 and earlier (Fennec), please visit this article.

You'll approach the coding of an extension for Firefox for Android in the same way as you would for a desktop extension; using a text editor or tool of your choice to write the code. However, when you want to test and debug 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

Complete some one-off setup tasks on your computer and Android device.

On your development computer:

On your device or Android emulator:

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

Check for Firefox for Android compatibility

Linting results are currently not updated to include Fenix compatibility. Some warnings may not be accurate.

Before running your extension on Firefox for Android, consider using web-ext lint. Lint performs a check to determine if any of the permissions, manifest keys, and web extension APIs you’re using are incompatible with Firefox for Android. Lint relies on your extension’s manifest.json file including strict_min_version, it then reports on the features that are not supported by the minimum version you have set.

In the lint report:

  • incompatible permissions are identified by PERMISSION_FIREFOX_ANDROID_UNSUPPORTED_BY_MIN_VERSION,
  • incompatible manifest keys are identified by KEY_FIREFOX_ANDROID_UNSUPPORTED_BY_MIN_VERSION, and
  • incompatible APIs are identified by ANDROID_INCOMPATIBLE_API

similar to this:

linter screenshot

Lint does not report on APIs that are not implemented by Firefox or Firefox for Android.

When setting strict_min_version, unless you’re targeting a specific version of Firefox, choose the most recent version of Firefox you expect your extension to be compatible with. For example, you can reasonably expect that most installations of Firefox for Android will be the current or previous version. So, if the current version is 66, consider setting 65 is the minimum version.

"browser_specific_settings": {
"gecko": {
"strict_min_version": "65.0"
}
}

Install and run your extension in Firefox for Android

These instructions are for temporarily loading an extension. Instructions for persistent loading extensions in Firefox for Android Nightly can be found on this blog post.

In your extension, ensure that you've included an application ID using the browser_specific_settings key in the manifest.json:

"browser_specific_settings": {
"gecko": {
"id": "borderify@example.com"
}
}

In the unzipped directory of your extension, run web-ext run -t firefox-android and follow the instructions on screen to make sure you select the right device. Select org.mozilla.fenix as the apkname.

Here is an example of the command:

web-ext run -t firefox-android --adb-device XXX --firefox-apk org.mozilla.fenix

The add-on will be loaded in the main browser profile instead of a new temporary profile directory.

Debug your extension

Currently, you cannot inspect the markup of Fenix's browserAction popups using the Firefox Developer Tools Inspector (see bug 1637616). As a workaround, we recommend that you temporarily change the extension to open the popup extension page into a tab to be able to inspect it.

You can debug your extension in the web developer tools 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 web development tools to debug your extension

With your device connected over USB or Wi-Fi, open about:debugging and enable the device connection.

Enable USB Devices

Your device is listed in the left-hand column, click Connect.

Connect to device

If prompted, allow the incoming connection on your Android device. Now start your extension on the Android device using web-ext run. You will need to have at least one tab opened in order for your extension to load. Click your device in the left-hand column and scroll down to find Processes in the list of active features in the browser.

Locate processes

Click Inspect next to Main Process. The web developer toolbox displays in Debugger.

For much of the debugging work, it's useful to be able to view Console with Inspector or Debugger. You do this using the split console, press esc to activate this mode.

Load a page in which your extension exercises. Now you can access any of the JavaScript in your extension.

Device debugging

Content scripts can be reached and debugged when connected to the main process or to a tab target where a content script is running.

In the Debugger you can set breakpoints, step through code, modify the extension's state, and do everything else you'd expect to be able to do in a debugger. Any messages logged by your code display in Console.

To inspect the popup's HTML and CSS, use Inspector. First, click the page select icon (Device debugging) to open the HTML document you want to inspect. You can review and modify the document's HTML and CSS in Inspector, as you would with any webpage.

For more details on using the web developer tools, see Firefox Developer Tools.

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.