Skip to content

Commit

Permalink
Update for general availability of MV3 (#1553)
Browse files Browse the repository at this point in the history 
Co-authored-by: William Durand <will+git@drnd.me>
  • Loading branch information
@rebloor @willdurand
rebloor and willdurand committed Mar 7, 2023
1 parent 97d7486 commit 0123eee
Show file tree
Hide file tree
Showing 4 changed files with 131 additions and 157 deletions.
125 changes: 68 additions & 57 deletions src/content/documentation/develop/extensions-and-the-add-on-id.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,24 +6,25 @@ topic: Develop
tags: [webextensions]
contributors:
[
Rob--W,
jsantell,
mdnwebdocs-bot,
andrewtruongmoz,
andymckay-github,
charmander,
DamienCassou,
freaktechnik,
wbamberg,
serv-inc,
scheinercc,
jsantell,
mconca,
DamienCassou,
andrewtruongmoz,
andymckay-github,
mdnwebdocs-bot,
rebloor,
Rob--W,
scheinercc,
serv-inc,
timdream,
Timendum,
willdurand,
wbamberg,
willdurand
]
last_updated_by: willdurand
date: 2022-05-17
last_updated_by: rebloor
date: 2023-03-03
---

<!-- Page Hero Banner -->
Expand All @@ -32,11 +33,11 @@ date: 2022-05-17

# Extensions and the add-on ID

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

This article describes how add-on IDs are handled for extensions that are built with WebExtensions APIs.
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 contain a unique identifier which is used both inside Firefox itself 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 this add-on.
This article describes how add-on IDs are handled for extensions built with WebExtensions APIs.

{% endcapture %}
{% include modules/page-hero.liquid,
Expand All @@ -47,42 +48,46 @@ Firefox add-ons contain a unique identifier which is used both inside Firefox it

<!-- Single Column Body Module -->

<section id="basic-workflow-with-no-add-on-id" class="module">
<aside class="module-aside table-of-contents">

{%- include contents.liquid -%}

</aside>
<section id="when-do-you-need-an-add-on-id" class="module">
<article class="module-content grid-x grid-padding-x">
<div class="cell small-12">

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

Extensions can explicitly set the add-on ID using the [`browser_specific_settings`](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings) key in manifest.json. However, this key is usually optional for Manifest V2 extensions. If you don't set it, then you can usually 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 will show a warning if you include it.

Note, though, that some WebExtension APIs use the add-on ID and expect it to be the same from one browser session to the next. If you use these APIs in Firefox, then you must set the ID explicitly using the [`browser_specific_settings`](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings) key. See [When do you need an Add-on ID?](#when-do-you-need-an-add-on-id).
## When do I need an add-on ID?

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

If your manifest.json does not contain an ID then the extension will be 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 will be used. If you then restart Firefox and load the add-on again, it will get a new ID.
For Manifest V2 extensions, you need to add an add-on ID when:

If you turn the extension into an `.xpi` or `.zip` and install it through `about:addons`, it will not work. To have it work in this scenario, you will need to add in the [`browser_specific_settings`](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings) key in `manifest.json`.
- 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/signing.html) 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`](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.')
- [`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/Mozilla/Add-ons/WebExtensions/manifest.json/dictionaries).

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

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 will generate one for you. It's only at this point that the add-on will be assigned a permanent ID, which will be embedded in the signed packaged extension.
</div>
</article>
</section>

### Updating
<!-- END: Single Column Body Module -->

Even after this point, though, you don't generally have to deal with the ID at all. 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 this particular add-on, even though it doesn't contain an ID.
<!-- Single Column Body Module -->

::: note
It's essential with this workflow that you update the add-on _manually using its page on AMO_, otherwise AMO will not understand that the submission is an update to an existing add-on, and will treat the update as a brand-new add-on.
:::
<section id="how-do-i-set-an-add-on-id" class="module">
<article class="module-content grid-x grid-padding-x">
<div class="cell small-12">

## What happens with Manifest V3?
## How do I set 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. Contrary to Manifest V2 extensions, AMO will not accept Manifest V3 extensions without an ID and it will not automatically embed this ID in the signed packaged extension.
See [`browser_specific_settings` in manifest.json](https://developer.mozilla.org/Add-ons/WebExtensions/manifest.json/browser_specific_settings) for the syntax of setting the extension ID.

</div>
</article>
Expand All @@ -92,35 +97,41 @@ All [Manifest V3 extensions](/documentation/develop/manifest-v3-migration-guide/

<!-- Single Column Body Module -->

<section id="when-do-you-need-an-add-on-id" class="module">
<section id="basic-workflow-with-no-add-on-id" class="module">
<aside class="module-aside table-of-contents">

{%- include contents.liquid -%}

</aside>
<article class="module-content grid-x grid-padding-x">
<div class="cell small-12">

## When do you need an add-on ID?
## Basic workflow with no add-on ID (Manifest V2)

All [Manifest V3 extensions](/documentation/develop/manifest-v3-migration-guide/) need an add-on ID in their manifest.json when submitted to AMO.
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.

For Manifest V2 extensions, you need an add-on ID when:
However, there are some implications of not setting an add-on ID that are described in this section.

- If you want to install an unsigned add-on from its XPI file, rather than loading it temporarily using `about:debugging`.
- If you want to have a value other than a randomly generated ID upon [getting your extension signed](/documentation/publish/#get-your-extension-signed) for the first time.
- If you use [AMO's API](https://addons-server.readthedocs.io/en/latest/topics/api/signing.html) for uploading your add-on, rather than uploading it manually on its page, then you need to include the add-on's ID in the request.
- Some WebExtension APIs use the add-on ID and expect it to be the same from one browser session to the next. If you use these APIs, then you must set the ID explicitly 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.')
- [`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.')
- Using the [`dictionaries` key in manifest.json](https://developer.mozilla.org/Mozilla/Add-ons/WebExtensions/manifest.json/dictionaries).
### Developing and debugging

See [`browser_specific_settings` in manifest.json](https://developer.mozilla.org/Add-ons/WebExtensions/manifest.json/browser_specific_settings) for the syntax of setting the extension 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.

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

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

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

</div>
</article>
</section>

<!-- END: Single Column Body Module -->


0 comments on commit 0123eee

Please sign in to comment.