• Skip to main content
  • Select language
  • Skip to search
MDN Web Docs
  • Technologies
    • HTML
    • CSS
    • JavaScript
    • Graphics
    • HTTP
    • APIs / DOM
    • WebExtensions
    • MathML
  • References & Guides
    • Learn web development
    • Tutorials
    • References
    • Developer Guides
    • Accessibility
    • Game development
    • ...more docs
Add-ons
  1. MDN
  2. Mozilla
  3. Add-ons
  4. Browser extensions
  5. Extensions and the add-on ID

Extensions and the add-on ID

In This Article
  1. Basic workflow with no add-on ID
    1. Developing and debugging
    2. Publishing
    3. Updating
  2. When do you need an add-on ID?

Firefox add-ons contain a unique ID which is used to distinguish this 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 add-ons contain a unique identifier which is used both inside Firefox itself 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 this add-on.

With older types of Firefox add-on, the add-on developer must set the add-on ID explicitly. XUL/XPCOM add-ons set the ID in the install manifest, while SDK add-ons set it in the package.json.

However, from Firefox 48 you can develop, debug, publish, and update extensions without needing to set an explicit ID at all.

Note that the ability to develop and debug WebExtensions that don't include an ID is new in Firefox 48. If you need to use an earlier version of Firefox, then you must use the applications key to set an ID explicitly.

Basic workflow with no add-on ID

Extensions can be set explicitly set the add-on ID using the applications key in manifest.json. However, this key is usually optional. 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 applications 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 applications key. See When do you need an Add-on ID?.

Developing and debugging

Starting in Firefox 48, 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 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.

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

Note that once an extension has been given a permanent ID, you can't then update it to use the Add-on SDK or legacy XUL/XPCOM techniques. If you do switch to one of these platforms, you must submit it as a distinct new add-on, with a new ID.

Updating

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.

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.

You can do the same thing if you are updating from an older add-on type, such as a XUL/XPCOM add-on, to use WebExtensions APIs. Just visit the old add-on's page on AMO, upload the new extension there, and it will be treated as an update to the old version.

When do you need an add-on ID?

  • If you are loading the add-on from it's XPI file, are not loading it temporarily using about:debugging and it is not signed.
  • If you use AMO's API 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 applications key. This applies to the following APIs:
    • storage.sync
    • identity.getRedirectURL
    • Native messaging

 

 

 

Document Tags and Contributors

Tags: 
  • WebExtensions
 Contributors to this page: DamienCassou, andrewtruongmoz, andymckay-github, timdream, wbamberg, Timendum
 Last updated by: DamienCassou, Jul 20, 2017, 7:50:52 AM
See also
  1. Browser extensions
  2. Getting started
    1. What are extensions?
    2. Your first extension
    3. Your second extension
    4. Anatomy of an extension
    5. Example extensions
  3. How to
    1. Intercept HTTP requests
    2. Modify a web page
    3. Add a button to the toolbar
    4. Implement a settings page
  4. User interface
    1. Introduction
    2. Toolbar button
    3. Address bar button
    4. Sidebar
    5. Context menu items
    6. Options page
    7. Bundled web pages
    8. Notifications
    9. Address bar suggestions
    10. Developer tools panels
  5. Concepts
    1. Using the JavaScript APIs
    2. Content scripts
    3. Match patterns
    4. Internationalization
    5. Content Security Policy
    6. Native messaging
  6. Porting
    1. Porting a Google Chrome extension
    2. Porting a legacy Firefox extension
    3. Embedded WebExtensions
    4. Comparison with the Add-on SDK
    5. Comparison with XUL/XPCOM extensions
    6. Chrome incompatibilities
    7. Differences between desktop and Android
  7. Firefox workflow
    1. Temporary Installation in Firefox
    2. Debugging
    3. Developing for Firefox for Android
    4. Getting started with web-ext
    5. web-ext command reference
    6. Extensions and the Add-on ID
    7. Publishing your extension
  8. JavaScript APIs
    1. Browser support for JavaScript APIs
    2. alarms
    3. bookmarks
    4. browserAction
    5. browserSettings
    6. browsingData
    7. commands
    8. contextMenus
    9. contextualIdentities
    10. cookies
    11. devtools.inspectedWindow
    12. devtools.network
    13. devtools.panels
    14. downloads
    15. events
    16. extension
    17. extensionTypes
    18. history
    19. i18n
    20. identity
    21. idle
    22. management
    23. notifications
    24. omnibox
    25. pageAction
    26. permissions
    27. privacy
    28. proxy
    29. runtime
    30. sessions
    31. sidebarAction
    32. storage
    33. tabs
    34. theme
    35. topSites
    36. types
    37. webNavigation
    38. webRequest
    39. windows
  9. Manifest keys
    1. applications
    2. author
    3. background
    4. browser_action
    5. chrome_settings_overrides
    6. chrome_url_overrides
    7. commands
    8. content_scripts
    9. content_security_policy
    10. default_locale
    11. description
    12. developer
    13. devtools_page
    14. homepage_url
    15. icons
    16. incognito
    17. manifest_version
    18. name
    19. omnibox
    20. optional_permissions
    21. options_ui
    22. page_action
    23. permissions
    24. protocol_handlers
    25. short_name
    26. sidebar_action
    27. theme
    28. version
    29. web_accessible_resources
  10. Themes
  11. Publishing add-ons
  12. Guides
    1. Signing and distribution overview
    2. Submit an add-on
    3. Creating an appealing listing
    4. Review policies
    5. Developer agreement
    6. Featured add-ons
    7. Contact addons.mozilla.org
  13. Community and support
  14. Channels
    1. Add-ons blog
    2. Add-on forums
    3. Stack Overflow
    4. Development newsgroup
    5. IRC Channel
  15. Legacy add-ons
  16. Legacy technologies
    1. Add-on SDK
    2. Legacy Firefox for Android
    3. Bootstrapped extensions
    4. Overlay extensions