recursal/MDN huggingface dataset:
privacy
=======

Access and modify various privacy-related browser settings.

To use the privacy API, you must have the "privacy" API permission.

Properties
----------

`privacy.network`

Access and modify privacy settings relating to the network.

`privacy.services`

Access and modify privacy settings relating to the services provided by the browser or third parties.

`privacy.websites`

Access and modify privacy settings relating to the behavior of websites.

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.privacy` API.
dom
===

Access special extension only DOM features.

Functions
---------

`dom.openOrClosedShadowRoot()`

Gets the open shadow root or the closed shadow root hosted by the specified element. If the shadow root isn't attached to the element, it will return `null`.

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

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

Use the proxy API to proxy web requests. You can use the `proxy.onRequest` event listener to intercept web requests, and return an object that describes whether and how to proxy them.

The advantage of the `proxy.onRequest` approach is that the code that implements your proxy policy runs in your extension's background script, so it gets full access to the WebExtension APIs available to your extension (including, for example, access to your extension's `storage` and networking APIs like `dns`).

Apart from this API, extensions can also use the `browserSettings.proxyConfig` property to configure global proxy settings.

Google Chrome provides an extension API also called "proxy" which is functionally similar to this API, in that extensions can use it to implement a proxying policy. However, the design of the Chrome API is completely different to this API. Because this API is incompatible with the Chrome `proxy` API, this API is only available through the `browser` namespace.

To use this API you need to have the "proxy" permission. Also, where you want to intercept requests, you also need host permission for the URLs of intercepted requests.

**Note:** The "proxy" permission requires `"strict_min_version"` to be set to "91.1.0" or above. To use this permission, add or update the `"browser_specific_settings"` key in your manifest.json to specify a minimum Firefox version. See Securing the proxy API for Firefox add-ons for more information.

**Note:** 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`.

Types
-----

`proxy.ProxyInfo`

Describes a proxy.

`proxy.RequestDetails`

Contains information about a web request that the browser is about to make.

Properties
----------

`proxy.settings`

Get and set proxy settings.

Events
------

`proxy.onError`

Fired when the system encounters an error running the PAC script or the `onRequest` listener.

`proxy.onRequest`

Fired when a web request is about to be made, giving the extension an opportunity to proxy it.

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

* proxy-blocker
Browser compatibility
---------------------

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

Gets and sets properties of an extension's sidebar.

A sidebar is a pane that is displayed at the left-hand or right-hand side of the browser window, next to the web page. The browser provides a UI that enables the user to see the currently available sidebars and to select a sidebar to display. Using the `sidebar_action` manifest.json key, an extension can define its own sidebar. Using the `sidebarAction` API described here, an extension can get and set the sidebar's properties.

The `sidebarAction` API is closely modeled on the `browserAction` API.

The sidebarAction API is based on Opera's sidebarAction API. However, note that the following are not yet supported: `setBadgeText()`, `getBadgeText()`, `setBadgeBackgroundColor()`, `getBadgeBackgroundColor()`, `onFocus`, `onBlur`.

Types
-----

`sidebarAction.ImageDataType`

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

Functions
---------

`sidebarAction.close()`

Closes the sidebar.

`sidebarAction.getPanel()`

Gets the sidebar's panel.

`sidebarAction.getTitle()`

Gets the sidebar's title.

`sidebarAction.isOpen()`

Checks whether the sidebar is open or not.

`sidebarAction.open()`

Opens the sidebar.

`sidebarAction.setIcon()`

Sets the sidebar's icon.

`sidebarAction.setPanel()`

Sets the sidebar's panel.

`sidebarAction.setTitle()`

Sets the sidebar's title. This will be displayed in any UI provided by the browser to list sidebars, such as a menu.

`sidebarAction.toggle()`

Toggles the visibility of the sidebar.

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

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

Example add-ons
---------------

* annotate-page

**Note:** This API is based on Opera's `chrome.sidebarAction` API.
userScripts
===========

Use this API to register user scripts, third-party scripts designed to manipulate webpages or provide new features. Registering a user script instructs the browser to attach the script to pages that match the URL patterns specified during registration.

**Note:** When using Manifest V3 or higher, use `scripting.registerContentScripts()` to register scripts.

This API offers similar capabilities to `contentScripts` but with features suited to handling third-party scripts:

* execution is in an isolated sandbox: each user script is run in an isolated sandbox within the web content processes, preventing accidental or deliberate interference among scripts.
* access to the `window` and `document` global values related to the webpage the user script is attached to.
* no access to WebExtension APIs or associated permissions granted to the extension: the API script, which inherits the extension's permissions, can provide packaged WebExtension APIs to registered user scripts. An API script is declared in the extension's manifest file using the "user\_scripts" manifest key.

**Warning:** This API requires the presence of the `user_scripts` key in the manifest.json, even if no API script is specified. For example. `user_scripts: {}`.

To use the API, call ``register()`` passing in an object defining the scripts to register. The method returns a Promise that is resolved with a ``RegisteredUserScript`` object.

**Note:** User scripts are unregistered when the related extension page (from which the user scripts were registered) is unloaded, so you should register a user script from an extension page that persists at least as long as you want the user scripts to stay registered.

Types
-----

`userScripts.RegisteredUserScript`

The `object` returned by the `register()` method. It represents the registered user scripts and is used to deregister the user scripts.

Methods
-------

`userScripts.register()`

Registers user scripts.

Events
------

`userScripts.onBeforeScript`

An event available to the API script, registered in`"user_scripts"`, that execute before a user script executes. Use it to trigger the export of the additional APIs provided by the API script, so they are available to the user script.

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

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

See also
--------

* Working with `userScripts`
* `browser.contentScripts`
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.
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
=====

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.
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
=======

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
=============

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
============

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
========

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
=====

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
========

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.