declarativeNetRequest - Mozilla

declarativeNetRequest
=====================

This API enables extensions to specify conditions and actions that describe how network requests should be handled. These declarative rules enable the browser to evaluate and modify network requests without notifying extensions about individual network requests.

Permissions
-----------

To use this API, an extension must request the `"declarativeNetRequest"` or `"declarativeNetRequestWithHostAccess"` permission in its `manifest.json` file.

The `"declarativeNetRequest"` permission allows extensions to block and upgrade requests without any host permissions. Host permissions are required if the extension wants to redirect requests or modify headers on requests or when the `"declarativeNetRequestWithHostAccess"` permission is used instead of the `"declarativeNetRequest"` permission. To act on requests in these cases, host permissions are required for the request URL. For all requests, except for navigation requests (i.e., resource type `main_frame` and `sub_frame`), host permissions are also required for the request's initiator. The initiator of a request is usually the document or worker that triggered the request.

Some requests are restricted and cannot be matched by extensions. These include privileged browser requests, requests to or from restricted domains, and requests from other extensions.

The `"declarativeNetRequestFeedback"` permission is required to use `getMatchedRules` and `onRuleMatchedDebug` as they return information on declarative rules matched. See Testing for more information.

Rules
-----

The declarative rules are defined by four fields:

* `id` – An ID that uniquely identifies a rule within a ruleset. Mandatory and should be >= 1.
* `priority` – The rule priority. When specified, it should be >= 1. Defaults to 1. See Matching precedents for details on how priority affects which rules are applied.
* `condition` – The `condition` under which this rule is triggered.
* `action` – The `action` to take when the rule is matched. Rules can do one of these things:
    + block a network request.
    + redirect a network request.
    + modify headers from a network request.
    + prevent another matching rule from being applied.

**Note:**
 A redirect action does not redirect the request, and the request continues as usual when:

* the action does not change the request.
* the redirect URL is invalid (e.g., the value of `redirect.regexSubstitution` is not a valid URL).

This is an example rule that blocks all script requests originating from `"foo.com"` to any URL with `"abc"` as a substring:

```json
{
  "id": 1,
  "priority": 1,
  "action": { "type": "block" },
  "condition": {
    "urlFilter": "abc",
    "initiatorDomains": ["foo.com"],
    "resourceTypes": ["script"]
  }
}
```

The `urlFilter` field of a rule condition is used to specify the pattern matched against the request URL. See `RuleCondition` for details. Some examples of URL filters are:

| `urlFilter` | Matches | Does not match |
| --- | --- | --- |
| `"abc"` | https://abcd.comhttps://example.com/abcd | https://ab.com |
| `"abc*d"` | https://abcd.comhttps://example.com/abcxyzd | https://abc.com |
| `"||a.example.com"` | https://a.example.com/https://b.a.example.com/xyz | https://example.com/ |
| `"|https*"` | https://example.com | http://example.com/http://https.com |

Rulesets
--------

Rules are organized into rulesets:

* **static rulesets**: collections of rules defined with the `"declarative_net_request"` manifest key and stored in the extension. An extension can enable and disable static rulesets using `updateEnabledRulesets`. The set of enabled static rulesets is persisted across sessions but not across extension updates. The static rulesets enabled on extension installation and update are determined by the content of the `"declarative_net_request"` manifest key.
* **dynamic ruleset**: rules added or removed using `updateDynamicRules`. These rules persist across sessions and extension updates.
* **session ruleset**: rules added or removed using `updateSessionRules`. These rules do not persist across browser sessions.

**Note:**
 Errors and warnings about invalid static rules are only displayed during testing. Invalid static rules in permanently installed extensions are ignored. Therefore, it's important to verify that your static rulesets are valid by testing.

Limits
------

### Static ruleset limits

An extension can:

* specify static rulesets as part of the `"declarative_net_request"` manifest key up to the value of `MAX_NUMBER_OF_STATIC_RULESETS`.
* enable static rulesets up to at least the value of `GUARANTEED_MINIMUM_STATIC_RULES`, and the number of enabled static rulesets must not exceed the value of `MAX_NUMBER_OF_ENABLED_STATIC_RULESETS`. In addition, the number of rules in enabled static rulesets for all extensions must not exceed the global limit. Extensions shouldn't depend on the global limit having a specific value and should instead use `getAvailableStaticRuleCount` to find the number of additional rules they can enable.
### Dynamic and session-scoped rules

The number of dynamic and session-scoped rules an extension can add is limited to the value of `MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES`.

Matching precedents
-------------------

When the browser evaluates how to handle requests, it checks each extension's rules that have a condition that matches the request and chooses the one to consider applying as follows:

1. the rule priority, where 1 is the lowest priority (and rules default to 1 where priority is not set).
If this doesn't result in one rule to apply:
2. the rule action, in the following order of precedence:
    1. "allow" which means any other remaining rules are ignored.
    2. "allowAllRequests" (for main\_frame and sub\_frame resourceTypes only) has the same effect as allow but also applies to future subresource loads in the document (including descendant frames) generated from the request.
    3. "block" cancels the request.
    4. "upgradeScheme" upgrades the scheme of the request.
    5. "redirect" redirects the request.
    6. "modifyHeaders" rewrites request or response headers or both.

**Note:** When multiple matching rules have the same rule priority and rule action type, the outcome can be ambiguous when the matched action support additional properties. These properties can result in outcomes that cannot be combined. For example:

* The "block" action does not support additional properties, and therefore there is no ambiguity: all matching "block" actions would result in the same outcome.
* The "redirect" action redirects a request to one destination. When multiple "redirect" actions match, all but one "redirect" action is ignored. It is still possible to redirect repeatedly when the redirected request matches another rule condition.
* Multiple "modifyHeaders" actions can be applied independently when they touch different headers. The result is ambiguous when they touch the same header, because some combination of operations are not allowed (as explained at `declarativeNetRequest.ModifyHeaderInfo`). The evaluation order of "modifyHeaders" actions is therefore important.

To control the order in which actions are applied, assign distinct `priority` values to rules whose order of precedence is important.

**Note:** After rule priority and rule action, Firefox considers the ruleset the rule belongs to, in this order of precedence: session > dynamic > session rulesets.
 This cannot be relied upon across browsers, see WECG issue 280.

If only one extension provides a rule for the request, that rule is applied. However, where more than one extension has a matching rule, the browser chooses the one to apply in this order of precedence:

1. "block"
2. "redirect" and "upgradeScheme"
3. "allow" and "allowAllRequests"

If the request was not blocked or redirected, the matching `modifyHeaders` actions are applied, as documented in `declarativeNetRequest.ModifyHeaderInfo`.

Testing
-------

`testMatchOutcome`, `getMatchedRules`, and `onRuleMatchedDebug` are available to assist with testing rules and rulesets. These APIs require the `"declarativeNetRequestFeedback"` permissions. In addition:

* in Chrome, these APIs are only available to unpacked extensions.
* in Firefox, these APIs are only available after setting the `extensions.dnr.feedback` preference to `true`. Set this preference using `about:config` or the `--pref` flag of the `web-ext` CLI tool.
Comparison with the webRequest API
----------------------------------

* The declarativeNetRequest API evaluates network requests in the browser itself. This makes it more performant than the webRequest API, where each network request is evaluated in JavaScript in the extension process.
* Because the requests are not intercepted by the extension process, declarativeNetRequest removes the need for extensions to have a background page.
* Unlike the webRequest API, blocking or upgrading requests using the declarativeNetRequest API requires no host permissions when used with the `declarativeNetRequest` permission.
* The declarativeNetRequest API provides better privacy to users because extensions do not read the network requests made on the user's behalf.
* (Chrome only:) Unlike the webRequest API, any images or iframes blocked using the declarativeNetRequest API are automatically collapsed in the DOM.
* While deciding whether a request is to be blocked or redirected, the declarativeNetRequest API is given priority over the webRequest API because it allows for synchronous interception. Similarly, any headers removed through declarativeNetRequest API are not made visible to web request extensions.
* The webRequest API is more flexible than the declarativeNetRequest API because it allows extensions to evaluate a request programmatically.
Types
-----

`declarativeNetRequest.MatchedRule`

Details of a matched rule.

`declarativeNetRequest.ModifyHeaderInfo`

The request or response headers to modify for the request.

`declarativeNetRequest.Redirect`

Details of how the redirect should be performed. Only valid for redirect rules.

`declarativeNetRequest.ResourceType`

The resource type of a request.

`declarativeNetRequest.Rule`

An object containing details of a rule.

`declarativeNetRequest.RuleAction`

An object defining the action to take if a rule is matched.

`declarativeNetRequest.RuleCondition`

An object defining the condition under which a rule is triggered.

`declarativeNetRequest.URLTransform`

An object containing details of a URL transformation to perform for a redirect action.

Properties
----------

`declarativeNetRequest.DYNAMIC_RULESET_ID`

Ruleset ID for the dynamic rules added by the extension.

`declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL`

The time interval within which `declarativeNetRequest.MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL` `declarativeNetRequest.getMatchedRules` calls can be made.

`declarativeNetRequest.GUARANTEED_MINIMUM_STATIC_RULES`

The minimum number of static rules guaranteed to an extension across its enabled static rulesets.

`declarativeNetRequest.MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL`

The number of times `declarativeNetRequest.getMatchedRules` can be called within a period of `declarativeNetRequest.GETMATCHEDRULES_QUOTA_INTERVAL`.

