AMRemoteSettings Overview

AMRemoteSettings is a singleton that is responsible for fetching data from a RemoteSettings collection named "main/addons-manager-settings" to remotely control a set of Add-ons related preferences (hardcoded inside the AMRemoteSettings definition part of a given Firefox release).

AMRemoteSettings will process the collection data when the RemoteSettings "sync" event is fired and on late browser startup if there is already some data stored locally in the collection (and so if the pref value is manually changed, then it would be set again to the value stored in the RemoteSettings collection data, either on the next browser startup or on the next time the "sync" event is fired again).

Warning

Any about:config preference that AMRemoteSettings singleton sets while processing the RemoteSettings collection data are never cleared automatically (e.g. if in a future Firefox version AMRemoteSettings does not handle a particular settings anymore, or if the RemoteSettings entry is removed from the collection on the RemoteSettings service side).

In practice this makes this feature a good choice when the remotely controlled about:config preferences is related to:

• Firefox Add-ons features in the process of being deprecated and then fully removed in a future Firefox release

• or controlled settings that are never removed from the "main/addons-manager-settings" collection.

In general before changing controlled settings in the "main/addons-manager-settings" collection it is advisable to:

• make sure to default value for the related about:config preferences has been changed in mozilla-central first, and to let it ride the release train and get some backing time on release;

• only after that consider changing the value controlled by "main/addons-manager-settings" collection, to set the same value on older Firefox releases where the previous default value was set.

The AMRemoteSettings singleton queries RemoteSettings and processes all the entries got from the "main/addons-manager-settings" collection, besides entries that may be filtered out by RemoteSettings based on the "filter_expression" property (See https://remote-settings.readthedocs.io/en/latest/target-filters.html#how).

Each of the entries created in the "main/addons-manager-settings" collection and is expected to match the JSONSchema described in the JSON Schema section below.

For each entry found in the collection, only the properties that are explicitly included in the AMRemoteSettings.RS_ENTRIES_MAP object are going to be processed (e.g. new Firefox versions may have introduced new ones that older Firefox version will just ignore):

• Each of the AMRemoteSettings.RS_ENTRIES_MAP properties:

  • represents a group of settings (e.g. the property named "installTriggerDeprecation") is responsible of controlling about:config preferences related to the InstallTrigger deprecation

  • is set to an array of string, which lists the about:config preferences names that can actually be controlled by the related group of settings (e.g. "installTriggerDeprecation" can only control two preferences, "extensions.InstallTrigger.enabled" and "extensions.InstallTriggerImpl.enabled", that are controlling the InstallTrigger and InstallTrigger’s methods availability).

Warning

Any other about:config preference names that are not listed explicitly in the AMRemoteSettings.RS_ENTRIES_MAP config is expected to be ignored, even if allowed by a new version of the collection’s JSONSchema (this is the expected behavior and prevents the introduction of unexpected behaviors on older Firefox versions that may not be expecting new settings groups that may be introduced in Firefox releases that followed it).

Any about:config preference with an unexpected value type is going to be ignored as well (look to the AMRemoteSettings.processEntries to confirm which preferences values types are already expected and handled accordingly).

AMRemoteSettings - Controlled Settings Groups

installTriggerDeprecation

Group of settings to control InstallTrigger deprecation (Bug 1754441)

• extensions.InstallTrigger.enabled (boolean), controls the availability of the InstallTrigger global:

  • Turning this to false will be hiding it completely

    Note

    Turning this off can potentially impact UA detection on website being using it to detect Firefox. The WebCompat team should be consulted before setting this to false by default in Nightly or across all Firefox >= 100 versions through the "addons-manager-settings" RemoteSettings collection).

• extensions.InstallTriggerImpl.enabled (boolean): controls the availability of the InstallTrigger methods:

  • Turning this to false will hide all the InstallTrigger implementation, preventing using it to trigger the addon install flow, while the InstallTrigger global will still exists but be set to null.

quarantinedDomains

Group of settings to control the list of quarantined domains (Bug 1832791)

• extensions.quarantinedDomains.list (string), controls the list of domains to be quarantined

  Note

  The WebExtensions and Add-ons Operations teams should be consulted before applying changes to the list of quarantined domains.

How to define new remotely controlled settings

Note

Please update the AMRemoteSettings - JSON Schema and UI Schema in this documentation page updated when the ones used on the RemoteSettings service side have been changed, and document new controlled settings in the section AMRemoteSettings - Controlled Settings Groups.

• Confirm that the AMRemoteSettings - JSON Schema and UI Schema included in this page are in sync with the one actually used on the RemoteSettings service side, and use it as the starting point to update it to include a new type on remotely controlled setting:

  • choose a new unique string for the group of settings to be used in the definitions and properties objects (any that isn’t already used in the existing JSON Schema definitions), possibly choosing a name that helps to understand what the purpose of the entry.

  • add a new JSONSchema for the new group of settings in the definitions property

    • each of the properties included in the new definition should be named after the name of the about:config pref being controlled, their types should match the type expected by the pref (e.g. "boolean" for a boolean preference).

    • make sure to add a description property to the definition and to each of the controlled preferences, which should describe what is the settings group controlling and what is the expected behavior on the values allowed.

• Add a new entry to "AMRemoteSettings.RS_ENTRIES_MAP" with the choosen "id" as its key and the array of the about:config preferences names are its value.

