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 |
Promise? getInstallForFile(in |
Promise? getAllInstalls(in InstallListCallback? callback) |
Promise? getInstallsByTypes(in string types[], in InstallListCallback? callback) |
void installAddonsFromWebpage(in string mimetype, in |
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) |
|
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 AddonInstall
s
void InstallListCallback(
in AddonInstall
installs[]
)
Parameters
- installs
- The array of
AddonInstall
s 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 Addon
s
void AddonListCallback(
in Addon
addons[]
)
Parameters
- addons
- The array of
Addon
s 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). |
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.
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, inInstallCallback
? callback, in string mimetype, in string hash, in string name, in string iconURL, in string version, innsILoadGroup
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( innsIFile
file, inInstallCallback
? 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 AddonInstall
s.
Promise? getAllInstalls(
in InstallListCallback
? callback
)
Parameters
- callback
- A callback which will be passed an array of
AddonInstall
s
getInstallsByTypes()
Asynchronously gets all current AddonInstall
s 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
AddonInstall
s.
installAddonsFromWebpage()
Starts installation of an array of AddonInstall
notifying the registered web install listener of blocked or started installs.
void installAddonsFromWebpage( in string mimetype, innsIDOMWindow
source, innsIURI
uri, inAddonInstall
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
AddonInstall
s 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 Addon
s.
Promise? getAllAddons(
in AddonListCallback? callback
)
Parameters
Parameters
callback
A callback which will be passed an array of
Addon
s
getAddonByID()
getAddonByID()
Asynchronously gets an
Addon
with a specific ID.
Promise? getAddonByID(
in string id,
in AddonCallback
? callback
)
Parameters
Parameters
getAddonBySyncGUID()
getAddonBySyncGUID()
Asynchronously gets an
Addon
with a specific Sync GUID.
Promise? getAddonBySyncGUID(
in string guid,
in AddonCallback
? callback
)
Parameters
Parameters
getAddonsByIDs()
getAddonsByIDs()
Asynchronously gets an array of
Addon
s.
Promise? getAddonsByIDs(
in string ids[],
in AddonListCallback
? callback
)
Parameters
Parameters
ids
The array of IDs to retrieve
callback
The callback to pass an array of
Addon
s to
getAddonsByTypes()
getAddonsByTypes()
Asynchronously gets
Addon
s of specific types.
Promise? getAddonsByTypes(
in string types[],
in AddonListCallback
? callback
)
Parameters
Parameters
types
An optional array of types to retrieve. Each type is a string name
callback
The callback to pass an array of
Addon
s to
getAddonsWithOperationsByTypes()
getAddonsWithOperationsByTypes()
Asynchronously gets
Addon
s that have operations waiting for an application restart to complete.
Promise? getAddonsWithOperationsByTypes(
in string types[],
in AddonListCallback
? callback
)
Parameters
Parameters
types
An optional array of types to retrieve. Each type is a string name.
callback
The callback to pass the array of
Addon
s to.
addAddonListener()
addAddonListener()
Adds a new
AddonListener
if the listener is not already registered.
void addAddonListener(
in AddonListener
listener
)
Parameters
Parameters
listener
The
AddonListener
to add
removeAddonListener()
removeAddonListener()
Removes an
AddonListener
if the listener is registered.
void removeAddonListener(
in AddonListener
listener
)
Parameters
Parameters
listener
The
AddonListener
to remove
addTypeListener()
addTypeListener()
Adds a new
TypeListener
if the listener is not already registered.
void addTypeListener(
in TypeListener
listener
)
Parameters
Parameters
listener
The
TypeListener
to add
removeTypeListener()
removeTypeListener()
Removes a
TypeListener
if the listener is registered.
void removeTypeListener(
in TypeListener
listener
)
Parameters
Parameters
listener
The
TypeListener
to remove
getURIForResourceInFile()
getURIForResourceInFile()
nsIURI
getURIForResourceInFile(
in nsIFile
aFile,
in string aPath
)
Parameters
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
Returns
An
nsIURI
pointing at the resource.