`declarativeNetRequest.MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES`

The maximum number of combined dynamic and session scoped rules an extension can add.

`declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS`

The maximum number of static rulesets an extension can enable.

`declarativeNetRequest.MAX_NUMBER_OF_REGEX_RULES`

The maximum number of regular expression rules that an extension can add.

`declarativeNetRequest.MAX_NUMBER_OF_STATIC_RULESETS`

The maximum number of static rulesets an extension can specify as part of the `declarative_net_request.rule_resources` manifest key.

`declarativeNetRequest.SESSION_RULESET_ID`

The ruleset ID for the session-scoped rules added by the extension.

Functions
---------

`declarativeNetRequest.getAvailableStaticRuleCount()`

Returns the number of static rules an extension can enable before the global static rule limit is reached.

`declarativeNetRequest.getDynamicRules()`

Returns the set of dynamic rules for the extension.

`declarativeNetRequest.getEnabledRulesets()`

Returns the IDs for the set of enabled static rulesets.

`declarativeNetRequest.getMatchedRules()`

Returns all the rules matched for the extension.

`declarativeNetRequest.getSessionRules()`

Returns the set of session scoped rules for the extension.

`declarativeNetRequest.isRegexSupported()`

Checks if a regular expression is supported as a `declarativeNetRequest.RuleCondition``.regexFilter` rule condition.

`declarativeNetRequest.setExtensionActionOptions()`

Configures how the action count for tabs are handled.

`declarativeNetRequest.testMatchOutcome()`

Checks if any of the extension's `declarativeNetRequest` rules would match a hypothetical request.

`declarativeNetRequest.updateDynamicRules()`

Modifies the active set of dynamic rules for the extension.

`declarativeNetRequest.updateEnabledRulesets()`

Updates the set of active static rulesets for the extension.

`declarativeNetRequest.updateSessionRules()`

Modifies the set of session scoped rules for the extension.

Events
------

`declarativeNetRequest.onRuleMatchedDebug`

Fired when a rule is matched with a request when debugging an extension with the "declarativeNetRequestFeedback" permission.

Example extensions
------------------

* dnr-block-only
* dnr-dynamic-with-options
* dnr-redirect-url
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


idle - Mozilla

idle
====

Find out when the user's system is idle, locked, or active.

To use this API you need to have the "idle" permission.

Types
-----

`idle.IdleState`

String describing the device's idle state.

Functions
---------

`idle.queryState()`

Returns `"locked"` if the system is locked, `"idle"` if the user has not generated any input for a specified number of seconds, or `"active"` otherwise.

`idle.setDetectionInterval()`

Sets the interval used to determine when the system is in an idle state for `idle.onStateChanged` events.

Events
------

`idle.onStateChanged`

Fired when the system changes state.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.idle` API. This documentation is derived from `idle.json` in the Chromium code.


webRequest - Mozilla

webRequest
==========

Add event listeners for the various stages of making an HTTP request, which includes websocket requests on `ws://` and `wss://`. The event listener receives detailed information about the request and can modify or cancel the request.

Each event is fired at a particular stage of the request. The typical sequence of events is like this:

![Order of requests is onBeforeRequest, onBeforeSendHeader, onSendHeaders, onHeadersReceived, onResponseStarted, and onCompleted. The onHeadersReceived can cause an onBeforeRedirect and an onAuthRequired. Events caused by onHeadersReceived start at the beginning onBeforeRequest. Events caused by onAuthRequired start at onBeforeSendHeader.](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/webRequest/webrequest-flow.png)

`onErrorOccurred` can fire at any time during the request. Also, note that sometimes the sequence of events may differ from this. For example, in Firefox, on an HSTS upgrade, the `onBeforeRedirect` event is triggered immediately after `onBeforeRequest`. `onErrorOccurred` is also fired if Firefox Tracking Protection blocks a request.

All events – *except* `onErrorOccurred` – can take three arguments to `addListener()`:

* the listener itself
* a `filter` object, so you can only be notified for requests made to particular URLs or for particular types of resource
* an optional `extraInfoSpec` object. You can use this to pass additional event-specific instructions.

The listener function is passed a `details` object containing information about the request. This includes a request ID, which is provided to enable an add-on to correlate events associated with a single request. It is unique within a browser session and the add-on's context. It stays the same throughout a request, even across redirections and authentication exchanges.

To use the `webRequest` API for a given host, an extension must have the `"webRequest"` API permission and the host permission for that host. To use the `"blocking"` feature, the extension must also have the `"webRequestBlocking"` API permission.

To intercept resources loaded by a page (such as images, scripts, or stylesheets), the extension must have the host permission for the resource as well as for the main page requesting the resource. For example, if a page at `https://developer.mozilla.org` loads an image from `https://mdn.mozillademos.org`, then an extension must have both host permissions if it is to intercept the image request.

Modifying requests
------------------

On some of these events, you can modify the request. Specifically, you can:

* cancel the request in:
    + `onBeforeRequest`
    + `onBeforeSendHeaders`
    + `onAuthRequired`
* redirect the request in:
    + `onBeforeRequest`
    + `onHeadersReceived`
* modify request headers in:
    + `onBeforeSendHeaders`
* modify response headers in:
    + `onHeadersReceived`
* supply authentication credentials in:
    + `onAuthRequired`

To do this, you need to pass an option with the value `"blocking"` in the `extraInfoSpec` argument to the event's `addListener()`. This makes the listener synchronous.

In the listener, you can then return a `BlockingResponse` object, which indicates the modification you need to make: for example, the modified request header you want to send.

Requests at browser startup
---------------------------

When a listener is registered with the `"blocking"` option and is registered during the extension startup, if a request is made during the browser startup that matches the listener the extension starts early. This enables the extension to observe the request at browser startup. If you don't take these steps, requests made at startup could be missed.

Speculative requests
--------------------

The browser can make speculative connections, where it determines that a request to a URI may be coming soon. This type of connection does not provide valid tab information, so request details such as `tabId`, `frameId`, `parentFrameId`, etc. are inaccurate. These connections have a `webRequest.ResourceType` of `speculative`.

Accessing security information
------------------------------

In the `onHeadersReceived` listener you can access the TLS properties of a request by calling `getSecurityInfo()`. To do this you must also pass "blocking" in the `extraInfoSpec` argument to the event's `addListener()`.

You can read details of the TLS handshake, but can't modify them or override the browser's trust decisions.

Modifying responses
-------------------

To modify the HTTP response bodies for a request, call `webRequest.filterResponseData`, passing it the ID of the request. This returns a `webRequest.StreamFilter` object that you can use to examine and modify the data as it is received by the browser.

To do this, you must have the `"webRequestBlocking"` API permission as well as the `"webRequest"` API permission and the host permission for the relevant host.

Types
-----

`webRequest.BlockingResponse`

An object of this type is returned by event listeners that have set `"blocking"` in their `extraInfoSpec` argument. By setting particular properties in `BlockingResponse`, the listener can modify network requests.

`webRequest.CertificateInfo`

An object describing a single X.509 certificate.

`webRequest.HttpHeaders`

An array of HTTP headers. Each header is represented as an object with two properties: `name` and either `value` or `binaryValue`.

`webRequest.RequestFilter`

An object describing filters to apply to `webRequest` events.

`webRequest.ResourceType`

Represents a particular kind of resource fetched in a web request.

`webRequest.SecurityInfo`

An object describing the security properties of a particular web request.

`webRequest.StreamFilter`

An object that can be used to monitor and modify HTTP responses while they are being received.

`webRequest.UploadData`

Contains data uploaded in a URL request.

Properties
----------

`webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES`

The maximum number of times that `handlerBehaviorChanged()` can be called in a 10 minute period.

Methods
-------

`webRequest.handlerBehaviorChanged()`

This method can be used to ensure that event listeners are applied correctly when pages are in the browser's in-memory cache.

`webRequest.filterResponseData()`

Returns a `webRequest.StreamFilter` object for a given request.

`webRequest.getSecurityInfo()`

Gets detailed information about the TLS connection associated with a given request.

Events
------

`webRequest.onBeforeRequest`

Fired when a request is about to be made, and before headers are available. This is a good place to listen if you want to cancel or redirect the request.

`webRequest.onBeforeSendHeaders`

Fired before sending any HTTP data, but after HTTP headers are available. This is a good place to listen if you want to modify HTTP request headers.

`webRequest.onSendHeaders`

Fired just before sending headers. If your add-on or some other add-on modified headers in ``onBeforeSendHeaders``, you'll see the modified version here.

`webRequest.onHeadersReceived`

Fired when the HTTP response headers associated with a request have been received. You can use this event to modify HTTP response headers.

`webRequest.onAuthRequired`

Fired when the server asks the client to provide authentication credentials. The listener can do nothing, cancel the request, or supply authentication credentials.

`webRequest.onResponseStarted`

Fired when the first byte of the response body is received. For HTTP requests, this means that the status line and response headers are available.

`webRequest.onBeforeRedirect`

Fired when a server-initiated redirect is about to occur.

`webRequest.onCompleted`

Fired when a request is completed.

`webRequest.onErrorOccurred`

Fired when an error occurs.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Additional notes on Chrome incompatibilities.

Example extensions
------------------

* http-response
* root-cert-stats
* stored-credentials
* user-agent-rewriter

**Note:** This API is based on Chromium's `chrome.webRequest` API. This documentation is derived from `web_request.json` in the Chromium code.


history - Mozilla

history
=======

