Extensions and the add-on ID

When do I need an add-on ID?

All Manifest V3 extensions need an add-on ID in their manifest.json when submitted to AMO.

For Manifest V2 extensions, you need to add an add-on ID 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.
• You use AMO's API for uploading your add-on, rather than uploading it manually on its page, you must include the add-on's ID in the request.
• 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 key. This applies to the following APIs:
  • storage.managed
  • storage.sync
  • identity.getRedirectURL
  • Native messaging
  • pkcs11
  • runtime.onMessageExternal
  • runtime.onConnectExternal
• You use the dictionaries key in manifest.json.

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

How do I set an add-on ID?

See browser_specific_settings in manifest.json for the syntax of setting the extension ID.

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.

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 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 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 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. 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.