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 |
|
|
kirinokirino |
2023-10-28 |
{% capture page_hero_banner_content %}
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 (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.
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 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: - You use the
dictionaries
key in manifest.json.
Otherwise, for Manifest V2 extensions, AMO adds an add-on ID during the signing process.
See browser_specific_settings
in manifest.json for the syntax of setting the extension ID.
{%- include contents.liquid -%}
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.
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
.
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.
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. :::