recursal/MDN huggingface dataset:
incognito
=========

|  |  |
| --- | --- |
| Type | `String` |
| Mandatory | No |
| Manifest version | 2 or higher |
| Example | 
```json
"incognito": "spanning"
```


```json
"incognito": "split"
```


```json
"incognito": "not\_allowed"
```
 |

Use the `incognito` key to control how the extension works with private browsing windows.

**Note:** By default, extensions do not run in private browsing windows. Whether an extension can access private browsing windows is under user control. For details, see Extensions in Private Browsing. Your extension can check whether it can access private browsing windows using `extension.isAllowedIncognitoAccess`.

This is a string that can take any of these values:

* "spanning" (the default): the extension will see events from private and non-private windows and tabs. Windows and tabs will get an `incognito` property in the `Window` or `Tab` that represents them. This property indicates whether or not the object is private:

```js
browser.windows.getLastFocused().then((windowInfo) => {
  console.log(`Window is private: ${windowInfo.incognito}`);
});
```

* "split": the extension will be split between private and non-private windows. There are effectively two copies of the extension running: one sees only non-private windows, the other sees only private windows. Each copy has isolated access to Web APIs (so, for example, `localStorage` is not shared). However, the WebExtension API `storage.local` is shared. (**Note:** this setting is not supported by Firefox.)
* "not\_allowed": private tabs and windows are invisible to the extension.
Example
-------


```json
"incognito": "spanning"
```



```json
"incognito": "split"
```



```json
"incognito": "not\_allowed"
```

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
declarative\_net\_request
=========================

|  |  |
| --- | --- |
| Type | `Object` |
| Mandatory | No |
| Manifest version | 2 or higher |
| Example | 
```json
"declarative\_net\_request" : {
  "rule\_resources" : [{
    "id": "ruleset",
    "enabled": true,
    "path": "rules.json"
  }]
}
```
 |

Specify static rulesets for use with `declarativeNetRequest`. See Permissions for more information on permission requirements.

Syntax
------

The `"declarative_net_request"` key is an object that must contain the `"rule_resources"` property, an array that must include at least one object with these properties:

| Name | Type | Description |
| --- | --- | --- |
| `"id"` | `String` | A non-empty string uniquely identifying the ruleset. IDs beginning with '\_' are reserved for internal use. |
| `"enabled"` | `Boolean` | Whether the ruleset is enabled by default. The `declarativeNetRequest.updateEnabledRulesets` method can be used to enable or disable a ruleset at runtime. |
| `"path"` | `String` | The path of the JSON ruleset relative to the extension directory. See the Rules section of the `declarativeNetRequest` API for information on the content of the ruleset JSON file. |

Example
-------


```json
"declarative\_net\_request" : {
  "rule\_resources" : [{
    "id": "ruleset\_1",
    "enabled": true,
    "path": "rules\_1.json"
  }, {
    "id": "ruleset\_2",
    "enabled": false,
    "path": "rules\_2.json"
  }]
}
```

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

* dnr-block-only
* dnr-redirect-url
Browser compatibility
---------------------

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

|  |  |
| --- | --- |
| Type | `Number` |
| Mandatory | Yes |
| Example | 
```json
"manifest\_version": 3
```
 |

This key specifies the version of manifest.json used by this extension.

Example
-------


```json
"manifest\_version": 3
```

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

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

This page describes legacy web extension version string formats. See the manifest version key documentation for information on the current version string format.

Firefox legacy version number
-----------------------------

A **version string** consists of one or more *version parts*, separated by dots.

Each **version part** is parsed as a sequence of four parts: `<number-a><string-b><number-c><string-d>`. Each of the parts is optional. Numbers are integers base 10 (may be negative), and strings are non-numeric ASCII characters.

Here are a few examples of valid version parts:

* `0` (as in `1.0`): `<number-a>=0`
* `5a` (as in `1.5a`): `<number-a>=5`, `<string-b>=a`
* `5pre4` (as in `3.5pre4`): `<number-a>=5`, `<string-b>=pre`, `<number-c>=4`
* `*` (as in `1.0.*`): `<string-b>=*`

A few special parsing rules are applied for backward compatibility and readability:

* if the version part is a single asterisk, it is interpreted as an infinitely-large number:
 `1.5.0.*` is the same as `1.5.0.(infinity)`
* if string-b is a plus sign, number-a is incremented to be compatible with the Firefox 1.0.x version format:
 `1.0+` is the same as `1.1pre`

The rationale behind splitting a version part into a sequence of strings and numbers is that when comparing version parts, the numeric parts are compared as numbers, for example, '1.0pre1' < '1.0pre10', while the strings are compared byte-wise. See the next section for details on how versions are compared.