Use the `history` API to interact with the browser history.

If you are looking for information about the browser session history, see the History interface.

**Note:** Downloads are treated as `HistoryItem` objects. Therefore, events such as `history.onVisited` fire for downloads.

Browser history is a chronological record of pages the user has visited. The history API enables you to:

* search for pages that appear in the browser history
* remove individual pages from the browser history
* add pages to the browser history
* remove all pages from the browser history.

However, the user may have visited a single page multiple times, so the API also has the concept of "visits". So you can also use this API to:

* retrieve the complete set of visits the user made to a particular page
* remove visits to any pages made during a given time period.

To use this API, an extension must request the "history" permission in its `manifest.json` file.

Types
-----

`history.TransitionType`

Describes how the browser navigated to a particular page.

`history.HistoryItem`

Provides information about a particular page in the browser history.

`history.VisitItem`

Describes a single visit to a page.

Functions
---------

`history.search()`

Searches the browser history for `history.HistoryItem` objects matching the given criteria.

`history.getVisits()`

Retrieves information about visits to a given page.

`history.addUrl()`

Adds a record to the browser history of a visit to the given page.

`history.deleteUrl()`

Removes all visits to the given URL from the browser history.

`history.deleteRange()`

Removes all visits to pages that the user made during the given time range.

`history.deleteAll()`

Removes all visits from the browser history.

Events
------

`history.onTitleChanged`

Fired when the title of a page visited by the user is recorded.

`history.onVisited`

Fired each time the user visits a page, providing the `history.HistoryItem` data for that page.

`history.onVisitRemoved`

Fired when a URL is removed completely from the browser history.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Example extensions
------------------

* history-deleter

**Note:** This API is based on Chromium's `chrome.history` API. This documentation is derived from `history.json` in the Chromium code.


theme - Mozilla

theme
=====

Enables browser extensions to get details of the browser's theme and update the theme.

You can use this API to include a theme in your extension, which you define as a `theme.Theme` and apply using `theme.update()`. You cannot include a static theme in your extension, defined with the "theme" manifest key. The "theme" manifest key is used to define static themes only. See Themes on Extension Workshop for more information.

Types
-----

`theme.Theme`

Represents the content of a theme.

Functions
---------

`theme.getCurrent()`

Gets the current browser theme.

`theme.update()`

Updates the browser's theme.

`theme.reset()`

Removes any theme updates made in a call to `theme.update()`.

Events
------

`theme.onUpdated`

Fired when the browser theme changes.

Example extensions
------------------

* dynamic-theme
* private-browsing-theme
* theme-integrated-sidebar
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


action - Mozilla

action
======

Adds a button to the browser's toolbar.

**Note:** This API is available in Manifest V3 or higher. It replaces the Manifest V2 APIs `browserAction` and, in Chrome and Safari, `pageAction`.

A browser action is a button in the browser's toolbar.

You can associate a popup with the button. Like a web page, the popup is specified using HTML, CSS, and JavaScript. JavaScript running in the popup gets access to all the same WebExtension APIs as your background scripts, but its global context is the popup, not the current page displayed in the browser. To affect web pages, you need to communicate with them via messages.

If you specify a popup, it is shown — and the content loaded — when the user clicks the icon. If you do not specify a popup, an event is dispatched to your extension when the user clicks the icon.

The button also has a context menu, and you can add items to this menu with the `menus` API using the `action` `menus.ContextType`.

You can define most of a browser action's properties declaratively using the `action` key in the manifest.json.

With the `action` API, you can:

* use `action.onClicked` to listen for clicks on the icon.
* get and set the icon's properties — icon, title, popup, and so on. You can get and set these globally across all tabs or for a tab by passing the tab ID as an additional argument.
Types
-----

`action.ColorArray`

An array of four integers in the range 0-255 defining an RGBA color.

`action.ImageDataType`

Pixel data for an image. Must be an `ImageData` object (for example, from a `<canvas>` element).

Functions
---------

`action.setTitle()`

Sets the browser action's title. This will be displayed in a tooltip.

`action.getTitle()`

Gets the browser action's title.

`action.setIcon()`

Sets the browser action's icon.

`action.setPopup()`

Sets the HTML document to be opened as a popup when the user clicks on the browser action's icon.

`action.getPopup()`

Gets the HTML document set as the browser action's popup.

`action.openPopup()`

Open the browser action's popup.

`action.setBadgeText()`

Sets the browser action's badge text. The badge is displayed on top of the icon.

`action.getBadgeText()`

Gets the browser action's badge text.

`action.setBadgeBackgroundColor()`

Sets the badge's background color.

`action.getBadgeBackgroundColor()`

Gets the badge's background color.

`action.setBadgeTextColor()`

Sets the badge's text color.

`action.getBadgeTextColor()`

Gets the badge's text color.

`action.getUserSettings()`

Gets the user-specified settings for the browser action.

`action.enable()`

Enables the browser action for a tab. By default, browser actions are enabled for all tabs.

`action.disable()`

Disables the browser action for a tab, meaning that it cannot be clicked when that tab is active.

`action.isEnabled()`

Checks whether the browser action is enabled or not.

Events
------

`action.onClicked`

Fired when a browser action icon is clicked. This event will not fire if the browser action has a popup.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.action` API. This documentation is derived from `action.json` in the Chromium code.


downloads - Mozilla

downloads
=========

Enables extensions to interact with the browser's download manager. You can use this API module to download files, cancel, pause, resume downloads, and show downloaded files in the file manager.

To use this API you need to have the "downloads" API permission specified in your manifest.json file.

Types
-----

`downloads.FilenameConflictAction`

Defines options for what to do if the name of a downloaded file conflicts with an existing file.

`downloads.InterruptReason`

Defines a set of possible reasons why a download was interrupted.

`downloads.DangerType`

Defines a set of common warnings of possible dangers associated with downloadable files.

`downloads.State`

Defines different states that a current download can be in.

`downloads.DownloadItem`

Represents a downloaded file.

`downloads.StringDelta`

Represents the difference between two strings.

`downloads.DoubleDelta`

Represents the difference between two doubles.

`downloads.BooleanDelta`

Represents the difference between two booleans.

`downloads.DownloadTime`

Represents the time a download took to complete.

`downloads.DownloadQuery`

Defines a set of parameters that can be used to search the downloads manager for a specific set of downloads.

Functions
---------

`downloads.download()`

Downloads a file, given its URL and other optional preferences.

`downloads.search()`

Queries the `DownloadItems` available in the browser's downloads manager, and returns those that match the specified search criteria.

`downloads.pause()`

Pauses a download.

`downloads.resume()`

Resumes a paused download.

`downloads.cancel()`

Cancels a download.

`downloads.getFileIcon()`

Retrieves an icon for the specified download.

`downloads.open()`

Opens the downloaded file with its associated application.

`downloads.show()`

Opens the platform's file manager application to show the downloaded file in its containing folder.

`downloads.showDefaultFolder()`

Opens the platform's file manager application to show the default downloads folder.

`downloads.erase()`

Erases matching `DownloadItems` from the browser's download history, without deleting the downloaded files from disk.

`downloads.removeFile()`

Removes a downloaded file from disk, but not from the browser's download history.

`downloads.acceptDanger()`

Prompts the user to accept or cancel a dangerous download.

`downloads.setShelfEnabled()`

Enables or disables the gray shelf at the bottom of every window associated with the current browser profile. The shelf will be disabled as long as at least one extension has disabled it.

Events
------

`downloads.onCreated`

Fires with the `DownloadItem` object when a download begins.

`downloads.onErased`

Fires with the `downloadId` when a download is erased from history.

`downloads.onChanged`

When any of a `DownloadItem`'s properties except `bytesReceived` changes, this event fires with the `downloadId` and an object containing the properties that changed.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Example extensions
------------------

* latest-download

**Note:** This API is based on Chromium's `chrome.downloads` API.


pkcs11 - Mozilla

pkcs11
======

The `pkcs11` API enables an extension to enumerate PKCS #11 security modules and to make them accessible to the browser as sources of keys and certificates.

To use this API you need to have the "pkcs11" permission.

Using the Firefox Preferences Dialog to Install PKCS #11 Modules
----------------------------------------------------------------

Perform the following steps:

1. Save the PKCS #11 module to a permanent location on your local computer
2. Select **Tools > Options** or select the **Firefox menu** and then **Options**
3. Once the Options page opens, select **Privacy & Security**
4. Scroll down to the bottom of the page and under **Certificates** click or tap on **Security Devices…**
![Security modules and devices](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/pkcs11/device_manager.png)
5. Click or tap the **Load** button

 ![Load PKCS#11 device driver](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/pkcs11/load_device_driver.png)
6. Enter a name for the security module, such as "*My Client Database*"

**Warning:** Be careful about using international characters as there is currently a bug in Firefox where international characters may cause problems.
7. Choose **Browse…** to find the location of the PKCS #11 module on your local computer, and then click or tap **OK** to confirm.
Provisioning PKCS #11 modules
-----------------------------

**Note:** Starting with Firefox 58, extensions can use this API to enumerate PKCS #11 modules and make them accessible to the browser as sources of keys and certificates.

There are two environmental prerequisites for using this **API**:

* One or more `PKCS #11` modules must be installed on the user's computer
* For each installed `PKCS #11` module, there must be a native manifest file that enables the browser to locate the module.

Most probably, the user or device administrator would install the `PKCS #11` module, and its installer would install the native manifest file at the same time.

