[pull] main from mdn:main

files/en-us/mozilla/add-ons/webextensions/api/permissions/contains/index.md

@@ -6,11 +6,7 @@ browser-compat: webextensions.api.permissions.contains
 sidebar: addonsidebar
 ---
 
-Check whether the extension has the permissions listed in the given {{WebExtAPIRef("permissions.Permissions")}} object.
-
-The `Permissions` argument may contain either an origins property, which is an array of [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions), or a `permissions` property, which is an array of [API permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions), or both.
-
-This is an asynchronous function that returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). The promise resolves to `true` if the extension has all of the specified permissions. For host permissions, if the extension's permissions [pattern-match](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns) the permissions listed in `origins`, then they are considered to match.
+Checks whether the extension has specific permissions.
 
 ## Syntax
 
@@ -27,17 +23,18 @@ let getContains = browser.permissions.contains(
 
 ### Return value
 
-A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that will be fulfilled with `true` if the extension already has all the permissions listed in the `permissions` argument, or `false` otherwise.
+A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) fulfilled with `true` if the extension has all the permissions listed in the `permissions` argument, or `false` otherwise. For host permissions, if the extension's permissions [pattern-match](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns) the permissions listed in `origins`, then they are considered to match.
 
 ## Examples
 
 ```js
 // Extension permissions are:
-// "webRequest", "tabs", "*://*.mozilla.org/*"
+// "webRequest", "tabs", "*://*.mozilla.org/*", and "healthInfo" in "data_collection"
 
 let testPermissions1 = {
   origins: ["*://mozilla.org/"],
   permissions: ["tabs"],
+  data_collection: ["healthInfo"],
 };
 
 const testResult1 = await browser.permissions.contains(testPermissions1);
@@ -65,6 +62,13 @@ let testPermissions4 = {
 
 const testResult4 = await browser.permissions.contains(testPermissions4);
 console.log(testResult4); // false: "https://example.org/", `origins` doesn't match
+
+let testPermissions5 = {
+  data_collection: ["searchTerms"],
+};
+
+const testResult5 = await browser.permissions.contains(testPermissions4);
+console.log(testResult5); // false: "searchTerms" doesn't match data type in `data_collection`
 ```
 
 {{WebExtExamples}}

files/en-us/mozilla/add-ons/webextensions/api/permissions/getall/index.md

@@ -6,9 +6,7 @@ browser-compat: webextensions.api.permissions.getAll
 sidebar: addonsidebar
 ---
 
-Retrieve a {{WebExtAPIRef("permissions.Permissions")}} object containing all the permissions currently granted to the extension.
-
-This is an asynchronous function that returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
+Retrieves a {{WebExtAPIRef("permissions.Permissions")}} object containing all the permissions currently granted to the extension.
 
 ## Syntax
 
@@ -22,18 +20,19 @@ None.
 
 ### Return value
 
-A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that will be fulfilled with a {{WebExtAPIRef("permissions.Permissions")}} object containing all the permissions currently granted to the extension. This includes all permissions the extension has listed in the [`permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) key, and any permissions listed in [`optional_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions) that the extension has been granted by calling {{WebExtAPIRef("permissions.request()")}}.
+A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) fulfilled with a {{WebExtAPIRef("permissions.Permissions")}} object containing all the permissions currently granted to the extension. This includes all permissions the extension has listed in the [`permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) key, and any permissions listed in [`optional_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions) that the extension has been granted by calling {{WebExtAPIRef("permissions.request()")}}.
 
 ## Examples
 
 ```js
 // Extension permissions are:
-// "webRequest", "tabs", "*://*.mozilla.org/*"
+// "webRequest", "tabs", "*://*.mozilla.org/*", and "healthInfo" in "data_collection"
 
 const currentPermissions = await browser.permissions.getAll();
 
 console.log(currentPermissions.permissions); // [ "webRequest", "tabs" ]
 console.log(currentPermissions.origins); // [ "*://*.mozilla.org/*" ]
+console.log(currentPermissions.data_collection); // [ healthInfo" ]
 ```
 
 {{WebExtExamples}}

files/en-us/mozilla/add-ons/webextensions/api/permissions/index.md

@@ -8,22 +8,29 @@ sidebar: addonsidebar
 
 Enables extensions to request extra permissions at runtime, after they have been installed.
 