From Firefox 108, web extensions using this version string trigger a warning on installation.

Comparing versions
------------------

When two version strings are compared, their version parts are compared left to right. An empty or missing version part is equivalent to `0`.

If at some point, a version part of one version string is greater than the corresponding version part of another version string, then the first version string is greater than the other one.

Otherwise, the version strings are equal. As missing version parts are treated as if they were `0`, these version strings are equal: `1`, `1.0`, `1.0.`, `1.0.0`, and even `1.0..`.

### Comparing version parts

Version parts are also compared left to right; parts A and C are compared as numbers, while parts B and D are compared byte-wise. A string part that exists is always less than a string part that doesn't exist (`1.6a` is less than `1.6`).

Examples
--------
```

1.-1
< 1 == 1. == 1.0 == 1.0.0
< 1.1a < 1.1aa < 1.1ab < 1.1b < 1.1c
< 1.1pre == 1.1pre0 == 1.0+
< 1.1pre1a < 1.1pre1aa < 1.1pre1b < 1.1pre1
< 1.1pre2
< 1.1pre10
< 1.1.-1
< 1.1 == 1.1.0 == 1.1.00
< 1.10
< 1.* < 1.*.1
< 2.0
```
i18n
====

Functions to internationalize your extension. You can use these APIs to get localized strings from locale files packaged with your extension, find out the browser's current language, and find out the value of its Accept-Language header.

See the Internationalization page for a guide on using this API.

Types
-----

`i18n.LanguageCode`

A language tag such as `"en-US"` or "`fr`".

Functions
---------

`i18n.getAcceptLanguages()`

Gets the accept-languages of the browser. This is different from the locale used by the browser. To get the locale, use `i18n.getUILanguage`.

`i18n.getMessage()`

Gets the localized string for the specified message.

`i18n.getUILanguage()`

Gets the UI language of the browser. This is different from `i18n.getAcceptLanguages` which returns the preferred user languages.

`i18n.detectLanguage()`

Detects the language of the provided text using the Compact Language Detector.

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

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

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

* menu-accesskey-visible
* menu-demo
* notify-link-clicks-i18n

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

See also
--------

* Internationalization: a guide to using the WebExtension i18n system.
* Locale-Specific Message reference: extensions supply locale-specific strings in files called `messages.json`. This page describes the format of `messages.json`.
browserSettings
===============

Enables an extension to modify certain global browser settings. Each property of this API is a `BrowserSetting` object, providing the ability to modify a particular setting.

Because these are global settings, it's possible for extensions to conflict. See the documentation for `BrowserSetting.set()` for details of how conflicts are handled.

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

Properties
----------

`browserSettings.allowPopupsForUserEvents`

Determines whether code running in web pages can display popups in response to user events.

`browserSettings.cacheEnabled`

Determines whether the browser cache is enabled or not.

`browserSettings.closeTabsByDoubleClick`

Determines whether the selected tab can be closed with a double click.

`browserSettings.colorManagement`

Determines various settings for color management.

`browserSettings.contextMenuShowEvent`

Determines the mouse event that triggers a context menu popup.

`browserSettings.ftpProtocolEnabled`

Determines whether the FTP protocol is enabled.

`browserSettings.homepageOverride`

Read the value of the browser's home page.

`browserSettings.imageAnimationBehavior`

Determines how the browser treats animated images.

`browserSettings.newTabPageOverride`

Reads the value of the browser's new tab page.

`browserSettings.newTabPosition`

Controls the position of newly opened tabs relative to already open tabs.

`browserSettings.openBookmarksInNewTabs`

Determines whether bookmarks are opened in the current tab or a new tab.

`browserSettings.openSearchResultsInNewTabs`

Determines whether search results are opened in the current tab or a new tab.

`browserSettings.openUrlbarResultsInNewTabs`

Determines whether address bar autocomplete suggestions are opened in the current tab or a new tab.

`browserSettings.overrideContentColorScheme`

Controls whether to override the browser theme (light or dark) when setting pages' preferred color scheme.

`browserSettings.overrideDocumentColors`

Controls whether the user-chosen colors override the page's colors.

`browserSettings.tlsVersionRestrictionConfig`

Read the highest and lowest versions of TLS supported by the browser.

`browserSettings.useDocumentFonts`

Controls whether the browser will use the fonts specified by a web page or use only built-in fonts.

`browserSettings.webNotificationsDisabled`

Prevents websites from showing notifications using the `Notification` Web API.

`browserSettings.zoomFullPage`

Controls whether zoom is applied to the entire page or to text only.

`browserSettings.zoomSiteSpecific`