However, the module and manifest can't be installed as part of the extension's own installation process.

For details about the manifest file's contents and location, see Native manifests.

Functions
---------

`pkcs11.getModuleSlots()`

For each slot in a module, get its name and whether it contains a token.

`pkcs11.installModule()`

Installs the named PKCS #11 module.

`pkcs11.isModuleInstalled()`

Checks whether the named PKCS #11 module is installed.

`pkcs11.uninstallModule()`

Uninstalls the named PKCS #11 module.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


omnibox - Mozilla

omnibox
=======

Enables extensions to implement customized behavior when the user types into the browser's address bar.

When the user focuses the browser's address bar and starts typing, the browser displays a drop-down list containing suggested pages based on what they typed. This gives the user a quick way to access, for example, pages from their history or bookmarks.

The omnibox API provides the extension a way to customize the suggestions displayed in the drop-down, when the user enters a keyword defined by the extension. It works as follows:

1. First, the extension must include an "omnibox" key in its manifest.json file, which defines a keyword.
2. When the user focuses the address bar and types the keyword followed by a space, the extension gets an `omnibox.onInputStarted` event.
3. Optionally, the extension can call `omnibox.setDefaultSuggestion()` to define the first suggestion displayed in the address bar drop-down.
4. As the user continues to type characters, the extension gets `omnibox.onInputChanged` events. The event listener is passed the value the user has typed and can populate the address bar drop-down with suggestions. If the extension sets a default suggestion using `omnibox.setDefaultSuggestion()`, this suggestion is displayed first in the drop-down.
5. If the user accepts a suggestion, the extension gets an `omnibox.onInputEntered` event. The event listener is passed the accepted suggestion.
6. If the user deletes a suggestion, the extension gets an `omnibox.onDeleteSuggestion` event.
7. If the user dismisses the drop-down, the extension gets an `omnibox.onInputCancelled` event.
Types
-----

`omnibox.OnInputEnteredDisposition`

Describes the recommended method to handle the selected suggestion: open in the current tab, open in a new foreground tab, or open in a new background tab.

`omnibox.SuggestResult`

An object representing a suggestion to add to the address bar drop-down.

Functions
---------

`omnibox.setDefaultSuggestion()`

Defines the first suggestion displayed in the drop-down when the user enters your extension's keyword followed by a space.

Events
------

`omnibox.onDeleteSuggestion`

Fired whenever the user deletes a suggestion.

`omnibox.onInputStarted`

Fired when the user focuses the address bar and types your extension's omnibox keyword, followed by a space.

`omnibox.onInputChanged`

Fired whenever the user's input changes after they have focused the address bar and typed your extension's keyword followed by a space.

`omnibox.onInputEntered`

Fired when the user accepts one of your extension's suggestions.

`omnibox.onInputCancelled`

Fired when the user dismisses the address bar drop-down after they have focused the address bar and typed your extension's keyword followed by a space.

Example extensions
------------------

* firefox-code-search
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.omnibox` API.


captivePortal - Mozilla

captivePortal
=============

Determine the captive portal state of the user's connection. A captive portal is a web page displayed when a user first connects to a Wi-Fi network. The user provides information or acts on the captive portal web page to gain broader access to network resources, such as accepting terms and conditions or making a payment.

To use this API you need to have the "captivePortal" permission.

Properties
----------

`captivePortal.canonicalURL`

Return the canonical URL of the captive-portal detection page. Read-only.

Functions
---------

`captivePortal.getLastChecked()`

Returns the time, in milliseconds, since the last request was completed.

`captivePortal.getState()`

Returns the portal state as one of `unknown`, `not_captive`, `unlocked_portal`, or `locked_portal`.

Events
------

`captivePortal.onConnectivityAvailable`

Fires when the captive portal service determines that the user can connect to the internet.

`captivePortal.onStateChanged`

Fires when the captive portal state changes.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


browsingData - Mozilla

browsingData
============

Enables extensions to clear the data that is accumulated while the user is browsing.

In the `browsingData` API, browsing data is divided into types:

* browser cache
* cookies
* downloads
* history
* local storage
* plugin data
* saved form data
* saved passwords

You can use the `browsingData.remove()` function to remove any combination of these types. There are also dedicated functions to remove each particular type of data, such as `removePasswords()`, `removeHistory()` and so on.

All the `browsingData.remove[X]()` functions take a `browsingData.RemovalOptions` object, which you can use to control two further aspects of data removal:

* how far back in time to remove data
* whether to remove data only from normal web pages, or also from hosted web apps and add-ons. Note that this option is not yet supported in Firefox.

Finally, this API gives you a `browsingData.settings()` function that gives you the current value of the settings for the browser's built-in "Clear History" feature.

To use this API you must have the "browsingData" API permission.

Types
-----

`browsingData.DataTypeSet`

Object used to specify the type of data to remove: for example, history, downloads, passwords, and so on.

`browsingData.RemovalOptions`

Object used to specify how far back in time to remove data, and whether to remove data added through normal web browsing, by hosted apps, or by add-ons.

Methods
-------

`browsingData.remove()`

Removes browsing data for the data types specified.

`browsingData.removeCache()`

Clears the browser's cache.

`browsingData.removeCookies()`

Removes cookies.

`browsingData.removeDownloads()`

Removes the list of downloaded files.

`browsingData.removeFormData()`

Clears saved form data.

`browsingData.removeHistory()`

Clears the browser's history.

`browsingData.removeLocalStorage()`

Clears any local storage created by websites.

`browsingData.removePasswords()`

Clears saved passwords.

`browsingData.removePluginData()`

Clears data associated with plugins.

`browsingData.settings()`

Gets the current value of settings in the browser's "Clear History" feature.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Example extensions
------------------

* forget-it

**Note:** This API is based on Chromium's `chrome.browsingData` API.


commands - Mozilla

commands
========

Listen for the user executing commands that you have registered using the `commands` manifest.json key.

Types
-----

`commands.Command`

Object representing a command. This contains the information specified for the command in the `commands` manifest.json key.

Functions
---------

`commands.getAll`

Gets all registered commands for this extension.

`commands.reset`

Reset the given command's description and shortcut to the values given in the manifest key.

`commands.update`

Change the description or shortcut for the given command.

Events
------

`commands.onChanged`

Fired when the keyboard shortcut for a command is changed.

`commands.onCommand`

Fired when a command is executed using its associated keyboard shortcut.

Example extensions
------------------

* commands
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:**

This API is based on Chromium's `chrome.commands` API.


types - Mozilla

types
=====

Defines the `BrowserSetting` type, which is used to represent a browser setting.

Types
-----

`types.BrowserSetting`

Represents a browser setting.

Browser compatibility
---------------------

**Note:**

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


topSites - Mozilla

topSites
========

Use the topSites API to get an array containing pages that the user has visited frequently.

Browsers maintain this to help the user get back to these places easily. For example, Firefox by default provides a list of the most-visited pages in the "New Tab" page.

To use the topSites API you must have the "topSites" API permission.

Types
-----

`topSites.MostVisitedURL`

An object containing the title and URL of a website.

Methods
-------

`topSites.get()`

Gets an array containing all the sites listed in the browser's "New Tab" page. Note that the number of sites returned here is browser-specific, and the particular sites returned will probably be specific to the user, based on their browsing history.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Example extensions
------------------

* top-sites

**Note:** This API is based on Chromium's `chrome.topSites` API.


scripting - Mozilla

scripting
=========

Inserts JavaScript and CSS into websites. This API offers two approaches to inserting content:

* `scripting.executeScript()`, `scripting.insertCSS()`, and `scripting.removeCSS()` that provide for one-off injections.
* `scripting.registerContentScripts()` that registers content scripts dynamically, which can then be retrieved with `scripting.getRegisteredContentScripts()` and unregistered with `scripting.unregisterContentScripts()`).

**Note:** Chrome restricts this API to Manifest V3. Firefox and Safari support this API in Manifest V2 and V3.

This API requires the `"scripting"` permission and host permission for the target in the tab into which JavaScript or CSS is injected.

Alternatively, you can get permission temporarily in the active tab and only in response to an explicit user action, by asking for the `"activeTab"` permission. However, the `"scripting"` permission is still required.

Types
-----

`scripting.ContentScriptFilter`

Specifies the IDs of scripts to retrieve with `scripting.getRegisteredContentScripts()` or to unregister with `scripting.unregisterContentScripts()`.

`scripting.ExecutionWorld`

Specifies the execution environment of a script injected with `scripting.executeScript()` or registered with `scripting.registerContentScripts()`.

`scripting.InjectionTarget`

Details of an injection target.

`scripting.RegisteredContentScript`

Details of a content script to be registered or that is registered.

Functions
---------

`scripting.executeScript()`

Injects JavaScript code into a page.

`scripting.getRegisteredContentScripts()`

Gets a list of registered content scripts.

`scripting.insertCSS()`

Injects CSS into a page.

`scripting.registerContentScripts()`

Registers a content script for future page loads.

`scripting.removeCSS()`

Removes CSS which was previously injected into a page by a `scripting.insertCSS()` call.

`scripting.updateContentScripts()`

Updates one or more content scripts already registered.

`scripting.unregisterContentScripts()`

Unregisters one or more content scripts.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.scripting` API.


extensionTypes - Mozilla

extensionTypes
==============

Some common types used in other WebExtension APIs.

Types
-----

`extensionTypes.ImageDetails`

Details about the format and quality of an image.

`extensionTypes.ImageFormat`

