Addon

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.

An Addon represents an add-on that is either installed or can be installed. Instances can be created using the many getAddon methods on the AddonManager object.

The interface can represent many different kinds of add-ons and as such, some of the methods and properties are considered "required" and others "optional," which means that the optional methods or property may not exist on Addon instances for some types of add-ons. API consumers should take care to verify the existence of these methods or properties before relying on them.

Overview of required methods

void isCompatibleWith(in string appVersion, in string platformVersion)

void findUpdates(in UpdateListener listener, in integer reason, in string appVersion, in string platformVersion)

Overview of optional methods

void uninstall()

void cancelUninstall()

boolean hasResource(in string path)

nsIURI getResourceURI(in string path)

void getDataDirectory(in DataDirectoryCallback callback)

Required properties

Attribute	Type	Description
`appDisabled` Read only	`boolean`	True if this add-on cannot be used in the application based on version compatibility, dependencies, and blocklisting.
`blocklistState` Read only	`integer`	The current blocklist state of this add-on; see `nsIBlocklistService` for possible values.
`creator` Read only	`AddonAuthor`	The creator of the add-on.
`foreignInstall` Read only	`boolean`	True or false depending on whether the add-on is a third party add-on installation or not.
`id` Read only	`string`	The ID of the add-on. No other installed add-on will have the same ID.
`isActive` Read only	`boolean`	True if the add-on is currently functional. For some add-ons this will change immediately based on the appDisabled and userDisabled properties; for others it will only change after an application restart.
`isCompatible` Read only	`boolean`	True or false depending on whether the add-on is compatible with the current application version and platform version.
`isPlatformCompatible` Read only	`boolean`	True or false depending on whether the add-on is compatible with the current operating system.
`name` Read only	`string`	The name of the add-on.
`pendingOperations` Read only	`integer`	A bitfield holding all of the current operations that are waiting to be performed for this add-on. Operations are generally deferred when a restart is necessary to accomplish them.
`permissions` Read only	`integer`	A bitfield holding all the the operations that can be performed on this add-on. Operations my be restricted based on system policies (e.g., the system administrator may not allow certain add-ons to be uninstalled), add-on type (e.g., themes may not be disabled), or add-on state (e.g., an incompatible add-on cannot be enabled).
`providesUpdatesSecurely` Read only	`boolean`	True if the add-on has a secure means of updating or cannot be updated at all.
`scope` Read only	`integer`	Indicates what scope the add-on is installed in, per profile, user, system, or application.
`type` Read only	`string`	The type of the add-on.
`userDisabled`	`boolean`	True if the user wants this add-on to be disabled.
`version` Read only	`string`	The version of the add-on.

Optional properties

