Skip to content

Clarify extension ID creation #2022

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: master
Choose a base branch
from
Open

Clarify extension ID creation #2022

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
6e2f6f3
Clarify extension ID creation
andrewbaxter Mar 4, 2025
5cbdc0a
Further ID clarifications
rebloor Mar 9, 2025
8fc15ec
Merge branch 'master' into master
rebloor Mar 10, 2025
a7a8246
Contributer list fix
rebloor Mar 10, 2025
8199a80
Apply suggestions from review
rebloor Mar 12, 2025
9798611
Use term create and fix minor issues
rebloor Mar 12, 2025
c937d9e
Clarification of ID assignment
rebloor Mar 14, 2025
1e07fd1
Blanket recommendation to define ID upfront
rebloor Mar 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 27 additions & 24 deletions src/content/documentation/develop/extensions-and-the-add-on-id.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,11 @@ contributors:
willdurand,
djbrown,
kirinokirino,
dotproto
dotproto,
andrewbaxter
]
last_updated_by: dotproto
date: 2024-08-21
last_updated_by: andrewbaxter
date: 2025-03-10
---

<!-- Page Hero Banner -->
Expand All @@ -35,9 +36,7 @@ date: 2024-08-21

# Extensions and the add-on ID

Firefox add-ons contain a unique ID that is used to distinguish one add-on from any other Firefox add-on.