The format of an image.

`extensionTypes.InjectDetails`

Injects details into a page.

`extensionTypes.RunAt`

The soonest that the JavaScript or CSS will be injected into the tab.

`extensionTypes.CSSOrigin`

Indicates whether a CSS stylesheet injected by `tabs.insertCSS` should be treated as an "author" or "user" stylesheet.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.extensionTypes` API. This documentation is derived from `extension_types.json` in the Chromium code.


management - Mozilla

management
==========

Get information about installed add-ons.

With the `management` API you can:

* get information about installed add-ons
* enable/disable add-ons
* uninstall add-ons
* find out which permission warnings are given for particular add-ons or manifests
* get notifications of add-ons being installed, uninstalled, enabled, or disabled.

Most of these operations require the "management" API permission. Operations that don't provide access to other add-ons don't require this permission.

Types
-----

`management.ExtensionInfo`

An object that contains information about an installed add-on.

Functions
---------

`management.getAll()`

Returns information about all installed add-ons.

`management.get()`

Returns information about a particular add-on, given its ID.

`management.getSelf()`

Returns information about the calling add-on.

`management.install()`

Installs a particular theme, given its URL at addons.mozilla.org.

`management.uninstall()`

Uninstalls a particular add-on, given its ID.

`management.uninstallSelf()`

Uninstalls the calling add-on.

`management.getPermissionWarningsById()`

Get the set of permission warnings for a particular add-on, given its ID.

`management.getPermissionWarningsByManifest()`

Get the set of permission warnings that would be displayed for the given manifest string.

`management.setEnabled()`

Enable/disable a particular add-on, given its ID.

Events
------

`management.onInstalled`

Fired when an add-on is installed.

`management.onUninstalled`

Fired when an add-on is uninstalled.

`management.onEnabled`

Fired when an add-on is enabled.

`management.onDisabled`

Fired when an add-on is disabled.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Example extensions
------------------

* theme-switcher

**Note:** This API is based on Chromium's `chrome.management` API. This documentation is derived from `management.json` in the Chromium code.


clipboard - Mozilla

clipboard
=========

The WebExtension `clipboard` API (which is different from the standard Clipboard API) enables an extension to copy items to the system clipboard. Currently the WebExtension `clipboard` API only supports copying images, but it's intended to support copying text and HTML in the future.

The WebExtension `clipboard` API exists primarily because the standard Clipboard API doesn't support writing images to the clipboard. The WebExtension `clipboard` API may be deprecated once the standard Clipboard API's support for non-text clipboard contents has entered general use.

Reading from the clipboard is not supported by this API, because the clipboard can already be read using the standard web platform APIs. See Interacting with the clipboard.

This API is based on Chrome's `clipboard` API, but that API is only available for Chrome apps, not extensions.

To use this API you need the `"clipboardWrite"` extension permission.

Functions
---------

`clipboard.setImageData()`

Copy an image to the clipboard.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:**

This API is based on Chromium's `chrome.clipboard` API.


devtools - Mozilla

devtools
========

Enables extensions to interact with the browser's Developer Tools. You use this API to create Developer Tools pages, interact with the window that is being inspected, inspect the page network usage.

To use this API, you must specify the `devtools_page` manifest key. The use of this manifest key triggers an install-time permission warning about devtools. To avoid an install-time permission warning, mark the feature as optional by listing the `"devtools"` permission in the `optional_permissions` manifest key.

>
> NOTE: The "devtools" optional permission is only supported by Firefox and not Chrome (Chromium issue 1143015).
>
>
>

Properties
----------

`devtools.inspectedWindow`

Interact with the window that Developer tools are attached to (inspected window). This includes obtaining the tab ID for the inspected page, evaluate the code in the context of the inspected window, reload the page, or obtain the list of resources within the page.

`devtools.network`

Obtain information about network requests associated with the window that the Developer Tools are attached to (the inspected window).

`devtools.panels`

Create User Interface panels that will be displayed inside User Agent Developer Tools.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.devtools` API.


dns - Mozilla

dns
===

Enables an extension to resolve domain names.

To use this API, an extension must request the "dns" permission in its `manifest.json` file.

**Note:** DNS will fail with NS\_ERROR\_UNKNOWN\_PROXY\_HOST if proxying DNS over socks is enabled.

Functions
---------

`dns.resolve()`

Resolves the given hostname to a DNS record.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


extension - Mozilla

extension
=========

Utilities related to your extension. Get URLs to resources packages with your extension. Get the `Window` object for your extension's pages. Get the values for various settings.

**Note:** **The messaging APIs in this module are deprecated** in favor of the equivalent APIs in the `runtime` module.

Types
-----

`extension.ViewType`

The type of extension view.

Properties
----------

`extension.lastError`
Deprecated

Set for the lifetime of a callback if an asynchronous extension API has resulted in an error. If no error has occurred, `lastError` will be `undefined`.

`extension.inIncognitoContext`

`True` for content scripts running inside incognito tabs, and for extension pages running inside an incognito process. (The latter only applies to extensions with '`split`' `incognito_behavior`.)

Functions
---------

`extension.getBackgroundPage()`

Returns the `Window` object for the background page running inside the current extension. Returns `null` if the extension has no background page.

`extension.getExtensionTabs()`
Deprecated

Returns an array of the JavaScript Window objects for each of the tabs running inside the current extension.

`extension.getURL()`
Deprecated

Converts a relative path within an extension install directory to a fully-qualified URL.

`extension.getViews()`

Returns an array of the `Window` objects for each of the pages running inside the current extension.

`extension.isAllowedIncognitoAccess()`

Retrieves the state of the extension's access to Incognito-mode (as determined by the user-controlled '*Allowed in Incognito*' checkbox).

`extension.isAllowedFileSchemeAccess()`

Retrieves the state of the extension's access to the `file://` scheme (as determined by the user-controlled '*Allow access to File URLs*' checkbox).

`extension.sendRequest()`
Deprecated

Sends a single request to other listeners within the extension.

`extension.setUpdateUrlData()`

Sets the value of the ap CGI parameter used in the extension's update URL. This value is ignored for extensions that are hosted in the browser vendor's store.

Events
------

`extension.onRequest`
Deprecated

Fired when a request is sent from either an extension process or a content script.

`extension.onRequestExternal`
Deprecated

Fired when a request is sent from another extension.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Example extensions
------------------

* beastify
* cookie-bg-picker
* find-across-tabs
* imagify
* notify-link-clicks-i18n
* proxy-blocker
* user-agent-rewriter

**Note:** This API is based on Chromium's `chrome.extension` API. This documentation is derived from `extension.json` in the Chromium code.


find - Mozilla

find
====

Finds text in a web page, and highlights matches.

To use this API you need to have the "find" permission.

Functions
---------

`find.find()`

Find text in a web page.

`find.highlightResults()`

Highlight the last set of matches found.

`find.removeHighlighting()`

Remove any highlighting.

Browser compatibility
---------------------

Example extensions
------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

* find-across-tabs


events - Mozilla

events
======

Common types used by APIs that dispatch events.

Types
-----

`events.Rule`

Description of a declarative rule for handling events.

`events.Event`

An object which allows the addition and removal of listeners for a browser event.

`events.UrlFilter`

Filters URLs for various criteria. If any of the given criteria match, then the whole filter matches.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.events` API. This documentation is derived from `events.json` in the Chromium code.


browsingData.removeLocalStorage() - Mozilla

browsingData.removeLocalStorage()
=================================

Clears any local storage created by websites.

You can use the `removalOptions` parameter, which is a `browsingData.RemovalOptions` object, to:

* clear only local storage objects created after a given time
* control whether to clear only local storage objects created by normal web pages or to clear objects created by hosted apps and extensions as well.

This is an asynchronous function that returns a `Promise`.

Syntax
------

```js
let removing = browser.browsingData.removeLocalStorage(
  removalOptions            // RemovalOptions object
)
```

### Parameters

`removalOptions`

`object`. A `browsingData.RemovalOptions` object, which may be used to clear only local storage objects created by normal web pages or to clear objects created by hosted apps and extensions as well.

### Return value

A `Promise` that will be fulfilled with no arguments when the removal has finished. If any error occurs, the promise will be rejected with an error message.

Examples
--------

Remove all local storage:

```js
function onRemoved() {
  console.log("removed");
}

function onError(error) {
  console.error(error);
}

browser.browsingData.removeLocalStorage({}).then(onRemoved, onError);
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.browsingData` API.


browsingData.removePasswords() - Mozilla

browsingData.removePasswords()
==============================

Clears saved passwords.

You can use the `removalOptions` parameter, which is a `browsingData.RemovalOptions` object, to:

* clear only passwords that were saved after a given time
* control whether to clear passwords that were saved on normal web pages or to clear passwords that were saved on hosted apps and extensions as well.

This is an asynchronous function that returns a `Promise`.

Syntax
------

```js
let removing = browser.browsingData.removePasswords(
  removalOptions            // RemovalOptions object
)
```

### Parameters

`removalOptions`

`object`. A `browsingData.RemovalOptions` object, which may be used to clear only passwords that were saved after a given time, and whether to clear passwords that were saved on normal web pages or to clear passwords that were saved on hosted apps and extensions as well.

### Return value

A `Promise` that will be fulfilled with no arguments when the removal has finished. If any error occurs, the promise will be rejected with an error message.

Examples
--------

Remove passwords saved in the last week:

```js
function onRemoved() {
  console.log("removed");
}