-Extensions need permissions to access more powerful WebExtension APIs. They can ask for permissions at install time, by including the permissions they need in the [`permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) manifest.json key. The main advantages of asking for permissions at install time are:
+Extensions need permissions to access more powerful WebExtension APIs. They can request permissions at install time by including them in the [`permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) manifest.json key. The main advantages of asking for permissions at install time are:
 
-- The user is only asked once, so it's less disruptive for them, and a simpler decision.
-- The extension can rely on the access to the APIs it needs, because if already running, the permissions have been granted.
+- The extension asks the user only once, so it's less disruptive for them, and a simpler decision.
+- The extension can rely on the access to the APIs it needs, as it knows the permissions are granted.
 
-In most major browsers, users can see if their installed extensions request advanced permissions through the browser's extensions manager.
+In most major browsers, users can see if installed extensions request advanced permissions through the browser's extensions manager.
 
-With the permissions API, an extension can ask for additional permissions at runtime. These permissions need to be listed in the [`optional_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions) manifest.json key. Note that some permissions are not allowed in `optional_permissions`. The main advantages of this are:
+Using the permissions API, an extension can request additional permissions at runtime. The extension must list these permissions in
 
-- The extension can run with a smaller set of permissions, except when it actually needs them.
-- The extension can handle permission denial in a graceful manner, instead of presenting the user with a global "all or nothing" choice at install time. You can still get a lot out of that map extension, without giving it access to your location, for example.
-- The extension may need [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions), but not know at install time which host permissions it needs. For example, the list of hosts may be a user setting. In this scenario, asking for a more specific range of hosts at runtime, can be an alternative to asking for "\<all_urls>" at install time.
+- [`optional_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions) key of its manifest.json file for origins and API permissions.
+- [`gecko.data_collection_permissions.optional`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings#optional) property of the `browser_specific_settings` key of its manifest.json file for data collection permissions.
 
-To use the permissions API, decide which permissions your extension can request at runtime, and list them in [`optional_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions). After this, you can request any permissions that were included in `optional_permissions`. Requests may only be made in the handler for a user action (for example, a click handler).
+The main advantages of requesting permissions at runtime are:
 
-Starting with Firefox 84, users will be able to manage optional permissions of installed extensions from the Add-ons Manager. Extensions that use optional permissions should listen for [browser.permissions.onAdded](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/permissions/onAdded) and [browser.permissions.onRemoved](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/permissions/onRemoved) API events to know when a user grants or revokes these permissions.
+- The extension can run with a smaller set of permissions, except when it needs them.
+- The extension can gracefully handle permission denial, instead of presenting the user with a global "all or nothing" choice at install time. For example, a user can get a lot out of that map extension without giving it access to their location.
+- The extension may need [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions), but not know at install time which host permissions it needs. For example, the list of hosts may be a user setting. In this scenario, requesting a more specific range of hosts at runtime can be an alternative to asking for "\<all_urls>" at install time.
+
+Note that some permissions are not allowed in `optional_permissions`.
+
+To use the permissions API, decide which permissions your extension can request at runtime, and list them in [`optional_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions) and [`browser_specific_settings.gecko.data_collection_permissions.optional`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings#optional). After this, you can request any permissions included in `optional_permissions` or `browser_specific_settings.gecko.data_collection_permissions.optional`. The extension can only make these requests in the handler for a user action (for example, a click handler).
+
+Starting with Firefox 84, users can manage optional permissions of installed extensions from the Add-ons Manager. Extensions that use optional permissions should listen for [browser.permissions.onAdded](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/permissions/onAdded) and [browser.permissions.onRemoved](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/permissions/onRemoved) API events to know when a user grants or revokes these permissions.
 
 For advice on designing your request for runtime permissions, to maximize the likelihood that users grant them, see [Request permissions at runtime](https://extensionworkshop.com/documentation/develop/request-the-right-permissions/#request_permissions_at_runtime).
 
@@ -35,20 +42,20 @@ For advice on designing your request for runtime permissions, to maximize the li
 ## Methods
 
 - {{WebExtAPIRef("permissions.contains()")}}
-  - : Discover an extension's given set of permissions.
+  - : Checks whether the extension has specific permissions.
 - {{WebExtAPIRef("permissions.getAll()")}}
-  - : Get all the permissions this extension currently has.
+  - : Retrieves all the permissions currently granted to the extension.
 - {{WebExtAPIRef("permissions.remove()")}}
-  - : Give up a set of permissions.
+  - : Givew up a set of permissions.
 - {{WebExtAPIRef("permissions.request()")}}
-  - : Ask for a set of permissions.
+  - : Asks for a set of permissions.
 
 ## Event handlers
 
 - {{WebExtAPIRef("permissions.onAdded")}}
-  - : Fired when a new permission is granted.
+  - : Fires when a user grants new permissions.
 - {{WebExtAPIRef("permissions.onRemoved")}}
-  - : Fired when a permission is removed.
+  - : Fires when a user revokes a permission.
 
 {{WebExtExamples("h2")}}
 

files/en-us/mozilla/add-ons/webextensions/api/permissions/onadded/index.md

@@ -6,7 +6,7 @@ browser-compat: webextensions.api.permissions.onAdded
 sidebar: addonsidebar
 ---
 
-Fired when the extension granted new permissions.
+Fires when the extension is granted permissions.
 
 ## Syntax
 
@@ -40,6 +40,9 @@ Events have three functions:
 function handleAdded(permissions) {
   console.log(`New API permissions: ${permissions.permissions}`);
   console.log(`New host permissions: ${permissions.origins}`);
+  console.log(
+    `New data collection permissions: ${permissions.data_collection}`,
+  );
 }
 
 browser.permissions.onAdded.addListener(handleAdded);

files/en-us/mozilla/add-ons/webextensions/api/permissions/onremoved/index.md

@@ -6,7 +6,7 @@ browser-compat: webextensions.api.permissions.onRemoved
 sidebar: addonsidebar
 ---
 
-Fired when some permissions are removed from the extension.
+Fires when permissions are removed from the extension.
 
 ## Syntax
 
@@ -21,9 +21,9 @@ 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.
+  - : Stops 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.
+  - : Checks whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.
 
 ## addListener syntax
 
@@ -40,6 +40,9 @@ Events have three functions:
 function handleRemoved(permissions) {
   console.log(`Removed API permissions: ${permissions.permissions}`);
   console.log(`Removed host permissions: ${permissions.origins}`);
+  console.log(
+    `Removed data collection permissions: ${permissions.data_collection}`,
+  );
 }
 
 browser.permissions.onRemoved.addListener(handleRemoved);

files/en-us/mozilla/add-ons/webextensions/api/permissions/permissions/index.md

@@ -10,12 +10,14 @@ A `Permissions` object represents a collection of permissions.
 
 ## Type
 
-An {{jsxref("object")}} with the following properties:
+An {{jsxref("object")}} with these properties:
 
 - `origins` {{optional_inline}}
   - : An array of [match patterns](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns), representing [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions).
 - `permissions` {{optional_inline}}
   - : An array of named permissions, including [API permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions) and [clipboard permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#clipboard_access).
+- `data_collection` {optional_inline}}
+  - : An array of [data collection permissions types](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings#data_collection_permissions).
 
 {{WebExtExamples}}
 

files/en-us/mozilla/add-ons/webextensions/api/permissions/remove/index.md

@@ -6,11 +6,9 @@ browser-compat: webextensions.api.permissions.remove
 sidebar: addonsidebar
 ---
 
-Ask to give up the permissions listed in the given {{WebExtAPIRef("permissions.Permissions")}} object.
+Revokes the permissions listed in a {{WebExtAPIRef("permissions.Permissions")}} object.
 
-The `Permissions` argument may contain either an `origins` property, which is an array of [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions), or a `permissions` property, which is an array of [API permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions), or both. Permissions must come from the set of permissions defined in the [`optional_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions) manifest.json key.
-
-This is an asynchronous function that returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
+Permissions must come from those defined in the extension's [`optional_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions) key or [`gecko.data_collection_permissions.optional`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings#optional) property of the `browser_specific_settings` key of its manifest.json file.
 
 ## Syntax
 
@@ -27,11 +25,11 @@ let removing = browser.permissions.remove(
 
 ### Return value
 
-A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that is fulfilled with `true` if the permissions listed in the `permissions` argument are now not granted to the extension, or `false` otherwise.
+A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) fulfilled with `true` if the browser is no longer granting the permissions listed in the `permissions` argument to the extension, or `false` otherwise.
 
 ## Examples
 
-This code adds a click handler that removes a given permission.
+This code adds a click handler that removes a permission.
 
 ```js
 const permissionToRemove = {