Attribute	Type	Description
`aboutURL` Read only	`string`	The URL of the about dialog to display for this add-on. This is passed to `window.openDialog()` when presenting the about dialog. If you don't provide an `aboutURL`, a generic about dialog is displayed. The dialog receives the `Addon` object representing your add-on as a parameter.
`applyBackgroundUpdates`	`integer`	Indicates whether updates found in the background for this add-on will be applied automatically. See auto update values. The user is provided a UI for this in the add-ons manager and it's the add-on provider's responsibility to remember its selection.
`contributors` Read only	`AddonAuthor[]`	An array of strings holding the contributors of the add-on.
`description` Read only	`string`	The description of the add-on.
`developers` Read only	`AddonAuthor[]`	An array of strings holding the developers of the add-on.
`homepageURL` Read only	`string`	The homepage URL of the add-on.
`iconURL` Read only	`string`	The url of the icon that represents this add-on.
`install` Read only	`AddonInstall`	The `AddonInstall` that will install this add-on. Only available if this add-on is in the process of being installed.
`installDate` Read only	`Date`	The Date that the add-on was first installed.
`optionsURL` Read only	`string`	The url of the options dialog to display for this add-on.
`pendingUpgrade` Read only	`Addon`	If this add-on will be replaced on the next restart, this property will hold the new `Addon` object.
`releaseNotesURI` Read only	`nsIURI`	A uri for release notes for this version.
`screenshots` Read only	`AddonScreenshot[]`	An array of AddonScreenshot objects containing urls of preview images for the add-on.
`size` Read only	`integer`	The size of the add-on's files in bytes. For an add-on that has not yet been downloaded, this may be an estimated value.
`sourceURI` Read only	`nsIURI`	The uri that this add-on was installed from.
`syncGUID` Read only	`string`	String GUID to identify the add-on in sync. The GUID is generated randomly and is made consistent across devices during sync.
`translators` Read only	`AddonAuthor[]`	An array of strings holding the translators of the add-on.
`updateDate` Read only	`Date`	The Date that the add-on was most recently updated.
`operationsRequiringRestart` Read only	`integer`	A bitfield holding all of the operations that will require a restart to complete for this add-on.
`fullDescription` Read only	`string`
`developerComments` Read only	`string`
`eula` Read only	`string`
`icon64URL` Read only	`string`
`supportURL` Read only	`string`
`contributionURL` Read only	`string`
`contributionAmount` Read only	`string`
`averageRating` Read only	`number`
`reviewCount` Read only	`integer`
`reviewURL` Read only	`string`
`totalDownloads` Read only	`integer`
`weeklyDownloads` Read only	`integer`
`dailyUsers` Read only	`integer`
`repositoryStatus` Read only	`integer`

Callbacks

DataDirectoryCallback()

A callback which is passed a directory path, and, when an error has occured, an Error object.

void DataDirectoryCallback(
  in string path,
  in Error error
)

Parameters

path: A string representation of the Addon's data directory.
error: If an error has occured, an Error object relevant to the error, othereise null.

Required Methods

isCompatibleWith()

Tests whether this add-on is known to be compatible with a particular application and platform version.

void isCompatibleWith(
  in string appVersion,
  in string platformVersion
)

Parameters

appVersion: An application version to test against
platformVersion: A platform version to test against

findUpdates()

Starts an update check for this add-on. This will perform asynchronously and deliver results to the given listener.

void findUpdates(
  in UpdateListener listener,
  in integer reason,
  in string appVersion,
  in string platformVersion
)

Parameters

listener: An UpdateListener for the update process
reason: A reason code for performing the update
appVersion: An application version to check for updates for
platformVersion: A platform version to check for updates for

Optional Methods

uninstall()

Uninstalls this add-on. If possible the uninstall will happen immediately, otherwise it will wait until the next application restart.

This method must be defined if an add-on has the permission PERM_CAN_UNINSTALL.

void uninstall(
)

cancelUninstall()

Cancels uninstalling an add-on if it is pending uninstall.

This method must be defined if an add-on has the pendingOperation PENDING_UNINSTALL.

void cancelUninstall(
)

hasResource()

Checks whether a file resource is available for this add-on. For XPI style add-ons, for example, it tests whether the named file was included in the package.

boolean hasResource(
  in string path
)

Parameters

path: A "/" separated path for the resource.

getResourceURI()

Gets an nsIURI to the file resource for this add-on.

nsIURI getResourceURI(
  in string path
)

Parameters

path: A "/" separated path for the resource.

getDataDirectory()

Requires Gecko 32.0(Firefox 32.0 / Thunderbird 32.0 / SeaMonkey 2.29)

Returns the path of the preferred directory, within the current profile, where an add-on should store data files. If the directory does not already exist, it will be created.

void getDataDirectory(
  in DataDirectoryCallback callback
)

Overview of required methods

Overview of optional methods

Required properties

Optional properties

Callbacks

DataDirectoryCallback()

Parameters

Required Methods

isCompatibleWith()

Parameters

findUpdates()

Parameters

Optional Methods

uninstall()

cancelUninstall()

hasResource()

Parameters

getResourceURI()

Parameters

getDataDirectory()

Document Tags and Contributors