Controls whether page zoom is applied on a per-site or per-tab basis. If `privacy.websites``.resistFingerprinting` is true, this setting has no effect and zoom is applied on a per-tab basis.

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

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

Use the sessions API to list, and restore, tabs and windows that have been closed while the browser has been running.

The `sessions.getRecentlyClosed()` function returns an array of `tabs.Tab` and `windows.Window` objects, representing tabs and windows that have been closed since the browser was running, up to the maximum defined in `sessions.MAX_SESSION_RESULTS`.

You can then restore a window or tab using the `sessions.restore()` function. Restoring doesn't just reopen the tab: it also restores the tab's navigation history so the back/forward buttons will work.

This API also provides a group of functions that enable an extension to store additional state associated with a tab or a window. Then, if the tab or window is closed and subsequently restored, the extension can retrieve the state. For example, a tab grouping extension might use this to remember which group a tab is in, so as to restore it into the right group if the user restores the tab.

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

Types
-----

`sessions.Filter`

Enables you to restrict the number of `Session` objects returned by a call to `sessions.getRecentlyClosed()`.

`sessions.Session`

Represents a tab or window that the user has closed in the current browsing session.

Properties
----------

`sessions.MAX_SESSION_RESULTS`

The maximum number of sessions that will be returned by a call to `sessions.getRecentlyClosed()`.

Functions
---------

`sessions.forgetClosedTab()`

Removes a closed tab from the browser's list of recently closed tabs.

`sessions.forgetClosedWindow()`

Removes a closed window from the browser's list of recently closed windows.

`sessions.getRecentlyClosed()`

Returns an array of `Session` objects, representing windows and tabs that were closed in the current browsing session (that is: the time since the browser was started).

`sessions.restore()`

Restores a closed tab or window.

`sessions.setTabValue()`

Store a key/value pair associated with a given tab.

`sessions.getTabValue()`

Retrieve a previously stored value for a given tab, given its key.

`sessions.removeTabValue()`

Remove a key/value pair from a given tab.

`sessions.setWindowValue()`

Store a key/value pair associated with a given window.

`sessions.getWindowValue()`

Retrieve a previously stored value for a given window, given its key.

`sessions.removeWindowValue()`

Remove a key/value pair from a given window.

Events
------

`sessions.onChanged`

Fired when a tab or window is closed.

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

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

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

* session-state

**Note:** This API is based on Chromium's `chrome.sessions` API.
search
======

Use the search API to retrieve the installed search engines and execute searches.

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

When choosing between `search.query()` and `search.search()`, consider the following:

* `search.query()` is available in most major browsers, making it ideal for use in cross-browser extensions. However, it can only issue searches against the browser's default search engine.
* `search.search()` is available only in Firefox. However, it has the advantage of being able to issue a search against any search engine installed in the browser.
Functions
---------

`search.get()`

Retrieve all search engines.

`search.query()`

Search using the browser's default search engine.

`search.search()`

Search using a specified search engine.

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

* menu-search
Browser compatibility
---------------------

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

The API to control address bar button.

![Paw print icon representing a page action](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/pageAction/page-action.png)

You can listen for clicks on the icon in a background script, or specify a popup that opens when the icon is clicked.

If you specify a popup, you define its contents and behavior using HTML, CSS, and JavaScript. JavaScript running in the popup gets access to all the same WebExtension APIs as your background scripts. Despite being named `pageAction`, the action code doesn't get access to web page content. To access web page DOM, you need to add a content script and interact with it.

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

You can define most of a page action's properties declaratively using the `page_action` key in your `manifest.json`, and redefine them programmatically using this API.

Page actions are for actions that are only relevant to particular pages (such as "bookmark the current tab"). If they are relevant to the browser as a whole (such as "show all bookmarks"), use a browser action instead.

Types
-----

`pageAction.ImageDataType`

Pixel data for an image.

Functions
---------

`pageAction.show()`

Shows the page action for a given tab.

`pageAction.hide()`

Hides the page action for a given tab.

`pageAction.isShown()`

Checks whether the page action is shown or not.

`pageAction.setTitle()`

Sets the page action's title. This is displayed in a tooltip over the page action.

`pageAction.getTitle()`

Gets the page action's title.

`pageAction.setIcon()`

Sets the page action's icon.

`pageAction.setPopup()`

Sets the URL for the page action's popup.

`pageAction.getPopup()`

Gets the URL for the page action's popup.

`pageAction.openPopup()`

Opens the page action's popup.

Events
------

`pageAction.onClicked`

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

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

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

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

* apply-css
* chill-out
* history-deleter
* menu-remove-element

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

Interact with browser windows. You can use this API to get information about open windows and to open, modify, and close windows. You can also listen for window open, close, and activate events.

Types
-----

