Add-ons

AddonManager

Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.

From Firefox 53 onwards, no new legacy add-ons will be accepted on addons.mozilla.org (AMO).

From Firefox 57 onwards, WebExtensions will be the only supported extension type, and Firefox will not load other types.

Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to WebExtensions if they can. See the "Compatibility Milestones" document for more.

A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.

The AddonManager object is the global API used to access information about add-ons installed in the application and to manipulate them. The majority of the methods are asynchronous meaning that results are delivered through callbacks passed to the method. The callbacks will be called just once but that may be before or after the method returns.

One of the forces of the AddonManager is that it deals with any kind (type) of add-on in a generic manner. To do so many methods of the AddonManager take the add-on types as parameters. The existing add-on types are defined in XPIProvider.jsm and are, at this time, the following: extension, theme, locale, multipackage, dictionary and experiment.

To import the AddonManager object in the Add-on SDK, use:

const { AddonManager } = require("resource://gre/modules/AddonManager.jsm");

To import it in a normal bootstrapped extension or similar, use:

Cu.import("resource://gre/modules/AddonManager.jsm");

Method Overview

Promise? getInstallForURL(in string url, in InstallCallback? callback, in string mimetype, in string hash, in string name, in string iconURL, in string version, in nsILoadGroup loadGroup)
Promise? getInstallForFile(in nsIFile file, in InstallCallback? callback, in string mimetype)
Promise? getAllInstalls(in InstallListCallback? callback)
Promise? getInstallsByTypes(in string types[], in InstallListCallback? callback)
void installAddonsFromWebpage(in string mimetype, in nsIDOMWindow source, in nsIURI uri, in AddonInstall installs[])
void addInstallListener(in InstallListener listener)
void removeInstallListener(in InstallListener listener)
Promise? getAllAddons(in AddonListCallback? callback)
Promise? getAddonByID(in string id, in AddonCallback? callback)
Promise? getAddonBySyncGUID(in string id, in AddonCallback? callback)
Promise? getAddonsByIDs(in string ids[], in AddonListCallback? callback)
Promise? getAddonsByTypes(in string types[], in AddonListCallback? callback)
Promise? getAddonsWithOperationsByTypes(in string types[], in AddonListCallback? callback)
void addAddonListener(in AddonListener listener)
void removeAddonListener(in AddonListener listener)
void addTypeListener(in TypeListener listener)
void removeTypeListener(in TypeListener listener)
nsIURI getURIForResourceInFile(in nsIFile aFile, in string aPath)

Properties Overview

Attribute Type Description
addonTypes dictionary A dictionary that maps type ID to AddonType.
autoUpdateDefault boolean Whether add-ons should auto-update by default (overrideable per add-on). Corresponds to the extensions.autoUpdateDefault preference.

Callbacks

InstallCallback()

A callback that is passed a single AddonInstall

void InstallCallback(
  in AddonInstall install
)
Parameters
install
The AddonInstall passed back from the asynchronous request

InstallListCallback()

A callback that is passed an array of AddonInstalls

void InstallListCallback(
  in AddonInstall installs[]
)
Parameters
installs
The array of AddonInstalls passed back from the asynchronous request

AddonCallback()

A callback that is passed a single Addon

void AddonCallback(
  in Addon addon
)
Parameters
addon
The Addon passed back from the asynchronous request. If an error occurred (such as an add-on not being found), null is passed back instead.

AddonListCallback()

A callback that is passed an array of Addons

void AddonListCallback(
  in Addon addons[]
)
Parameters
addons
The array of Addons passed back from the asynchronous request

Constants

AddonInstall states

Constant Description
STATE_AVAILABLE An install that is waiting to be started.
STATE_DOWNLOADING An install that is in the process of being downloaded.
STATE_CHECKING An install that is checking for updated information.
STATE_DOWNLOADED An install that has finished downloading and is ready to install.
STATE_DOWNLOAD_FAILED An install that failed to download.
STATE_INSTALLING An install that is in the process of being installed.
STATE_INSTALLED An install that has successfully been installed.
STATE_INSTALL_FAILED An install that has failed to install.
STATE_CANCELLED An install that has been canceled.

