|
| 1 | +--- |
| 2 | +layout: sidebar |
| 3 | +title: Firefox built-in consent for data collection and transmission |
| 4 | +permalink: /documentation/develop/firefox-builtin-data-consent/ |
| 5 | +topic: Develop |
| 6 | +tags: [data-collection, data-transmission, api, permissions, firefox, guide] |
| 7 | +contributors: |
| 8 | + [ |
| 9 | + abyrne-moz, |
| 10 | + wagnerand, |
| 11 | + willdurand |
| 12 | + ] |
| 13 | +last_updated_by: wagnerand |
| 14 | +date: 2025-06-19 |
| 15 | +--- |
| 16 | + |
| 17 | +<!-- Page Hero Banner --> |
| 18 | + |
| 19 | +{% capture page_hero_banner_content %} |
| 20 | + |
| 21 | +# Firefox built-in consent for data collection and transmission |
| 22 | + |
| 23 | +::: note |
| 24 | +Firefox built-in consent for data collection and transmission is supported in Firefox for desktop 140 and later, and Firefox for Android 142 and above. |
| 25 | + |
| 26 | +Please follow our [community blog](https://blog.mozilla.org/addons/) for updates on the overall rollout process and a timeline when we will start accepting accepting submissions on AMO that make use of this feature. |
| 27 | +::: |
| 28 | + |
| 29 | +Developers can specify what data they wish to collect or transmit in their extensions `manifest.json` file. This information will be parsed by the browser and shown to the user when they first install the extension. A user can then choose to accept or reject the data collection, just like they do with extension permissions. The developer can also specify that the extension collects no data. |
| 30 | + |
| 31 | +{% endcapture %} |
| 32 | +{% include modules/page-hero.liquid, |
| 33 | + content: page_hero_banner_content |
| 34 | +%} |
| 35 | + |
| 36 | +<!-- END: Page Hero Banner --> |
| 37 | + |
| 38 | +<!-- Content with Table of Contents Module --> |
| 39 | + |
| 40 | +{% capture content_with_toc %} |
| 41 | + |
| 42 | +## Taxonomy |
| 43 | + |
| 44 | +To standardize this information for both developers and end users, Mozilla has created categories based on data types that extensions might be using today. In line with our [policies](/documentation/publish/add-on-policies/), there are two types of data: *Personal data*, and *Technical and Interaction data*. |
| 45 | + |
| 46 | +### Personal data |
| 47 | + |
| 48 | +Personally identifiable information can be actively provided by the user or obtained through extension APIs. It includes, but is not limited to names, email addresses, search terms and browsing activity data, as well as access to and placement of cookies. |
| 49 | + |
| 50 | +| Data type<br>Visible during install | Data collection permission**<br>Used in the manifest | Definition / Examples | |
| 51 | +|----------------------------------------|------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
| 52 | +| **Personally identifying information** | `personallyIdentifyingInfo` | Examples: contact information like name and address, email, and phone number, as well as other identifying data such as ID numbers, voice or video recordings, age, demographic information, or biometric data. | |
| 53 | +| **Health information** | `healthInfo` | Examples: medical history, symptoms, diagnoses, treatments, procedures, or heart rate data. | |
| 54 | +| **Financial and payment information** | `financialAndPaymentInfo` | Examples: credit card numbers, transactions, credit ratings, financial statements, or payment history. | |
| 55 | +| **Authentication information** | `authenticationInfo` | Examples: passwords, usernames, personal identification numbers (PINs), security questions, and registration information for extensions that offer account-based services. | |
| 56 | +| **Personal communications** | `personalCommunications` | Examples: emails, text or chat messages, social media posts, and data from phone calls and conference calls. | |
| 57 | +| **Location** | `locationInfo` | Examples: region, GPS coordinates, or information about things near a user’s device. | |
| 58 | +| **Browsing activity** | `browsingActivity` | Information about the websites you visit, like specific URLs, domains, or categories of pages you view over time. | |
| 59 | +| **Website content** | `websiteContent` | Covers anything visible on a website — such as text, images, videos, and links — as well as anything embedded like cookies, audio, page headers, request, and response information. | |
| 60 | +| **Website activity** | `websiteActivity` | Examples: interactions and mouse and keyboard activity like scrolling, clicking, typing, and covers actions such as saving and downloading. | |
| 61 | +| **Search terms** | `searchTerms` | Search terms entered into search engines. | |
| 62 | +| **Bookmarks** | `bookmarksInfo` | Information about Firefox bookmarks, including specific websites, bookmark names, and folder names. | |
| 63 | + |
| 64 | +### Technical and interaction data |
| 65 | + |
| 66 | +Technical data describes information about the environment the user is running, such as browser settings, platform information, and hardware properties. User interaction data includes how the user interacts with Firefox and the installed add-on, metrics for product improvement, and error information. |
| 67 | + |
| 68 | +| Data type<br>Visible during install | Data collection permission<br>Used in the manifest | Definition / Examples | |
| 69 | +|-------------------------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------| |
| 70 | +| **Technical and interaction data** | `technicalAndInteraction` | Examples: Device and browser info, extension usage and settings data, crash and error reports. | |
| 71 | + |
| 72 | +{% endcapture %} |
| 73 | +{% include modules/column-w-toc.liquid, |
| 74 | + id: "taxonomy" |
| 75 | + content: content_with_toc |
| 76 | +%} |
| 77 | + |
| 78 | +<!-- END: Content with Table of Contents --> |
| 79 | + |
| 80 | +<!-- Single Column Body Module --> |
| 81 | + |
| 82 | +{% capture content %} |
| 83 | + |
| 84 | +## Specifying data types |
| 85 | + |
| 86 | +You specify data types your extension transmits in the `browser_specific_settings.gecko.data_collection_permissions` key in the `manifest.json` file. As a reminder, our policies state that data transmission refers to any data that is collected, used, transferred, shared, or handled outside of the add-on or the local browser. |
| 87 | + |
| 88 | +### Personal data |
| 89 | + |
| 90 | +Personal data permissions can either be required or optional (only `technicalAndInteraction` cannot be required, see the documentation further down): |
| 91 | + |
| 92 | +```json |
| 93 | +"browser_specific_settings": { |
| 94 | + "gecko": { |
| 95 | + "data_collection_permissions": { |
| 96 | + "required": [...], |
| 97 | + "optional": [...] |
| 98 | + } |
| 99 | + } |
| 100 | +} |
| 101 | +``` |
| 102 | + |
| 103 | +The rest of this section describes each key in the `data_collection_permissions` object. |
| 104 | + |
| 105 | +#### Required data |
| 106 | + |
| 107 | +When types of data are specified in the required list, users must opt in to this data collection to use the extension. Users cannot opt-out, and Figure 1 gives an example of how it could look. If a user does not agree to the data collection the extension is not installed. This gives the user a chance to review the data collection requirements of an extension before it is installed in their browser. |
| 108 | + |
| 109 | +In the example `manifest.json` file below, the developer specifies a single type of required data: `locationInfo`. |
| 110 | + |
| 111 | +```json |
| 112 | +{ |
| 113 | + "manifest_version": 2, |
| 114 | + "name": "Example - Data collection with fallback", |
| 115 | + "version": "1.0.0", |
| 116 | + "permissions": [ |
| 117 | + "storage", |
| 118 | + "management" |
| 119 | + ], |
| 120 | + "browser_specific_settings": { |
| 121 | + "gecko": { |
| 122 | + |
| 123 | + "data_collection_permissions": { |
| 124 | + "required": [ |
| 125 | + "locationInfo" |
| 126 | + ], |
| 127 | + "optional": [ |
| 128 | + "technicalAndInteraction" |
| 129 | + ] |
| 130 | + } |
| 131 | + } |
| 132 | + }, |
| 133 | + "background": { |
| 134 | + "scripts": [ |
| 135 | + "background.js" |
| 136 | + ] |
| 137 | + }, |
| 138 | + "browser_action": {}, |
| 139 | + "options_ui": { |
| 140 | + "page": "options/page.html" |
| 141 | + } |
| 142 | +} |
| 143 | +``` |
| 144 | + |
| 145 | +This results in a new paragraph in the installation prompt (see Figure 1). The data permissions are also listed in `about:addons` as shown in Figure 2. |
| 146 | + |
| 147 | + |
| 148 | +*Figure 1: Installation prompt with data types as specified in the manifest* |
| 149 | + |
| 150 | + |
| 151 | +*Figure 2: The data permissions are also listed in about:addons* |
| 152 | + |
| 153 | +#### Optional data |
| 154 | + |
| 155 | +Optional data collection permissions can be specified using the optional list. These are not surfaced during installation (except `technicalAndInteraction`; see next section), and they are not granted by default. The extension can request the user opts in to this data collection after installation via a prompt, and the user can enable or disable this option data collection at any time in `about:addons` in the *Permissions and data* section of the extension settings. |
| 156 | + |
| 157 | +### Technical and interaction data |
| 158 | + |
| 159 | +The `technicalAndInteraction` data type behaves differently compared to all others. This data permission can only be optional, but unlike other optional data collection options the user has the opportunity to enable or disable this during the installation flow. In Figure 1 above, this choice is available in the optional settings section of the installation prompt. |
| 160 | + |
| 161 | +### No data collection |
| 162 | + |
| 163 | +If an extension does not collect or transmit any data, developers should explicitly indicate that by specifying the `none` required permission in the manifest, as follows: |
| 164 | + |
| 165 | +```json |
| 166 | +{ |
| 167 | + "manifest_version": 2, |
| 168 | + "name": "extension without data collection", |
| 169 | + "version": "1.0.0", |
| 170 | + "browser_specific_settings": { |
| 171 | + "gecko": { |
| 172 | + "id": "@extension-without-data-collection", |
| 173 | + "data_collection_permissions": { |
| 174 | + "required": ["none"] |
| 175 | + } |
| 176 | + } |
| 177 | + }, |
| 178 | + "permissions": [ |
| 179 | + "bookmarks", |
| 180 | + "<all_urls>" |
| 181 | + ] |
| 182 | +} |
| 183 | +``` |
| 184 | + |
| 185 | +When a user attempts to install this extension, Firefox will show the usual installation prompt with the description of the required (API) permissions as well as a new description to indicate that the extension does not collect any data (see Figure 3). |
| 186 | + |
| 187 | + |
| 188 | +*Figure 3: Installation prompt with no data transmission defined in the manifest* |
| 189 | + |
| 190 | +The "no data collected" type is also listed in the *Permissions and data* tab of the extension in `about:addons` as shown in Figure 4. |
| 191 | + |
| 192 | + |
| 193 | +*Figure 4: The "no data collected" permission is listed in about:addons* |
| 194 | + |
| 195 | +{% endcapture %} |
| 196 | +{% include modules/one-column.liquid, |
| 197 | + id: "specifying-data-types" |
| 198 | + content: content |
| 199 | +%} |
| 200 | + |
| 201 | +{% capture content %} |
| 202 | + |
| 203 | +## Accessing the data collection permissions programmatically |
| 204 | + |
| 205 | +Extension developers can use the [`browser.permissions` API](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/permissions) to interact with the optional data permissions. Specifically, the `getAll()` method returns the list of granted optional data permissions as follows: |
| 206 | + |
| 207 | +```js |
| 208 | +await browser.permissions.getAll() |
| 209 | + |
| 210 | +{ |
| 211 | + origins: ["<all_urls>"], |
| 212 | + permissions: ["bookmarks"], |
| 213 | + // In this case, the permission is granted. |
| 214 | + data_collection: ["technicalAndInteraction"] |
| 215 | +} |
| 216 | +``` |
| 217 | + |
| 218 | +The presence/absence of the `data_collection` key in the response of the `getAll()` method can also be used to feature-detect the built-in data collection consent experience in Firefox at runtime. |
| 219 | + |
| 220 | +```js |
| 221 | +const perms = await browser.permissions.getAll(); |
| 222 | +if (!perms.data_collection) { |
| 223 | + // no built-in data consent in Firefox |
| 224 | +} |
| 225 | +``` |
| 226 | + |
| 227 | +Extension developers can use the [`browser.permissions.request()`](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/API/permissions/request) API method (MDN docs) to get consent from users for ancillary data collection (defined in the optional list): |
| 228 | + |
| 229 | +```js |
| 230 | +await browser.permissions.request({ data_collection: ["healthInfo"] }); |
| 231 | +``` |
| 232 | + |
| 233 | +This will show the following message to the Firefox user, giving them the choice to opt in to this data collection or not (Figure 5) |
| 234 | + |
| 235 | + |
| 236 | +*Figure 5: Prompt when requesting data collection permissions programmatically* |
| 237 | + |
| 238 | +{% endcapture %} |
| 239 | +{% include modules/one-column.liquid, |
| 240 | + id: "acessing-data-permissions-programmatically" |
| 241 | + content: content |
| 242 | +%} |
| 243 | + |
| 244 | +{% capture content %} |
| 245 | + |
| 246 | +## Updates |
| 247 | + |
| 248 | +When an extension is updated, Firefox will only show the newly added required data permissions, unless it’s the special `none` data type because when the extension does not collect any data, that does not need to be exposed to the user. |
| 249 | + |
| 250 | +{% endcapture %} |
| 251 | +{% include modules/one-column.liquid, |
| 252 | + id: "updates" |
| 253 | + content: content |
| 254 | +%} |
0 commit comments