| layout | title | permalink | topic | tags | contributors | last_updated_by | date | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
sidebar |
Extensions and the Add-on ID |
/documentation/develop/extensions-and-the-add-on-id/ |
Develop |
|
|
andrewbaxter |
2025-03-10 |
{% capture page_hero_banner_content %}
Firefox add-ons are distinguished by a unique ID. These unique IDs are used inside Firefox and on the 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.
{% endcapture %} {% include modules/page-hero.liquid, content: page_hero_banner_content %}
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 you must add an ID to your extension's manifest.json file before it's submitted to AMO (online or using web-ext sign or the AMO API create endpoint).
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).
When you submit an add-on to AMO with an ID defined, AMO checks that the ID is unique.
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 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:
- You use the
dictionarieskey in manifest.json.
See browser_specific_settings in manifest.json for the syntax of setting the extension ID.
{%- include contents.liquid -%}
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.
However, there are some implications of not setting an add-on ID that are described in this section.
If your manifest.json does not contain an ID, the extension is assigned a randomly-generated temporary ID when you install it 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 does not work. For it to work, you must add the browser_specific_settings key in manifest.json.
When you have finished developing the extension, you can package it and submit it to AMO for review and signing. 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.
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.
However, if you use AMO's API 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.