AddonInstall errors

Constant Description
ERROR_NETWORK_FAILURE A network error occurred.
ERROR_INCORRECT_HASH The downloaded file did not match the expected hash.
ERROR_CORRUPT_FILE The file appears to be corrupt.
ERROR_FILE_ACCESS There was an error accessing the filesystem.
ERROR_SIGNEDSTATE_REQUIRED The addon must be signed and isn't.

Update check reasons

Constant Description
UPDATE_WHEN_USER_REQUESTED An update check performed at the explicit request of the user.
UPDATE_WHEN_NEW_APP_DETECTED An update check performed when a new version of the application has been detected.
UPDATE_WHEN_NEW_APP_INSTALLED An update check performed after a new version of the application has been installed.
UPDATE_WHEN_PERIODIC_UPDATE An update check performed automatically in the background.
UPDATE_WHEN_ADDON_INSTALLED An update check performed when a new add-on has been installed.

Update status values

Constant Description
UPDATE_STATUS_NO_ERROR No error was encountered.
UPDATE_STATUS_TIMEOUT The update check timed out.
UPDATE_STATUS_DOWNLOAD_ERROR There was an error while downloading the update information.
UPDATE_STATUS_PARSE_ERROR The update information was malformed in some way.
UPDATE_STATUS_UNKNOWN_FORMAT The update was not in any known format.
UPDATE_STATUS_SECURITY_ERROR The update information was not correctly signed or there was an SSL error.

Auto update values

Constant Description
AUTOUPDATE_DISABLE Indicates that the add-on should not update automatically.
AUTOUPDATE_DEFAULT Indicates that the add-on should update automatically only if that's the global default.
AUTOUPDATE_ENABLE Indicates that the add-on should update automatically.

Pending operations

Constant Description
PENDING_NONE No operations are pending.
PENDING_ENABLE This add-on will be enabled after the application restarts.
PENDING_DISABLE This add-on will be disabled after the application restarts.
PENDING_UNINSTALL This add-on will be uninstalled after the application restarts.
PENDING_INSTALL This add-on will be installed after the application restarts.
PENDING_UPGRADE This add-on will be upgraded after the application restarts.

Permissions

Constant Description
PERM_CAN_UNINSTALL This add-on can be uninstalled.
PERM_CAN_ENABLE This add-on can be enabled.
PERM_CAN_DISABLE This add-on can be disabled.
PERM_CAN_UPGRADE This add-on can be upgraded.

Operations requiring restart

Constant Description
OP_NEEDS_RESTART_NONE No operations will require a restart.
OP_NEEDS_RESTART_ENABLE Enabling the add-on will require a restart.
OP_NEEDS_RESTART_DISABLE Disabling the add-on will require a restart.
OP_NEEDS_RESTART_UNINSTALL Uninstalling the add-on will require a restart.
OP_NEEDS_RESTART_INSTALL Installing the add-on will require a restart.

Installation scopes

Constant Value Description
SCOPE_ALL 15 A combination of all the installation scopes.
SCOPE_APPLICATION 4 This add-on is a part of the current application (Installed and owned by Firefox).
SCOPE_PROFILE 1 This add-on is installed in the current profile directory.
SCOPE_SYSTEM 8 This add-on is installed somewhere global to the system (installed for all users of the computer).
SCOPE_USER 2 This add-on is installed somewhere specific to the current user (all profiles of the logged-in user).
Note: The extensions.enabledScopes preference lets you configure which of these scopes are enabled; however, you can't turn off the profile scope. Starting in Firefox 8 (Firefox 8.0 / Thunderbird 8.0 / SeaMonkey 2.5), you can also set the value of the preference extensions.autoDisabledScopes to prevent Firefox from automatically installing add-ons from the specified scopes.

AddonType viewTypes

Requires Gecko 6.0(Firefox 6.0 / Thunderbird 6.0 / SeaMonkey 2.3)

Constant Description
VIEW_TYPE_LIST The type should be displayed in a regular list view in the UI.

AddonType flags