`windows.WindowType`

The type of browser window this is.

`windows.WindowState`

The state of this browser window.

`windows.Window`

Contains information about a browser window.

`windows.CreateType`

Specifies the type of browser window to create.

Constants
---------

`windows.WINDOW_ID_NONE`

The `windowId` value that represents the absence of a browser window.

`windows.WINDOW_ID_CURRENT`

A value that can be used in place of a `windowId` in some APIs to represent the current window.

Methods
-------

`windows.get()`

Gets details about a window, given its ID.

`windows.getCurrent()`

Gets the current window.

`windows.getLastFocused()`

Gets the window that was most recently focused — typically the window 'on top'.

`windows.getAll()`

Gets all windows.

`windows.create()`

Creates a new window.

`windows.update()`

Updates the properties of a window. Use this to move, resize, and (un)focus a window, etc.

`windows.remove()`

Closes a window, and all its tabs.

Events
------

`windows.onCreated`

Fired when a window is created.

`windows.onRemoved`

Fired when a window is closed.

`windows.onFocusChanged`

Fired when the currently focused window changes.

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

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

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

* annotate-page
* bookmark-it
* private-browsing-theme
* store-collected-images
* theme-integrated-sidebar
* window-manipulator

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

Use this API to register content scripts. Registering a content script instructs the browser to insert the given content scripts into pages that match the given URL patterns.

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

This API is very similar to the `"content_scripts"` `manifest.json` key, except that with `"content_scripts"`, the set of content scripts and associated patterns is fixed at install time. With the `contentScripts` API, an extension can register and unregister scripts at runtime.

To use the API, call `contentScripts.register()` passing in an object defining the scripts to register, the URL patterns, and other options. This returns a `Promise` that is resolved with a `contentScripts.RegisteredContentScript` object.

The `RegisteredContentScript` object represents the scripts that were registered in the `register()` call. It defines an `unregister()` method that you can use to unregister the content scripts. Content scripts are also unregistered automatically when the page that created them is destroyed. For example, if they are registered from the background page they will be unregistered automatically when the background page is destroyed, and if they are registered from a sidebar or a popup, they will be unregistered automatically when the sidebar or popup is closed.

There is no `contentScripts` API permission, but an extension must have the appropriate host permissions for any patterns it passes to `register()`.

Types
-----

`contentScripts.RegisteredContentScript`

An object of this type is returned by the `contentScripts.register()` function. It represents the content scripts that were registered by that call, and can be used to unregister the content script.

Functions
---------

`contentScripts.register()`

Registers the given content scripts.

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

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

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

* content-script-register
alarms
======

Schedule code to run at a specific time in the future. This is like `setTimeout()` and `setInterval()`, except that those functions don't work with background pages that are loaded on demand.

Alarms do not persist across browser sessions. They are created globally across all contexts of a single extension. E.g. alarm created in background script will fire `onAlarm` event in background script, options page, popup page and extension tabs (and vice versa). Alarms API is not available in `Content scripts`.

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

Types
-----

`alarms.Alarm`

Information about a particular alarm.

Methods
-------

`alarms.clear()`

Clear a specific alarm, given its name.

`alarms.clearAll()`

Clear all scheduled alarms.

`alarms.create()`

Create a new alarm.

`alarms.get()`

Retrieves a specific alarm, given its name.

`alarms.getAll()`

Retrieve all scheduled alarms.

Events
------

`alarms.onAlarm`

Fired when an alarm goes off.

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

* chill-out
* dynamic-theme
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.alarms` API.
notifications
=============

Display notifications to the user, using the underlying operating system's notification mechanism. Because this API uses the operating system's notification mechanism, the details of how notifications appear and behave may differ according to the operating system and the user's settings.

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

The notification looks the same on all desktop operating systems. Something like:

![Example notification with a bold title and regular text](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/notifications/notification.png)

Types
-----

`notifications.NotificationOptions`

Defines the content of a notification.

`notifications.TemplateType`

The type of notification. For example, this defines whether the notification can contain an image.

Functions
---------

`notifications.clear()`

Clear a specific notification, given its ID.

`notifications.create()`

Create and display a new notification.

`notifications.getAll()`

Get all notifications.

`notifications.update()`

Update a notification.

Events
------

`notifications.onButtonClicked`

Fired when the user clicked a button in the notification.

`notifications.onClicked`

Fired when the user clicked the notification, but not on a button.

`notifications.onClosed`

Fired when a notification closed, either by the system or because the user dismissed it.

`notifications.onShown`

Fired immediately after a notification has been shown.

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

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

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

* export-helpers
* forget-it
* google-userinfo
* notify-link-clicks-i18n
* runtime-examples

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