function onError(error) {
  console.error(error);
}

function weekInMilliseconds() {
  return 1000 \* 60 \* 60 \* 24 \* 7;
}

let oneWeekAgo = new Date().getTime() - weekInMilliseconds();

browser.browsingData
  .removePasswords({ since: oneWeekAgo })
  .then(onRemoved, onError);
```

Remove all saved passwords:

```js
function onRemoved() {
  console.log("removed");
}

function onError(error) {
  console.error(error);
}

browser.browsingData.removePasswords({}).then(onRemoved, onError);
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.browsingData` API.


browsingData.removeFormData() - Mozilla

browsingData.removeFormData()
=============================

Clears data that the browser has saved for autofilling forms.

You can use the `removalOptions` parameter, which is a `browsingData.RemovalOptions` object, to:

* clear only form data entered after a given time
* control whether to clear only form data entered in normal web pages or to clear data entered in hosted apps and extensions as well.

This is an asynchronous function that returns a `Promise`.

Syntax
------

```js
let removing = browser.browsingData.removeFormData(
  removalOptions            // RemovalOptions object
)
```

### Parameters

`removalOptions`

`object`. A `browsingData.RemovalOptions` object, which may be used to clear only form data entered after a given time, and whether to clear only form data entered in normal web pages or to clear data entered in hosted apps and extensions as well.

### Return value

A `Promise` that will be fulfilled with no arguments when the removal has finished. If any error occurs, the promise will be rejected with an error message.

Examples
--------

Remove form data saved in the last week:

```js
function onRemoved() {
  console.log("removed");
}

function onError(error) {
  console.error(error);
}

function weekInMilliseconds() {
  return 1000 \* 60 \* 60 \* 24 \* 7;
}

let oneWeekAgo = new Date().getTime() - weekInMilliseconds();

browser.browsingData
  .removeFormData({ since: oneWeekAgo })
  .then(onRemoved, onError);
```

Remove all saved form data:

```js
function onRemoved() {
  console.log("removed");
}

function onError(error) {
  console.error(error);
}

browser.browsingData.removeFormData({}).then(onRemoved, onError);
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.browsingData` API.


browsingData.removeCache() - Mozilla

browsingData.removeCache()
==========================

Clears the browser's cache.

Note that although this function can take a `browsingData.RemovalOptions` object, it will be ignored. The entire cache is always cleared when using this function.

This is an asynchronous function that returns a `Promise`.

Syntax
------

```js
let removing = browser.browsingData.removeCache(
  removalOptions            // RemovalOptions object
)
```

### Parameters

`removalOptions` Optional

`object`. A `browsingData.RemovalOptions` object. This parameter has no effect.

### Return value

A `Promise` that will be fulfilled with no arguments when the removal has finished. If any error occurs, the promise will be rejected with an error message.

Examples
--------

Clear the browser cache:

```js
function onRemoved() {
  console.log("removed");
}

function onError(error) {
  console.error(error);
}

browser.browsingData.removeCache({}).then(onRemoved, onError);
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.browsingData` API.


browsingData.removeHistory() - Mozilla

browsingData.removeHistory()
============================

Clears the record of web pages that the user has visited (browsing history).

You can use the `removalOptions` parameter, which is a `browsingData.RemovalOptions` object, to:

* clear only records of web pages visited after a given time
* control whether to clear only records of normal web pages or to clear records of hosted apps and extensions as well.

This is an asynchronous function that returns a `Promise`.

Syntax
------

```js
let removing = browser.browsingData.removeHistory(
  removalOptions            // RemovalOptions object
)
```

### Parameters

`removalOptions`

`object`. A `browsingData.RemovalOptions` object, which may be used to clear only records of web pages visited after a given time, and whether to clear only records of normal web pages or to clear records of hosted apps and extensions as well.

### Return value

A `Promise` that will be fulfilled with no arguments when the removal has finished. If any error occurs, the promise will be rejected with an error message.

Examples
--------

Remove records of pages visited in the last week:

```js
function onRemoved() {
  console.log("removed");
}

function onError(error) {
  console.error(error);
}

function weekInMilliseconds() {
  return 1000 \* 60 \* 60 \* 24 \* 7;
}

let oneWeekAgo = new Date().getTime() - weekInMilliseconds();

browser.browsingData
  .removeHistory({ since: oneWeekAgo })
  .then(onRemoved, onError);
```

Remove all records of visited pages:

```js
function onRemoved() {
  console.log("removed");
}

function onError(error) {
  console.error(error);
}

browser.browsingData.removeHistory({}).then(onRemoved, onError);
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.browsingData` API.


browsingData.removeDownloads() - Mozilla

browsingData.removeDownloads()
==============================

Clears the browser's download history. Note that this does not delete the downloaded objects themselves, only records of downloads in the browser's history.

You can use the `removalOptions` parameter, which is a `browsingData.RemovalOptions` object, to:

* clear records of items downloaded after a given time
* control whether to clear only records of items downloaded from normal web pages or to clear records from hosted apps and extensions as well.

This is an asynchronous function that returns a `Promise`.

Syntax
------

```js
let removing = browser.browsingData.removeDownloads(
  removalOptions            // RemovalOptions object
)
```

### Parameters

`removalOptions`

`object`. A `browsingData.RemovalOptions` object, which may be used to clear only records created after a given time, and whether to clear only records of items downloaded from normal web pages or to clear records from hosted apps and extensions as well.

### Return value

A `Promise` that will be fulfilled with no arguments when the removal has finished. If any error occurs, the promise will be rejected with an error message.

Examples
--------

Remove records of objects downloaded in the last week:

```js
function onRemoved() {
  console.log("removed");
}

function onError(error) {
  console.error(error);
}

function weekInMilliseconds() {
  return 1000 \* 60 \* 60 \* 24 \* 7;
}

let oneWeekAgo = new Date().getTime() - weekInMilliseconds();

browser.browsingData
  .removeDownloads({ since: oneWeekAgo })
  .then(onRemoved, onError);
```

Remove all records of downloaded objects:

```js
function onRemoved() {
  console.log("removed");
}

function onError(error) {
  console.error(error);
}

browser.browsingData.removeDownloads({}).then(onRemoved, onError);
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.browsingData` API.


browsingData.removeCookies() - Mozilla

browsingData.removeCookies()
============================

Clears the browser's cookies.

You can use the `removalOptions` parameter, which is a `browsingData.RemovalOptions` object, to:

* clear only cookies created after a given time
* control whether to clear cookies only set from normal web pages or to clear cookies set from hosted apps and extensions as well.

This is an asynchronous function that returns a `Promise`.

Syntax
------

```js
let removing = browser.browsingData.removeCookies(
  removalOptions            // RemovalOptions object
)
```

### Parameters

`removalOptions`

`object`. A `browsingData.RemovalOptions` object, which may be used to clear only cookies created after a given time, and whether to clear cookies only set from normal web pages or to clear cookies set from hosted apps and extensions as well.

### Return value

A `Promise` that will be fulfilled with no arguments when the removal has finished. If any error occurs, the promise will be rejected with an error message.

Examples
--------

Remove cookies created in the last week:

```js
function onRemoved() {
  console.log("removed");
}

function onError(error) {
  console.error(error);
}

function weekInMilliseconds() {
  return 1000 \* 60 \* 60 \* 24 \* 7;
}

let oneWeekAgo = new Date().getTime() - weekInMilliseconds();

browser.browsingData
  .removeCookies({ since: oneWeekAgo })
  .then(onRemoved, onError);
```

Remove all cookies:

**Warning:** Using the API to remove all cookies will, simultaneously, clear all local storage objects (including those of other extensions).

If you want to clear all cookies without disrupting local storage facilities, use browser.cookies to loop through and remove the contents of all cookie stores.

```js
function onRemoved() {
  console.log("removed");
}

function onError(error) {
  console.error(error);
}

browser.browsingData.removeCookies({}).then(onRemoved, onError);
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.browsingData` API.


browsingData.DataTypeSet - Mozilla

browsingData.DataTypeSet
========================

The **`browsingData.DataTypeSet`** type describes a set of data types.

It contains a number of boolean properties. The name of each property is the name of a particular type of browsing data: "downloads", "history" and so on. All properties are optional.

This type is used:

* in `browsingData.remove()` to describe which data types to remove
* in `browsingData.settings()` to describe which data types are currently selected in the browser's "Clear History" feature.
Type
----

Values of this type are objects. They contain the following properties:

`cache` Optional

`boolean`. The browser's cache.

`cookies` Optional

`boolean`. Cookies acquired while browsing.

`downloads` Optional

`boolean`. The user's download history.

`fileSystems` Optional

`boolean`. Website's file systems.

`formData` Optional

`boolean`. Saved form data, for autocomplete.

`history` Optional

`boolean`. The user's browsing history.

`indexedDB` Optional

`boolean`. IndexedDB data.

`localStorage` Optional

`boolean`. Local storage data.

`passwords` Optional

`boolean`. Saved passwords, for autocomplete.

`pluginData` Optional

`boolean`. Stored data associated with plugins.

`serverBoundCertificates` Optional

`boolean`. Stored server-bound certificates.

`serviceWorkers` Optional

`boolean`. Data cached by service workers.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.browsingData` API.


browsingData.removePluginData() - Mozilla

browsingData.removePluginData()
===============================

Clears data stored by browser plugins.

You can use the `removalOptions` parameter, which is a `browsingData.RemovalOptions` object, to:

