MDN wants to talk to developers like you: https://qsurvey.mozilla.com/s3/8d22564490d8

set()

Use BrowserSetting.set() to change the browser setting to a new value.

There are some rules that can restrict when add-ons are able to change settings:

  • some settings are locked, so they can't be changed by add-ons at all
  • if multiple add-ons try to modify the same setting, then add-ons are given a precedence ordering based on when they were installed. More-recently installed add-ons have precedence over less-recently installed add-ons.

This means that if add-on X tries to change a setting:

  1. If the setting is locked, then the setting is not changed. However, X's change is remembered, and it is stored in a queue, ordered by X's precedence relative to any other add-ons that tried to change the setting. If the setting becomes unlocked later on, the first add-on in the queue gets to change the setting.
  2. Otherwise, if no other add-on has already changed the setting, then X succeeds in changing the setting, and is then said to "control" the setting.
  3. Otherwise, if a lower-precedence add-on Y has already changed the setting, then X succeeds in changing the setting, and now controls the setting. However, Y's change is remembered, and is stored in a queue in precedence order. If X subsequently clears its value, or if X is disabled or uninstalled,  the first add-on in the queue gets to make its change to the setting.
  4. Otherwise, if a higher-precedence add-on Z has already changed the setting, then X does not succeed in changing the setting, but its change is queued. If Z subsequently clears its value, or if Z is disabled or uninstalled, the first add-on in the queue gets to make its change to the setting.

An add-on can find out which of these scenarios applies by examining the "levelOfControl" property returned from a call to BrowserSetting.get().

The BrowserSetting.set() method returns a Promise that resolves to a boolean: if an attempt to change a setting actually results in the setting being changed (scenarios 2 and 3 above) the boolean is true: otherwise it is false.

Syntax

var setting = setting.set(
  details     // object
)

Parameters

details
An object that must contain the following property:
value
any. The value you want to change the setting to. Its type depends on the particular setting.

Return value

A Promise that will be fulfilled with a boolean: true if the setting was modified, false otherwise (for example, because the add-on did not control the setting).

Browser compatibility

See types.BrowserSetting.

Example

Modify the hyperlinkAuditingEnabled setting:

function onSet(result) {
  if (result) {
    console.log("Value was updated");
  } else {
    console.log("Value was not updated");
  }
}

browser.browserAction.onClicked.addListener(() => {

    var setting = browser.privacy.websites.hyperlinkAuditingEnabled.set({
      value: false
    });
    setting.then(onSet);

});

Acknowledgements

This API is based on Chromium's chrome.types API.

Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.

Document Tags and Contributors

 Contributors to this page: wbamberg, jwhitlock
 Last updated by: wbamberg,