browser_specific_settings

Description

The browser_specific_settings key contains keys that are specific to a particular host application.

Firefox (Gecko) properties

Firefox stores browser-specific settings in these properties:

• gecko for the desktop and (when enabled) Android versions of Firefox.
• gecko_android for the Android version of Firefox.

The gecko sub-key supports these properties:

data_collection_permissions

The optional and required data types that the extension collects and transmits for storage and processing outside the extension. These are represented by the properties:

required

The data that the extension requires to be collected and transmitted for its operation. Must contain the value none, or one or more of authenticationInfo, bookmarksInfo, browsingActivity, financialAndPaymentInfo, healthInfo, locationInfo, personalCommunications, personallyIdentifyingInfo, searchTerms, websiteActivity, or websiteContent.

optional Optional

The data that the user can opt to provide. Can contain one or more of authenticationInfo, bookmarksInfo, browsingActivity, financialAndPaymentInfo, healthInfo, locationInfo, personalCommunications, personallyIdentifyingInfo, searchTerms, technicalAndInteraction, websiteActivity, or websiteContent.

For more information, see the Extension Workshop article Firefox built-in consent for data collection and transmission.

id

The extension ID. Optional for Manifest V2 (although setting an ID is recommended) and required for signing Manifest V3 extensions. If you don't provide a value for Manifest V2 extensions, AMO assigns a GUID to the extension when it is signed. You must create an ID for signing Manifest V3 extensions; AMO does not assign an ID. When provided, this property must be a:

• (recommended) string containing 80 characters or less formatted like an email address. (^[a-zA-Z0-9-._]*@[a-zA-Z0-9-._]+$). While you can use a real email address (remembering that this may attract spam), any correctly formatted string can be used. For example, great_app@developers.company.
• GUID (^{[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}}$)

When signing extensions for the first time, addons.mozilla.org (AMO) checks that the ID is unique.

For example:

json

  "id": "extensionname@example.org"

json

  "id": "{daf44bf7-a45e-4450-979c-91cf07434c3d}"

See Extensions and the Add-on ID for more information about setting extension IDs.

strict_min_version

Minimum version of Gecko to support. If the Firefox version on which the extension is being installed or run is below this version, the extension is not installed or not run. If not provided, all versions earlier than strict_max_version are supported. "*" is not valid in this field.

Note: The minimum supported version capable of receiving updates is 115.0 (ESR) or, if ESR versions are not included, 128.0. This is due to the expiration of the root certificate in Firefox in March 2025. As a result, older versions of Firefox don't recognize extension signatures. See Update Firefox to prevent add-ons issues from root certificate expiration for more information.

strict_max_version

Maximum version of Gecko to support. If the Firefox version on which the extension is being installed or run is above this version, the extension is not installed or not run. Defaults to "*", which disables checking for a maximum version.

See the list of valid Gecko versions.

update_url

A link to an extension update manifest. Note that the link must begin with "https". This key is for managing extension updates yourself (i.e., not through AMO).

The gecko_android sub-key supports these properties:

strict_min_version

Minimum version of Gecko to support on Android. If the Firefox for Android version on which the extension is being installed or run is below this version, the extension is not installed or not run. If not provided, defaults to the version determined by gecko.strict_min_version. "*" is not valid in this field.

strict_max_version

Maximum version of Gecko to support on Android. If the Firefox version on which the extension is being installed or run is above this version, the extension is not installed or not run. Defaults to the version determined by gecko.strict_max_version.

To support Firefox for Android without specifying a version range, the gecko_android sub-key must be an empty object, i.e., "gecko_android": {}. Otherwise, the extension is only made available on desktop Firefox.

Extension ID format

The extension ID must be one of these:

• GUID
• A string formatted like an email address: extensionname@example.org. However, use of an @string format is recommended.

The latter format is easier to generate and manipulate. Be aware that using a real email address here may attract spam.

For example:

"id": "@extension-name.developer-name"

"id": "{daf44bf7-a45e-4450-979c-91cf07434c3d}"

Safari properties

Safari stores its browser-specific settings in the safari sub-key, which has these properties:

strict_min_version

Minimum version of Safari to support.

strict_max_version

Maximum version of Safari to support.

Chrome properties

Chrome doesn't use this key and ignores it if present in an extension's manifest.json file.

Examples

Example with all possible keys. Note that most extensions omit strict_max_version and update_url.

"browser_specific_settings": {
  "gecko": {
    "id": "@addon-example",
    "strict_min_version": "42.0",
    "strict_max_version": "50.*",
    "update_url": "https://example.com/updates.json"
  },
  "safari": {
    "strict_min_version": "14",
    "strict_max_version": "20"
  }
}

Browser compatibility