* clear only plugin data stored after a given time
* control whether to clear only data stored by plugins running in normal web pages or to clear data stored by plugins running in hosted apps and extensions as well.

This is an asynchronous function that returns a `Promise`.

Syntax
------

```js
let removing = browser.browsingData.removePluginData(
  removalOptions            // RemovalOptions object
)
```

### Parameters

`removalOptions`

`object`. A `browsingData.RemovalOptions` object, which may be used to clear only plugin data stored after a given time, and whether to clear only data stored by plugins running in normal web pages or to clear data stored by plugins running in hosted apps and extensions as well.

### Return value

A `Promise` that will be fulfilled with no arguments when the removal has finished. If any error occurs, the promise will be rejected with an error message.

Examples
--------

Remove data stored by plugins in the last week:

```js
function onRemoved() {
  console.log("removed");
}

function onError(error) {
  console.error(error);
}

function weekInMilliseconds() {
  return 1000 \* 60 \* 60 \* 24 \* 7;
}

let oneWeekAgo = new Date().getTime() - weekInMilliseconds();

browser.browsingData
  .removePluginData({ since: oneWeekAgo })
  .then(onRemoved, onError);
```

Remove all data stored by plugins:

```js
function onRemoved() {
  console.log("removed");
}

function onError(error) {
  console.error(error);
}

browser.browsingData.removePluginData({}).then(onRemoved, onError);
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.browsingData` API.


browsingData.settings() - Mozilla

browsingData.settings()
=======================

Browsers have a built-in "Clear History" feature, which enables the user to clear various types of browsing data. This has a UI that enables the user to select what type of data to remove (e.g. history, downloads, …) and how far back in time to remove data.

This function returns the current value of these settings.

Note that not all data types will always be removable through the UI, and some UI options may map to more than one data type.

This is an asynchronous function that returns a `Promise`.

Syntax
------

```js
let getSettings = browser.browsingData.settings()
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with an object containing the settings information. This object has three properties:

`options`

``browsingData.RemovalOptions``. A `RemovalOptions` object describing the removal options currently selected.

`dataToRemove`

``browsingData.DataTypeSet``. This will contain a property for every data type that can be toggled in the browser's UI. Each property will have a value of `true` if that type is selected for removal and `false` otherwise.

`dataRemovalPermitted`

``browsingData.DataTypeSet``. This will contain a property for every data type that can be toggled in the browser's UI. Each will have a value of `true` if the administrator of the device has allowed the user to remove that type, and `false` otherwise.

If any error occurs, the promise will be rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Log current settings:

```js
function onGotSettings(settings) {
  console.log(settings.options);
  console.log(settings.dataToRemove);
  console.log(settings.dataRemovalPermitted);
}

function onError(error) {
  console.error(error);
}

browser.browsingData.settings().then(onGotSettings, onError);
```

**Note:** This API is based on Chromium's `chrome.browsingData` API.


browsingData.RemovalOptions - Mozilla

browsingData.RemovalOptions
===========================

The **`browsingData.RemovalOptions`** type contains options to control certain aspects of browsing data removal.

Type
----

Values of this type are objects. They contain the following properties:

`cookieStoreId` Optional

`string`. This property only applies to cookies and indexedDB items. The removal is limited to items belonging to a specific cookie store as specified by the ID. See Work with contextual identities for more information.

**Note:** On Firefox Nightly removal of localStorage items by `cookieStoreId` is also supported.

`hostnames` Optional

`Array` of `string`. This property applies to cookie, indexedDB, local storage, and service worker registration items. Remove only cookie, indexedDB, local storage, and service worker registration items associated with these hostnames.

You must pass in just a hostname here, without protocol (for example, "google.com" not "https://google.com"). You can use the `URL` interface to parse a raw URL and retrieve the hostname. Items associated with subdomains of a given hostname are *not* removed: you must explicitly list subdomains.

`originTypes` Optional

`object`. Used to control whether to remove data only from normal web pages, or also from hosted web apps and extensions. If this option is omitted, only data from normal web pages ("`unprotectedWeb`") is removed. Before removing data from web apps or extensions, be very careful to ensure that this is really what the user wants.

This object may contain any of the following properties:

`unprotectedWeb` Optional

`boolean`. If present and `true`, remove data from normal web pages.

`protectedWeb` Optional

`boolean`. If present and `true`, remove data from websites that have been installed as hosted apps.

`extension` Optional

`boolean`. If present and `true`, remove data from extensions.

`since` Optional

`number`. How far back in time to remove data, given in milliseconds since the UNIX epoch. Note that when removing the browser cache, the entire cache is always removed and this option is ignored. If the `since` property is omitted, it defaults to 0, which means "forever".

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.browsingData` API.


browsingData.remove() - Mozilla

browsingData.remove()
=====================

Removes the specified browsing data.

The browsing data to be removed is specified in the `dataTypes` option, which is a `browsingData.DataTypeSet` object.

You can use the `removalOptions` option, which is a `browsingData.RemovalOptions` object, to control how far back in time to remove data and whether to remove data only from normal web pages or to remove data from hosted apps and extensions as well.

This is an asynchronous function that returns a `Promise`.

Syntax
------

```js
let removing = browser.browsingData.remove(
  removalOptions,            // RemovalOptions object
  dataTypes                  // DataTypeSet object
)
```

### Parameters

`removalOptions`

`object`. A `browsingData.RemovalOptions` object, which may be used to control how far back in time to remove data, and whether to remove data from hosted web apps and extensions, or just normal web pages.

`dataTypes`

`object`. A `browsingData.DataTypeSet` object, describing the types of data to remove (e.g. history, downloads, …).

### Return value

A `Promise` that will be fulfilled with no arguments when the removal has finished. If any error occurs, the promise will be rejected with an error message.

Examples
--------

Remove download history and browsing history for the last week:

```js
function onRemoved() {
  console.log("removed");
}

function onError(error) {
  console.error(error);
}

function weekInMilliseconds() {
  return 1000 \* 60 \* 60 \* 24 \* 7;
}

let oneWeekAgo = new Date().getTime() - weekInMilliseconds();

browser.browsingData
  .remove({ since: oneWeekAgo }, { downloads: true, history: true })
  .then(onRemoved, onError);
```

Remove all download and browsing history:

```js
function onRemoved() {
  console.log("removed");
}

function onError(error) {
  console.error(error);
}

browser.browsingData
  .remove({}, { downloads: true, history: true })
  .then(onRemoved, onError);
```

### Example extensions

* forget-it
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.browsingData` API.


theme.update() - Mozilla

theme.update()
==============

Updates the browser theme according to the content of the `Theme` object.

To use this method, an extension must request the "theme" permission in its manifest.json file.

Syntax
------

```js
browser.theme.update(
  windowId,    // integer
  theme        // object
)
```

### Parameters

`windowId` Optional

`integer`. The ID of a window. If this is provided, the theme is applied only to that window. If it is omitted, the theme is applied to all windows.

`theme`

`object`. A `Theme` object specifying values for the UI elements you want to modify.

Examples
--------

Sets the browser theme to use a sun graphic with a complementary background color:

```js
const suntheme = {
  images: {
    theme\_frame: "sun.jpg",
  },
  colors: {
    frame: "#CF723F",
    tab\_background\_text: "#111",
  },
};

browser.theme.update(suntheme);
```

Set the theme for the focused window only:

```js
const day = {
  images: {
    theme\_frame: "sun.jpg",
  },
  colors: {
    frame: "#CF723F",
    tab\_background\_text: "#111",
  },
};

browser.menus.create({
  id: "set-theme",
  title: "set theme",
  contexts: ["all"],
});

async function updateThemeForCurrentWindow() {
  let currentWindow = await browser.windows.getLastFocused();
  browser.theme.update(currentWindow.id, day);
}

browser.menus.onClicked.addListener(updateThemeForCurrentWindow);
```

### Example extensions

* dynamic-theme
* private-browsing-theme
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


theme.onUpdated - Mozilla

theme.onUpdated
===============

Fires when a theme supplied as a browser extension is applied or removed. Specifically:

* when a static theme is installed
* when a dynamic theme calls `theme.update()` or `theme.reset()`
* when a theme gets uninstalled.

This event is not fired for changes to the built-in themes.

Syntax
------

```js
browser.theme.onUpdated.addListener(listener)
browser.theme.onUpdated.removeListener(listener)
browser.theme.onUpdated.hasListener(listener)
```

Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed these arguments:

`updateInfo`

`object`. An object containing two properties:

`theme`

`object`. If the event fired because an extension-supplied theme was removed, this is an empty object. If it fired because an extension-supplied theme was applied, then it is a `theme.Theme` object representing the theme that was applied.

`windowId` Optional

`integer`. The ID of the window in which the theme was updated. If this property is not present, the theme was updated in all windows.

Examples
--------

```js
function handleUpdated(updateInfo) {
  if (updateInfo.theme.colors) {
    console.log(`Theme was applied: ${updateInfo.theme}`);
  } else {
    console.log(`Theme was removed`);
  }
}

browser.theme.onUpdated.addListener(handleUpdated);
```

### Example extensions

* theme-integrated-sidebar
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Theme - Mozilla

Theme
=====

A Theme object represents the specification of a theme.

Type
----

A JSON object that takes the same properties as the "theme" manifest key.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


theme.reset() - Mozilla

theme.reset()
=============

Resets any theme applied using the `theme.update()` method.

To use this method, an extension must request the "theme" permission in its manifest.json file.

Note that this always reset the theme back to the original default theme, even if the user selected a different theme before this extension's theme was applied (see bug 1415267).

Syntax
------

```js
browser.theme.reset(
  windowId     // integer
)
```

### Parameters

`windowId` Optional

`integer`. The ID of a window. If this is provided, the theme applied to that window is reset. If it is omitted, the theme is reset on all windows.

Examples
--------

This code applies a theme, then removes it when the user clicks a browser action:

```js
browser.theme.update(themes.night);