Requires Gecko 6.0(Firefox 6.0 / Thunderbird 6.0 / SeaMonkey 2.3)

Constant Description
TYPE_UI_HIDE_EMPTY The type should be hidden from the UI if no add-ons of that type are currently installed.

Startup change types

Requires Gecko 7.0(Firefox 7.0 / Thunderbird 7.0 / SeaMonkey 2.4)

These constants represent the lists of types of changes that can occur to add-ons during startup; they're used with the getStartupChanges(), addStartupChange(), and removeStartupChange() methods.

Constant Description
STARTUP_CHANGE_INSTALLED A list of add-ons that were detected as newly-installed during application startup. This doesn't include add-ons that were awaiting installation the last time the application was running.
STARTUP_CHANGE_CHANGED A list of add-ons that were detected as having changed during startup. This includes an add-on being moved to a new location, changing version, or having been detected as possibly altered.
STARTUP_CHANGE_UNINSTALLED A list of add-ons that were detected as having been uninstalled during startup. This doesn't include add-ons for which uninstall was pending the last time the application was running.
STARTUP_CHANGE_DISABLED A list of add-ons that were detected as having become disabled during startup. This normally means the application determined that the add-on is incompatible. This doesn't include add-ons that were pending becoming disabled the last time the application was running.
STARTUP_CHANGE_ENABLED A list of add-ons that were detected as having become enabled during startup. This normally means the application determined that an application change has made the add-on compatible. This doesn't include add-ons that were pending becoming enabled the last time the application was running.

Methods

addStartupChange()

Adds an add-on change from the add-on changes list. This is used to build the lists of changed add-ons reported by the getStartupChanges() method.

Note: Calling this method more than once for the same add-on will replace the last change that was recorded with the new one; an add-on can only appear once across all change types.
void addStartupChange(
  in string changeType,
  in string id
);
Parameters
changeType
The type of change that occurred for the specified add-on. This can be one of the Startup change types or a custom value defined by your own provider.
id
The add-on ID to add to the change list.

removeStartupChange()

Removes an add-on from the add-on changes list.

void addStartupChange(
  in string changeType,
  in string id
);
Parameters
changeType
The type of change to remove for the specified add-on. This can be one of the Startup change types or a custom value defined by your own provider.
id
The add-on ID to remove from the change list.

getStartupChanges()

Returns an array of add-on IDs that changed for a given startup change type.

string[] getStartupChanges(
  in string changeType
);
Parameters
changeType
The change type for which to retrieve a list of changed add-ons. This can be one of the Startup change types or a custom value defined by your own provider.
Return value

An array of add-on IDs indicating the add-ons for which the specified change type applies.

getInstallForURL()

Asynchronously gets an AddonInstall for a URL.

Promise? getInstallForURL(
  in string url,
  in InstallCallback? callback,
  in string mimetype,
  in string hash,
  in string name,
  in string iconURL,
  in string version,
  in nsILoadGroup loadGroup
)
Parameters
url
The url the add-on is located at
callback
A callback to pass the AddonInstall to
mimetype
The mimetype of the add-on
hash
An optional hash of the add-on
name
An optional placeholder name while the add-on is being downloaded
iconURL
An optional placeholder icon URL while the add-on is being downloaded
version
An optional placeholder version while the add-on is being downloaded
loadGroup
An optional nsILoadGroup to associate any network requests with

getInstallForFile()

Asynchronously gets an AddonInstall for an nsIFile.

Promise? getInstallForFile(
  in nsIFile file,
  in InstallCallback? callback,
  in string mimetype
)
Parameters
file
The nsIFile where the add-on is located
callback
A callback to pass the AddonInstall to
mimetype
An optional mimetype hint for the add-on

getAllInstalls()

Asynchronously gets all current AddonInstalls.

Promise? getAllInstalls(
  in InstallListCallback? callback
)
Parameters
callback
A callback which will be passed an array of AddonInstalls

getInstallsByTypes()

Asynchronously gets all current AddonInstalls optionally limiting to a list of types.