• If the value type of a controlled preference isn’t yet supported, the method AMRemoteSettings.processEntries has to be updated to handle the new value type (otherwise the preference value will be just ignored).

• Add a new test to cover the expected behaviors on the new remotely controlled settings, the following RemoteSettings documentation page provides some useful pointers: * https://firefox-source-docs.mozilla.org/services/settings/index.html#unit-tests

• Refer to the RemoteSettings docs for more details about managing the JSONSchema for the "main/addons-manager-settings" collection and how to test it interactively in a Firefox instance: * https://remote-settings.readthedocs.io/en/latest/getting-started.html * https://firefox-source-docs.mozilla.org/services/settings/index.html#create-new-remote-settings * https://firefox-source-docs.mozilla.org/services/settings/index.html#remote-settings-dev-tools

AMRemoteSettings - JSON Schema

The entries part of the "addons-manager-settings" collection are validated using a JSON Schema structured as follows:

• The mandatory "id" property * defaults to “AddonManagerSettings” (which enforces only one entry in the collection as the preferred use case) * should NOT be changed unless there is a specific need to create separate collection entries which target or exclude specific Firefox versions. * when changed and multiple entries are created in this collection, it is advisable to:

  • set the id to a short string value that make easier to understand the purpose of the additional entry in the collection (eg. AddonManagerSettings-fx98-99 for an entry created that targets Firefox 98 and 99)

  • make sure only one applied to each targeted Firefox version ranges, or at least that each entry is controlling a different settings group

• Each supported group of controlled settings is described by its own property (e.g. "installTriggerDeprecation")

  • JSON Schema for each group of settings is defined in an entry of the "definitions" property.

  • The definition for each of the groups defined in the schema should be defined as a "oneOf" array including an entry of "type": "null" and "default"` set to ``null to omit the group of settings by default in new records.

  • In addition to the "type": "null" schema, each group of settings is expected to include in the "oneOf" array a second entry of "type": "object" and the controlled about:config preferences part of the group listed in the "properties".

{
  "type": "object",
  "required": ["id"],
  "properties": {
    "id": {
      "type": "string",
      "default": "AddonManagerSettings",
      "description": "The default id should NOT be changed, unless there is a specific need to create separate collection entries which target or exclude specific Firefox versions."
    },
    "filter_expression": {
      "type": "string",
      "optional": true,
      "description": "This is NOT directly used by AMRemoteSettings, but has special functionality in Remote Settings.\nSee https://remote-settings.readthedocs.io/en/latest/target-filters.html#how"
    },
    "quarantinedDomains": {
      "$ref": "#/definitions/quarantinedDomains",
      "optional": true
    },
    "installTriggerDeprecation": {
      "$ref": "#/definitions/installTriggerDeprecation",
      "optional": true
    }
  },
  "definitions": {
    "quarantinedDomains": {
      "oneOf": [
        {
          "type": "null",
          "title": "Omit quarantinedDomains settings"
        },
        {
          "type": "object",
          "title": "Include quarantinedDomains settings",
          "required": ["extensions.quarantinedDomains.list"],
          "properties": {
            "extensions.quarantinedDomains.list": {
              "type": "string",
              "default": "",
              "maxLength": 1048576,
              "description": "Set of domains to be quarantined separated by a comma (e.g. 'domain1.org,domain2.com'). NOTE: this pref value should be set to a ASCII encoded string and its size smaller than 1MB"
            }
          },
          "additionalProperties": false
        }
      ],
      "default": null,
      "description": "These settings provide a set of domain names to be quarantined (restricted by default to unverified extensions, which only the app or the user may grant back). IMPORTANT: The add-ons team should be consulted before introducing any new entry of this type."
    },
    "installTriggerDeprecation": {
      "oneOf": [
        {
          "type": "null",
          "title": "Omit installTriggerDeprecation settings"
        },
        {
          "type": "object",
          "title": "Include installTriggerDeprecation settings",
          "required": [
            "extensions.InstallTrigger.enabled",
            "extensions.InstallTriggerImpl.enabled"
          ],
          "properties": {
            "extensions.InstallTrigger.enabled": {
              "type": "boolean",
              "default": true,
              "optional": true,
              "description": "Show/Hide the InstallTrigger global completely (both the global and its methods will not be accessible anymore). IMPORTANT: The webcompat team should be consulted before turning this to false, because it may also potentially impact UA detection for some websites."
            },
            "extensions.InstallTriggerImpl.enabled": {
              "type": "boolean",
              "default": false,
              "optional": true,
              "description": "Show/Hide the InstallTrigger methods. The InstallTrigger global will remain visible but set to null."
            }
          },
          "additionalProperties": false
        }
      ],
      "default": null,
      "description": "These settings control the visibility of the InstallTrigger global and its methods."
    }
  }
}

UI Schema

In addition to the JSON Schema, a separate json called "UI schema" is associated to the "addons-manager-settings" collection, and it can be used to customize the form auto-generated based on the JSONSchema data.

Note

Extending this schema is only needed if it can help to make the RemoteSettings collection easier to manage and less error prone.

{
  "installTriggerDeprecation": {
    "extensions.InstallTrigger.enabled": {
      "ui:widget": "radio"
    },
    "extensions.InstallTriggerImpl.enabled": {
      "ui:widget": "radio"
    }
  }
}