browser.browserAction.onClicked.addListener(() => {
  browser.theme.reset();
});
```

### Example extensions

* private-browsing-theme
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


theme.getCurrent() - Mozilla

theme.getCurrent()
==================

Gets the current theme as a `Theme` object.

This is an asynchronous function that returns a `Promise`.

Syntax
------

```js
let getting = browser.theme.getCurrent(
  windowId    // integer
)
```

### Parameters

`windowId` Optional

`integer`. The ID of a window. If this is provided, the theme resolved is the one applied to that window. If it is omitted, the theme resolved is the one applied to the most recently focused window.

### Return value

A `Promise`. The promise is fulfilled with a `theme.Theme` object representing the theme applied to the given window. If no extension-supplied theme has been applied to the given window, it is fulfilled with an empty object.

Examples
--------

Gets the properties `frame` and `toolbar` colors of the current theme:

```js
function getStyle(themeInfo) {
  if (themeInfo.colors) {
    console.log(`accent color: ${themeInfo.colors.frame}`);
    console.log(`toolbar: ${themeInfo.colors.toolbar}`);
  }
}

async function getCurrentThemeInfo() {
  const themeInfo = await browser.theme.getCurrent();
  getStyle(themeInfo);
}

getCurrentThemeInfo();
```

### Example extensions

* theme-integrated-sidebar
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


privacy.network - Mozilla

privacy.network
===============

The `privacy.network` property contains privacy-related network settings. Each property is a `types.BrowserSetting` object.

Default values for these properties tend to vary across browsers.

Properties
----------

`networkPredictionEnabled`

A `types.BrowserSetting` object whose underlying value is a boolean. If `true`, the browser attempts to speed up web browsing by pre-resolving DNS entries, prerendering sites (using, for example, `<link rel='prefetch' …>`), and preemptively opening TCP and TLS connections to servers.

`peerConnectionEnabled`

A `types.BrowserSetting` object whose underlying value is a boolean. If `false`, the `RTCPeerConnection` interface is disabled. Note that `getUserMedia()` is *not* affected by this setting.

`webRTCIPHandlingPolicy`

A `types.BrowserSetting` object whose underlying value is a string. This setting allows users to specify the media performance/privacy tradeoffs which affect how WebRTC traffic will be routed and how much local address information is exposed. It may take any one of the following values, from least private to most private:

* `default`
* `default_public_and_private_interfaces`
* `default_public_interface_only`
* `disable_non_proxied_udp`
* `proxy_only` (only connections using TURN on a TCP connection through a proxy are allowed)

`httpsOnlyMode`

 This setting allows your extension to determine if a user has enabled
 HTTPS-Only mode. This property is read-only on all platforms. Its underlying value is a string that may take one of three values:

* `"always"`: HTTPS-Only mode is on.
* `"never"`: HTTPS-Only mode is off.
* `"private_browsing"`: HTTPS-Only mode is on in private browsing windows only.

`globalPrivacyControl`

 this setting allows your extension to determine if a user has enabled
 Global Privacy Control. This property is read-only on all platforms. Its underlying value is a boolean where `true` indicates that the browser sends Global Privacy Control signals and `false` indicates the browser does not send the signals.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Set the `webRTCIPHandlingPolicy` property:

```js
function onSet(result) {
  if (result) {
    console.log("success");
  } else {
    console.log("failure");
  }
}

browser.browserAction.onClicked.addListener(() => {
  let getting = browser.privacy.network.webRTCIPHandlingPolicy.get({});
  getting.then((got) => {
    console.log(got.value);
    if (
      got.levelOfControl === "controlled\_by\_this\_extension" ||
      got.levelOfControl === "controllable\_by\_this\_extension"
    ) {
      let setting = browser.privacy.network.webRTCIPHandlingPolicy.set({
        value: "default\_public\_interface\_only",
      });
      setting.then(onSet);
    } else {
      console.log("Not able to set webRTCIPHandlingPolicy");
    }
  });
});
```

**Note:** This API is based on Chromium's `chrome.privacy` API. This documentation is derived from `privacy.json` in the Chromium code.


privacy.websites - Mozilla

privacy.websites
================

The `privacy.websites` property contains privacy-related settings controlling the way to browser interacts with websites. Each property is a `types.BrowserSetting` object.

Default values for these properties tend to vary across browsers.

Properties
----------

`cookieConfig`

A `types.BrowserSetting` object whose underlying value is an object.

The object has two properties:

* `behavior`: a string which may take any of the following values:
    + "allow\_all": accept all cookies
    + "reject\_all": reject all cookies
    + "reject\_third\_party": reject all third-party cookies
    + "allow\_visited": accept a third-party cookie only if the cookie's top-level domain already has at least one cookie.
    + "reject\_trackers": reject tracking cookies
    + "reject\_trackers\_and\_partition\_foreign": reject trackers and partition third-party cookies.
* `nonPersistentCookies`
Deprecated
: a boolean. If true, all cookies will be treated as session cookies.

`firstPartyIsolate`

A `types.BrowserSetting` object whose underlying value is a boolean.

If `true`, the `firstPartyIsolate` preference makes the browser associate all data (including cookies, HSTS data, cached images, and more) for any third party domains with the domain in the address bar. This prevents third party trackers from using directly stored information to identify the user across different websites, but may break websites where the user logs in with a third party account (such as a Facebook or Google account).

Defaults to `false`.

`hyperlinkAuditingEnabled`

A `types.BrowserSetting` object whose underlying value is a boolean. If `true`, the browser sends auditing pings when a website uses the `ping` attribute to request them.

`protectedContentEnabled`

A `types.BrowserSetting` object whose underlying value is a boolean. Available on Windows only. If `true`, the browser provides a unique ID to plugins in order to run protected content.

`referrersEnabled`

A `types.BrowserSetting` object whose underlying value is a boolean. If enabled, the browser sends referer headers with your requests.

`resistFingerprinting`

A `types.BrowserSetting` object whose underlying value is a boolean.

Browser fingerprinting is the practice by which websites use Web APIs to collect status or configuration data associated with the browser or the device it's running on. By doing this, they can build up a digital fingerprint that they can use to identify and track a particular user.

If `true`, the `resistFingerprinting` preference makes the browser report generic spoofed information for data that's commonly used for fingerprinting. Such data includes the number of CPU cores, precision of JavaScript timers, and the local timezone. It will also disable features that are used in fingerprinting, such as GamePad support, and the WebSpeech and Navigator APIs.

Defaults to `false`.

`thirdPartyCookiesAllowed`

A `types.BrowserSetting` object whose underlying value is a boolean. If `false`, the browser blocks third-party cookies.

`trackingProtectionMode`

"Tracking protection" is a browser feature that blocks requests made to domains that are known to engage in cross-site tracking of users. Sites that track users are most commonly third-party advertising and analytics sites. This setting is a `types.BrowserSetting` object that determines whether the browser should enable tracking protection. Its underlying value is a string that may take one of three values:

* `"always"`: tracking protection is on.
* `"never"`: tracking protection is off.
* `"private_browsing"`: tracking protection is on in private browsing windows only.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Set the `hyperlinkAuditingEnabled` property.

```js
function onSet(result) {
  if (result) {
    console.log("success");
  } else {
    console.log("failure");
  }
}

browser.browserAction.onClicked.addListener(() => {
  let getting = browser.privacy.websites.hyperlinkAuditingEnabled.get({});
  getting.then((got) => {
    console.log(got.value);
    if (
      got.levelOfControl === "controlled\_by\_this\_extension" ||
      got.levelOfControl === "controllable\_by\_this\_extension"
    ) {
      let setting = browser.privacy.websites.hyperlinkAuditingEnabled.set({
        value: true,
      });
      setting.then(onSet);
    } else {
      console.log("Not able to set hyperlinkAuditingEnabled");
    }
  });
});
```

**Note:** This API is based on Chromium's `chrome.privacy` API. This documentation is derived from `privacy.json` in the Chromium code.


privacy.services - Mozilla

privacy.services
================

The `privacy.services` property contains privacy-related settings controlling services offered by the browser or by third parties. Each property is a `types.BrowserSetting` object.

Properties
----------

`passwordSavingEnabled`

A `types.BrowserSetting` object whose underlying value is a boolean. If `true`, the browser's password manager will offer to store passwords when the user enters them. Defaults to `true`.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Disable the password manager if possible.

```js
function onSet(result) {
  if (result) {
    console.log("success");
  } else {
    console.log("failure");
  }
}

let getting = browser.privacy.services.passwordSavingEnabled.get({});
getting.then((got) => {
  console.log(got.value);
  if (
    got.levelOfControl === "controlled\_by\_this\_extension" ||
    got.levelOfControl === "controllable\_by\_this\_extension"
  ) {
    let setting = browser.privacy.services.passwordSavingEnabled.set({
      value: false,
    });
    setting.then(onSet);
  } else {
    console.log("Not able to set passwordSavingEnabled");
  }
});
```

**Note:** This API is based on Chromium's `chrome.privacy` API.