Extensions and the add-on ID
Firefox add-ons are distinguished by a unique ID. These unique IDs are used inside Firefox and on theaddons.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.
When do I need an add-on ID?
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.
ForManifest V3 extensions you must add an ID to your extension's manifest.json file before it's submitted to AMO (online or usingweb-ext sign or theAMO 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 usingweb-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.
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 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.
How do I set an add-on ID?
Seebrowser_specific_settings in manifest.json for the syntax of setting the extension ID.
Working without an ID in Manifest V2
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. However, if you do add thebrowser_specific_settings manifest key (to add an ID), Google Chrome ignores it, and Apple Safari ignores Firefox'sgecko andgecko_android sub-keys.
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 youinstall it in Firefox throughabout: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 throughabout:addons, it does not work. For it to work, you must add thebrowser_specific_settings key inmanifest.json.
Publishing
When you have finished developing the extension, you canpackage 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.
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.
However, if you useAMO's API to upload an update to a Manifest V2 extension that doesn't define the ID in its manifest.json file you must include the add-on's ID in the request.
Tags: webextensions
Contributors: andrewtruongmoz andymckay-github charmander DamienCassou freaktechnik jsantell mconca rebloor Rob--W scheinercc serv-inc timdream Timendum wbamberg willdurand djbrown kirinokirino dotproto andrewbaxter dotproto
Last update: dotproto
Up Next
Develop
Build a secure extension
Develop
Request the right permissions
Develop