Promise? getInstallsByTypes(
  in string types[],
  in InstallListCallback? callback
)
Parameters
types
An optional array of types to retrieve. Each type is a string name.
callback
A callback which will be passed an array of AddonInstalls.

installAddonsFromWebpage()

Starts installation of an array of AddonInstall notifying the registered web install listener of blocked or started installs.

void installAddonsFromWebpage(
  in string mimetype,
  in nsIDOMWindow source,
  in nsIURI uri,
  in AddonInstall installs[]
)
Parameters
mimetype
The mimetype of add-ons being installed
source
The nsIDOMWindow that started the installs
uri
The nsIURI that started the installs
installs
The array of AddonInstalls to be installed

addInstallListener()

Adds a new InstallListener if the listener is not already registered.

void addInstallListener(
  in InstallListener listener
)
Parameters
listener
The InstallListener to add

removeInstallListener()

Removes an InstallListener if the listener is registered.

void removeInstallListener(
  in InstallListener listener
)
Parameters
listener
The InstallListener to remove

getAllAddons()

Asynchronously gets all installed Addons.

Promise? getAllAddons(
  in AddonListCallback? callback
)
Parameters
callback
A callback which will be passed an array of Addons

getAddonByID()

Asynchronously gets an Addon with a specific ID.

Promise? getAddonByID(
  in string id,
  in AddonCallback? callback
)
Parameters
id
The ID of the Addon to retrieve
callback
The callback to pass the retrieved Addon to

getAddonBySyncGUID()

Asynchronously gets an Addon with a specific Sync GUID.

Promise? getAddonBySyncGUID(
  in string guid,
  in AddonCallback? callback
)
Parameters
guid
The Sync GUID of the Addon to retrieve
callback
The callback to pass the retrieved Addon to

getAddonsByIDs()

Asynchronously gets an array of Addons.

Promise? getAddonsByIDs(
  in string ids[],
  in AddonListCallback? callback
)
Parameters
ids
The array of IDs to retrieve
callback
The callback to pass an array of Addons to

getAddonsByTypes()

Asynchronously gets Addons of specific types.

Promise? getAddonsByTypes(
  in string types[],
  in AddonListCallback? callback
)
Parameters
types
An optional array of types to retrieve. Each type is a string name
callback
The callback to pass an array of Addons to

getAddonsWithOperationsByTypes()

Asynchronously gets Addons that have operations waiting for an application restart to complete.

Promise? getAddonsWithOperationsByTypes(
  in string types[],
  in AddonListCallback? callback
)
Parameters
types
An optional array of types to retrieve. Each type is a string name.
callback
The callback to pass the array of Addons to.

addAddonListener()

Adds a new AddonListener if the listener is not already registered.

void addAddonListener(
  in AddonListener listener
)
Parameters
listener
The AddonListener to add

removeAddonListener()

Removes an AddonListener if the listener is registered.

void removeAddonListener(
  in AddonListener listener
)
Parameters
listener
The AddonListener to remove

addTypeListener()

Adds a new TypeListener if the listener is not already registered.

void addTypeListener(
  in TypeListener listener
)
Parameters
listener
The TypeListener to add

removeTypeListener()

Removes a TypeListener if the listener is registered.

void removeTypeListener(
  in TypeListener listener
)
Parameters
listener
The TypeListener to remove

getURIForResourceInFile()

nsIURI getURIForResourceInFile(
  in nsIFile aFile,
  in string aPath
)
Parameters
aFile
The nsIFile containing the resources; must be either a directory or an XPI file.
aPath
The path to find the resource at, "/" separated. If aPath is empty then the URI to the root of the contained files will be returned.
Returns

An nsIURI pointing at the resource.

Document Tags and Contributors

Tags: 
 Contributors to this page: bunnybooboo, Leif-AMO, kmaglione, freaktechnik, ahal, rubo77, jswisher, gonzipc, Beth_Newhouse, kscarfone, Maroosko, sachin.hosmani, Sheppy, darktrojan, greiner, gps, unfocused, trevorh, Mossop, Erikgotts50, erikvold, Mook, madarche
 Last updated by: bunnybooboo,