Firefox version compatibility

Version compatibility

Version compatibility controls let you manage which versions of Firefox can install your extension. You use these controls to make an extension available on Android or prevent incompatible versions of Firefox from installing the extension. For example, say your extension uses the Declarative Net Request API. To ensure that only compatible versions of Firefox install it, you set the minimum compatible version to 113, the first release that supported this API.

There are two ways to control Firefox version compatibility settings for an add-on. Each setting controls a different part of the add-on installation experience.

• The browser_specific_settings field in manifest.json: This controls the version compatibility check that the user's web browser performs during installation. It is also used to populate AMO's compatibility controls.
• AMO's compatibility controls: This controls what extensions appear in search results on AMO and are available for installation from AMO.

The way these two mechanisms interact means it's possible to make an extension available for download in a Firefox version that will not install it. To avoid this, it's strongly recommended that you only use browser_specific_settings to control browser compatibility settings.

The browser_specific_settings key

This is the recommended method for managing an extension's browser compatibility settings.

The browser_specific_settings manifest key enables you to statically declare what versions of Firefox can load the extension. The extension's installation fails on Firefox versions outside the supported range.

As these values are hardcoded in the extension, they cannot be changed after a version has been packaged. When distributing on AMO, you must submit a new version of the extension to modify the range of Firefox versions that can load the extension.

There are two subkeys for Firefox browsers:

• gecko for the desktop version of Firefox.
• gecko_android for the Android version of Firefox.

Both gecko and gecko_android accept two version-related properties:

-strict_min_version, which specifies the earliest version of the browser that can load the extension.

• strict_max_version, which specifies the latest version of the browser that can load the extension. Avoid unless absolutely necessary.

Android compatibility

To signal to AMO that your extension is compatible with Android, include, at least, an empty browser_specific_settings.gecko_android object in your manifest. If you don't, AMO assumes that the extension is not compatible with Android and does not list it as available on Android. This can be manually overridden using AMO's compatibility controls. Omitting "gecko_android" does not affect Firefox for Android's ability to install the extension.

{
  "name": "Desktop & Android extension",
  "version": "1.0",
  "manifest_version": 2,
  "browser_specific_settings": {
    "gecko_android": {}
  }
}

AMO compatibility setting

AMO's browser version compatibility settings determine whether the extension is listed in a search of AMO from a version of Firefox and whether it is available for installation. When an extension is uploaded to AMO, the extension's browser compatibility settings in AMO are set from the browser_specific_settings of the extension's manifest.

AMO's compatibility settings can be used to adjust an extension's availability after publication. For example, if user feedback reveals compatibility issues with older versions of Firefox, you can adjust the minimum Firefox version setting to prevent other users from encountering that bug. Remember, if you set a wider range of supported versions in AMO, AMO will show that the extension is installable but the installation process will fail due to the Firefox version limits set in its manifest file.

To manually configure the browser compatibility settings:

1. Visit the Add-on Developer Hub.
   
   

2. In My Add-ons, find the add-on you want to configure and select Edit Product Page.

3. Select Manage Status & Versions in the left navigation menu. A list of all your extension versions displays.
   
   

4. Choose the extension version you want to configure.

5. In the compatibility section, for the product you want to specify versions for, select the earliest and latest product versions this version of your add-on is compatible with. Remember, if you used browser_specific_settings.gecko_android the compatibility settings for Android are locked.
   
   

6. Select Save Changes to apply your edits.

Recommendations

1. Use browser_specific_settings as your primary (or only way) tool for managing Firefox version compatibility settings.

2. If you want to support Android, make sure you have a browser_specific_settings.gecko_android object in your manifest.

3. Do not use strict_max_version unless absolutely necessary. This setting can lead to unexpected results.