1. Set up your computer and Android emulator or device
2. Check for Firefox for Android compatibility
3. Install and run your extension in Firefox for Android
4. Debug your extension
5. Manifest V3 compatibility

• Install or updateweb-ext to version 4.1.0 or later.
• Use the Android StudioSDK Manager or thesdkmanager command-line tool to install theAndroid Platform Tools
• Make sure you have adb installed (Linux,Mac,Windows) and in yourPATH.

On your device or Android emulator:

• InstallFirefox for Android Nightly
• Enable Android USB debugging on the device.
• Attach your device to the development computer using a USB cable. When prompted, allow USB debugging for the connection.
• In the settings view for Firefox for Android Nightly, enable "Remote debugging via USB."

Then, on your development computer:

• Open a command shell.
• Runadb devices
  You should see output similar to:

  List of devices attached51800F220F01564 device

  Where the hex string is your device’s (or emulator’s) code. This means adb has found your device (or emulator).

Before running your extension on Firefox for Android, consider usingweb-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 includingstrict_min_version values for the optionalgecko andgecko_android sub-keys inbrowser_specific_settings. 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 byPERMISSION_FIREFOX_ANDROID_UNSUPPORTED_BY_MIN_VERSION,
• incompatible manifest keys are identified byKEY_FIREFOX_ANDROID_UNSUPPORTED_BY_MIN_VERSION, and
• incompatible APIs are identified byANDROID_INCOMPATIBLE_API

similar to this:

When settingstrict_min_version values inbrowser_specific_settings, unless you're targeting a specific version of Firefox, choose the most recent version of Firefox you expect your extension to be compatible with. Due to Android's different APIs and form factors (compared to desktop Firefox), setgecko_android after explicitly verifying compatibility. This sub-key enables a compatibility range that is distinct from Firefox for desktop.

"browser_specific_settings":{"gecko":{"strict_min_version":"102.0"},"gecko_android":{"strict_min_version":"113.0"}}

• If you haven't usedweb-ext lint, checkBrowser Support for JavaScript APIs to verify that the APIs your extension uses are available on Firefox for Android.

• Make sure HTML pages haveviewport meta tags to scale your extension's UI on mobile screens properly.

• Useresponsive design patterns to ensure that your UI meets the expectations of Android users.

• Go through all of your extension's critical paths on an Android device to ensure they work as expected.

• Make sure the extension works well without an internet connection, as connectivity can be unreliable on mobile devices.

• Test your extension on a variety of device types and sizes. Android Studio'svirtual devices can help.

In the unzipped directory of your extension, runweb-ext run -t firefox-android and follow the instructions on screen to make sure you select the right device. Selectorg.mozilla.fenix as the apkname (ororg.mozilla.firefox_beta for Firefox Beta for Android).

Here is an example of the command:

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

You can debug your extension in the web developer tools and view anymanifest.json validation messages usingadb logcat. To make use of these features, first set up Firefox remote debuggingover USB orvia Wi-Fi.

Using web development tools to debug your extension

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

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

If prompted, allow the incoming connection on your Android device. Now start your extension on the Android device usingweb-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 findProcesses in the list of active features in the browser.

ClickInspect next toMain Process. The web developer toolbox displays inDebugger.

For much of the debugging work, it's useful to be able to viewConsole withInspector orDebugger. You do this using thesplit console, pressesc to activate this mode.

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

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

To inspect the popup's HTML and CSS, useInspector. First, click the page select icon () to open the HTML document you want to inspect. You canreview and modify the document's HTML and CSS inInspector, as you would with any webpage.

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

Viewing manifest validation messages using the console

In addition to the messages from your code, the console may also include messages about the validation of the extension'smanifest.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.

Tags: add-ons beginner guide mobile webextensions 

Contributors: Rob--W caitmuenster rebloor juraj ExE-Boss Ding-Fan andrewtruongmoz 

Last update: Rob--W Nov 12, 2023