Firefox uses an extension's unique ID inside Firefox and on the [addons.mozilla.org](https://addons.mozilla.org/) (AMO) website. For example, it's used by Firefox to check for updates to installed add-ons and to identify which objects (such as data stores) are controlled by the add-on.
Firefox add-ons are distinguished by a unique ID. These unique IDs are used inside Firefox and on the [addons.mozilla.org](https://addons.mozilla.org/) (AMO) website. For example, they are used by Firefox to check for updates to installed add-ons and to identify which objects (such as data stores) are controlled by the add-on.

This article describes how add-on IDs are handled for extensions built with WebExtensions APIs.

Expand All @@ -56,25 +55,31 @@ This article describes how add-on IDs are handled for extensions built with WebE

## When do I need an add-on ID?

All [Manifest V3 extensions](/documentation/develop/manifest-v3-migration-guide/) need an add-on ID in their manifest.json when submitted to AMO.
### Signing and publishing

All signed add-ons have a unique ID. It's recommended that you define an extension ID and add it to your extension's manifest.json file when you begin development.

For [Manifest V3 extensions](/documentation/develop/manifest-v3-migration-guide/) you must add an ID to your extension's manifest.json file before it's submitted to AMO ([online](/documentation/publish/submitting-an-add-on/) or using [`web-ext sign`](/documentation/develop/web-ext-command-reference/#web-ext-sign) or the [AMO API create endpoint](https://mozilla.github.io/addons-server/topics/api/addons.html#create)).

If you don't add an ID to a Manifest V2 extension before submission, AMO assigns your extension an ID when you submit it to AMO (online or using `web-ext sign` or the AMO API create endpoint).

For Manifest V2 extensions, you need to add an add-on ID when:
When you submit an add-on to AMO with an ID defined, AMO checks that the ID is unique.

### Development and testing

You need to set an ID in your extensions manifest.json file when:

- You want to install an unsigned add-on from its XPI file, rather than loading it temporarily using `about:debugging`.
- You want a specific ID, rather than one randomly generated when [your extension is first signed](/documentation/publish/#get-your-extension-signed).
- You use [AMO's API](https://addons-server.readthedocs.io/en/latest/topics/api/v4_frozen/signing.html) or the [web-ext](/documentation/develop/getting-started-with-web-ext/) CLI tool when submitting updates to AMO.
- You use WebExtension APIs that use the add-on ID and expect it to be the same from one browser session to the next. If you use these APIs, you must explicitly set the ID using the [`browser_specific_settings`](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings) key. This applies to the following APIs:
- [`storage.managed`](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/API/storage/managed "A storage.StorageArea object that represents the managed storage area. Items in managed storage are set by the domain administrator or other native applications installed on user's computer, and are read-only for the extension. Trying to modify this storage area results in an error.")
- [`storage.sync`](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/API/storage/sync 'Represents the sync storage area. Items in sync storage are synced by the browser, and are available across all instances of that browser that the user is logged into (e.g. via Firefox sync, or a Google account), across different devices.')
- You use these WebExtension APIs that rely on the add-on ID and expect it to be the same from one browser session to the next:
- [`storage.managed`](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/API/storage/managed "A storage.StorageArea object that represents the managed storage area. Items in managed storage are set by the domain administrator or other native applications installed on the user's computer and are read-only for the extension. Trying to modify this storage area results in an error.")
- [`storage.sync`](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/API/storage/sync 'Represents the sync storage area. Items in sync storage are synced by the browser and are available across all instances of that browser that the user is logged into (e.g. using Firefox sync, or a Google account), across different devices.')
- [`identity.getRedirectURL`](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/API/identity/getRedirectURL 'Generates a URL that you can use as a redirect URL.')
- [Native messaging](https://developer.mozilla.org/Add-ons/WebExtensions/Native_messaging)
- [`pkcs11`](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/API/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.')
- [`runtime.onMessageExternal`](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onMessageExternal "This API can't be used in a content script.")
- [`runtime.onConnectExternal`](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onConnectExternal 'Fired when an extension receives a connection request from a different extension.')
- You use the [`dictionaries` key in manifest.json](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/manifest.json/dictionaries).

Otherwise, for Manifest V2 extensions, AMO adds an add-on ID during the signing process.

</div>
</article>
</section>
Expand Down Expand Up @@ -107,30 +112,28 @@ See [`browser_specific_settings` in manifest.json](https://developer.mozilla.org
</aside>
<article class="module-content grid-x grid-padding-x">
<div class="cell small-12">

## Working without an ID in Manifiest V2

## Basic workflow with no add-on ID (Manifest V2)

An add-on ID is usually optional for Manifest V2 extensions. If you don't set it, you can generally develop, debug, publish, and update your extension without ever having to deal with an ID. One advantage of this is that Google Chrome does not recognize the `browser_specific_settings` key and shows a warning if you include it.
An add-on ID is optional for Manifest V2 extensions. If you don't set it, you can generally develop, debug, publish, and update your extension without ever having to deal with an ID. One advantage of this is that Google Chrome does not recognize the `browser_specific_settings` key and shows a warning if you include it.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One advantage of this is that Google Chrome does not recognize the browser_specific_settings key and shows a warning if you include it.

That doesn't sound right or great if true. Isn't bss supposed to be designed exactly for this purpose?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dotproto I've taken one of the Chrome extension examples and added browser_specific_settings to it, then loaded it as an unpacked file. Chrome reported no errors or warnings. Can you confirm the statement about a warning in Chrome for browser_specific_settings is incorrect/updated?


However, there are some implications of not setting an add-on ID that are described in this section.

### Developing and debugging

If your manifest.json does not contain an ID, the extension is assigned a randomly-generated temporary ID when you [install it in Firefox](/documentation/develop/temporary-installation-in-firefox/) through `about:debugging`. If you then reload the extension using the "Reload" button, the same ID is used. If you restart Firefox and load the add-on again, it gets a new ID.
If your manifest.json does not contain an ID, the extension is assigned a randomly-generated temporary ID when you [install it in Firefox](/documentation/develop/temporary-installation-in-firefox/) through `about:debugging`. If you then reload the extension using the "Reload" button, the same ID is used. If you restart Firefox and load the add-on again, it gets a new ID. This affects the APIs listed in [Development and testing](#development-and-testing].

If you turn the extension into an `.xpi` or `.zip` and install it through `about:addons`, it will not work. For it to work, you must add the [`browser_specific_settings`](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings) key in `manifest.json`.
If you turn the extension into an `.xpi` or `.zip` and install it through `about:addons`, it does not work. For it to work, you must add the [`browser_specific_settings`](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings) key in `manifest.json`.

### Publishing

Once you have finished developing the extension, you can [package it and submit it to AMO for review and signing](/documentation/publish/signing-and-distribution-overview/). If the packaged extension you upload does not contain an ID, AMO generates one. It's only at this point that the add-on is assigned a permanent ID, which is embedded in the signed packaged extension.
When you have finished developing the extension, you can [package it and submit it to AMO for review and signing](/documentation/publish/signing-and-distribution-overview/). If the packaged extension you upload does not contain an ID, AMO generates one. It's only at this point that the add-on is assigned a permanent ID, which is embedded in the signed packaged extension.

### Updating

After publication, you don't generally have to deal with the ID. You can continue to develop the add-on without an ID, and when you want to update, upload the new version by visiting the add-on's AMO page. Because you are uploading the add-on through that page, AMO knows that this is an update to the add-on, even though it doesn't contain an ID.

::: note
With this workflow, you must update the add-on _manually using its page on AMO_. Otherwise, AMO does not understand that the submission is an update to an existing add-on and treats the update as a new add-on.
:::
However, if you use [AMO's API](https://addons-server.readthedocs.io/en/latest/topics/api/v4_frozen/signing.html) to upload an update to a Manifiest V2 extension that doesn't define the ID in its manifest.json file you must include the add-on's ID in the request.

</div>
</article>
Expand Down