Package org.mozilla.geckoview

Class WebExtensionController

Object

org.mozilla.geckoview.WebExtensionController

public class WebExtensionController
extends Object

Controller for managing WebExtensions within a GeckoRuntime instance. Provides functionality for installing, uninstalling, enabling, disabling, and managing delegates for WebExtensions.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	WebExtensionController.AddonManagerDelegate	This delegate will be called whenever the state of an extension has changed.
static interface	WebExtensionController.DebuggerDelegate	Delegate for receiving debugger-related WebExtension events.
static class	WebExtensionController.EnableSource	Contains the possible values for the source parameter in enable(org.mozilla.geckoview.WebExtension, int) and disable(org.mozilla.geckoview.WebExtension, int).
static @interface	WebExtensionController.EnableSources	Defines the possible sources that can enable or disable a WebExtension.
static interface	WebExtensionController.ExtensionProcessDelegate	This delegate is used to notify of extension process state changes.
static @interface	WebExtensionController.InstallationMethod	The method used by the embedder to install the WebExtension.
static interface	WebExtensionController.PromptDelegate	This delegate will be called whenever an extension is about to be installed or it needs new permissions, e.g during an update or because it called permissions.request

Field Summary

Fields

Modifier and Type	Field	Description
static final String	INSTALLATION_METHOD_FROM_FILE	Indicates the WebExtension was installed from a file.
static final String	INSTALLATION_METHOD_MANAGER	Indicates the WebExtension was installed using from the embedder's add-ons manager.
static final String	INSTALLATION_METHOD_ONBOARDING	Indicates the WebExtension was installed from the embedder's onboarding feature.

Method Summary

Modifier and Type	Method	Description
GeckoResult<WebExtension>	addOptionalPermissions(String extensionId, String[] permissions, String[] origins, String[] dataCollectionPermissions)	Add the provided permissions to the WebExtension with the given id.
WebExtension.Download	createDownload(int id)	Creates a new Download object with the specified ID for tracking WebExtension downloads.
GeckoResult<WebExtension>	disable(WebExtension extension, int source)	Disable an extension that is enabled.
void	disableExtensionProcessSpawning()	Disable extension process spawning.
GeckoResult<WebExtension>	enable(WebExtension extension, int source)	Enable an extension that has been disabled.
void	enableExtensionProcessSpawning()	Enable extension process spawning.
GeckoResult<WebExtension>	ensureBuiltIn(String uri, String id)	Ensure that a built-in extension is installed.
WebExtensionController.PromptDelegate	getPromptDelegate()
GeckoResult<WebExtension>	install(String uri)	Install an extension.
GeckoResult<WebExtension>	install(String uri, String installationMethod)	Install an extension.
GeckoResult<WebExtension>	installBuiltIn(String uri)	Install a built-in extension.
GeckoResult<List<WebExtension>>	list()	List installed extensions for this GeckoRuntime.
GeckoResult<WebExtension>	removeOptionalPermissions(String extensionId, String[] permissions, String[] origins, String[] dataCollectionPermissions)	Remove the provided permissions from the WebExtension with the given id.
void	setAddonManagerDelegate(WebExtensionController.AddonManagerDelegate delegate)	Set the WebExtensionController.AddonManagerDelegate for this instance.
GeckoResult<WebExtension>	setAllowedInPrivateBrowsing(WebExtension extension, boolean allowed)	Set whether an extension should be allowed to run in private browsing or not.
void	setDebuggerDelegate(WebExtensionController.DebuggerDelegate delegate)	Set the WebExtensionController.DebuggerDelegate for this instance.
void	setExtensionProcessDelegate(WebExtensionController.ExtensionProcessDelegate delegate)	Set the WebExtensionController.ExtensionProcessDelegate for this instance.
void	setPromptDelegate(WebExtensionController.PromptDelegate delegate)	Set the WebExtensionController.PromptDelegate for this instance.
void	setTabActive(GeckoSession session, boolean active)	Notifies extensions about a active tab change over the `tabs.onActivated` event.
GeckoResult<Void>	uninstall(WebExtension extension)	Uninstall an extension.
GeckoResult<WebExtension>	update(WebExtension extension)	Update a web extension.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

INSTALLATION_METHOD_MANAGER

public static final String INSTALLATION_METHOD_MANAGER

Indicates the WebExtension was installed using from the embedder's add-ons manager.

See Also:

• Constant Field Values

INSTALLATION_METHOD_FROM_FILE

public static final String INSTALLATION_METHOD_FROM_FILE

Indicates the WebExtension was installed from a file.

See Also:

• Constant Field Values

INSTALLATION_METHOD_ONBOARDING

public static final String INSTALLATION_METHOD_ONBOARDING

Indicates the WebExtension was installed from the embedder's onboarding feature.

See Also:

• Constant Field Values

Method Details

getPromptDelegate

@UiThread
@Nullable
public WebExtensionController.PromptDelegate getPromptDelegate()

Returns:

the current WebExtensionController.PromptDelegate instance.

See Also:

• WebExtensionController.PromptDelegate

setPromptDelegate

@UiThread
public void setPromptDelegate(@Nullable
 WebExtensionController.PromptDelegate delegate)

Set the WebExtensionController.PromptDelegate for this instance. This delegate will be used to be notified whenever an extension is being installed or needs new permissions.

Parameters:

delegate - the delegate instance.

See Also:

• WebExtensionController.PromptDelegate

setDebuggerDelegate

@UiThread
public void setDebuggerDelegate(@NonNull
 WebExtensionController.DebuggerDelegate delegate)

Set the WebExtensionController.DebuggerDelegate for this instance. This delegate will receive updates about extension changes using developer tools.

Parameters:

delegate - the Delegate instance

setAddonManagerDelegate

@UiThread
public void setAddonManagerDelegate(@Nullable
 WebExtensionController.AddonManagerDelegate delegate)

Set the WebExtensionController.AddonManagerDelegate for this instance. This delegate will be used to be notified whenever the state of an extension has changed.

Parameters:

delegate - the delegate instance

See Also:

• WebExtensionController.AddonManagerDelegate

setExtensionProcessDelegate

@UiThread
public void setExtensionProcessDelegate(@Nullable
 WebExtensionController.ExtensionProcessDelegate delegate)

Set the WebExtensionController.ExtensionProcessDelegate for this instance. This delegate will be used to notify when the state of the extension process has changed.

Parameters:

delegate - the extension process delegate

See Also:

• WebExtensionController.ExtensionProcessDelegate

enableExtensionProcessSpawning

@AnyThread
public void enableExtensionProcessSpawning()

Enable extension process spawning.

Extension process spawning can be disabled when the extension process has been killed or crashed beyond the threshold set for Gecko. This method can be called to reset the threshold count and allow the spawning again. If the threshold is reached again, WebExtensionController.ExtensionProcessDelegate.onDisabledProcessSpawning() will still be called.

See Also:

• WebExtensionController.ExtensionProcessDelegate.onDisabledProcessSpawning()

disableExtensionProcessSpawning

@AnyThread
public void disableExtensionProcessSpawning()

Disable extension process spawning.

Extension process spawning can be re-enabled with enableExtensionProcessSpawning(). This method does the opposite and stops the extension process. This method can be called when we no longer want to run extensions for the rest of the session.

See Also:

• WebExtensionController.ExtensionProcessDelegate.onDisabledProcessSpawning()

install

@NonNull
@AnyThread
public GeckoResult<WebExtension> install(@NonNull
 String uri,
 @Nullable
 String installationMethod)

Install an extension.

An installed extension will persist and will be available even when restarting the GeckoRuntime.

Installed extensions through this method need to be signed by Mozilla, see Distributing your add-on .

When calling this method, the GeckoView library will download the extension, validate its manifest and signature, and give you an opportunity to verify its permissions through WebExtensionController.PromptDelegate.onInstallPromptRequest(org.mozilla.geckoview.WebExtension, java.lang.String[], java.lang.String[], java.lang.String[]), you can use this method to prompt the user if appropriate.

Parameters:

uri - URI to the extension's .xpi package. This can be a remote https: URI or a local file: or resource: URI. Note: the app needs the appropriate permissions for local URIs.

installationMethod - The method used by the embedder to install the WebExtension.

Returns:

A GeckoResult that will complete when the installation process finishes. For successful installations, the GeckoResult will return the WebExtension object that you can use to set delegates and retrieve information about the WebExtension using WebExtension.metaData.

If an error occurs during the installation process, the GeckoResult will complete exceptionally with a InstallException that will contain the relevant error code in InstallException#code.

See Also:

• WebExtensionController.PromptDelegate.onInstallPromptRequest(WebExtension, String[], String[], String[])
• WebExtension.InstallException.ErrorCodes
• WebExtension.metaData

install

@NonNull
@AnyThread
public GeckoResult<WebExtension> install(@NonNull
 String uri)

Install an extension.

An installed extension will persist and will be available even when restarting the GeckoRuntime.

Installed extensions through this method need to be signed by Mozilla, see Distributing your add-on .

When calling this method, the GeckoView library will download the extension, validate its manifest and signature, and give you an opportunity to verify its permissions through installPromptRequest(GeckoBundle, EventCallback), you can use this method to prompt the user if appropriate. If you are looking to provide an WebExtensionController.InstallationMethod, please use install(String, String)

Parameters:

uri - URI to the extension's .xpi package. This can be a remote https: URI or a local file: or resource: URI. Note: the app needs the appropriate permissions for local URIs.

Returns:

A GeckoResult that will complete when the installation process finishes. For successful installations, the GeckoResult will return the WebExtension object that you can use to set delegates and retrieve information about the WebExtension using WebExtension.metaData.

If an error occurs during the installation process, the GeckoResult will complete exceptionally with a InstallException that will contain the relevant error code in InstallException#code.

See Also:

• installPromptRequest(org.mozilla.gecko.util.GeckoBundle, org.mozilla.gecko.util.EventCallback)
• WebExtension.InstallException.ErrorCodes
• WebExtension.metaData

setAllowedInPrivateBrowsing

@NonNull
@AnyThread
public GeckoResult<WebExtension> setAllowedInPrivateBrowsing(@NonNull
 WebExtension extension,
 boolean allowed)

Set whether an extension should be allowed to run in private browsing or not.

Parameters:

extension - the WebExtension instance to modify.

allowed - true if this extension should be allowed to run in private browsing pages, false otherwise.

Returns:

the updated WebExtension instance.

addOptionalPermissions

@NonNull
@AnyThread
public GeckoResult<WebExtension> addOptionalPermissions(@NonNull
 String extensionId,
 @NonNull
 String[] permissions,
 @NonNull
 String[] origins,
 @NonNull
 String[] dataCollectionPermissions)

Add the provided permissions to the WebExtension with the given id.

Parameters:

extensionId - the id of WebExtension instance to modify.

permissions - the permissions to add, pass an empty array to not update.

origins - the origins to add, pass an empty array to not update.

dataCollectionPermissions - the data collection permissions to add, pass an empty array to not update.

Returns:

the updated WebExtension instance.

removeOptionalPermissions

@NonNull
@AnyThread
public GeckoResult<WebExtension> removeOptionalPermissions(@NonNull
 String extensionId,
 @NonNull
 String[] permissions,
 @NonNull
 String[] origins,
 @NonNull
 String[] dataCollectionPermissions)

Remove the provided permissions from the WebExtension with the given id.

Parameters:

extensionId - the id of WebExtension instance to modify.

permissions - the permissions to remove, pass an empty array to not update.

origins - the origins to remove, pass an empty array to not update.

dataCollectionPermissions - the data collection permissions to remove, pass an array to not update.

Returns:

the updated WebExtension instance.

installBuiltIn

@NonNull
@AnyThread
public GeckoResult<WebExtension> installBuiltIn(@NonNull
 String uri)

Install a built-in extension.

Built-in extensions have access to native messaging, don't need to be signed and are installed from a folder in the APK instead of a .xpi bundle.

Example:

controller.installBuiltIn("resource://android/assets/example/"); Will install the built-in extension located at /assets/example/ in the app's APK.

Parameters:

uri - Folder where the extension is located. To ensure this folder is inside the APK, only resource://android URIs are allowed.

Returns:

A GeckoResult that completes with the extension once it's installed.

See Also:

• WebExtension.MessageDelegate

ensureBuiltIn

@NonNull
@AnyThread
public GeckoResult<WebExtension> ensureBuiltIn(@NonNull
 String uri,
 @Nullable
 String id)

Ensure that a built-in extension is installed.

Similar to installBuiltIn(java.lang.String), except the extension is not re-installed if it's already present and it has the same version.

Example:

controller.ensureBuiltIn("resource://android/assets/example/", "example@example.com"); Will install the built-in extension located at /assets/example/ in the app's APK.

Parameters:

uri - Folder where the extension is located. To ensure this folder is inside the APK, only resource://android URIs are allowed.

id - Extension ID as present in the manifest.json file.

Returns:

A GeckoResult that completes with the extension once it's installed.

See Also:

• WebExtension.MessageDelegate

uninstall

@NonNull
@AnyThread
public GeckoResult<Void> uninstall(@NonNull
 WebExtension extension)

Uninstall an extension.

Uninstalling an extension will remove it from the current GeckoRuntime instance, delete all its data and trigger a request to close all extension pages currently open.

Parameters:

extension - The WebExtension to be uninstalled.

Returns:

A GeckoResult that will complete when the uninstall process is completed.

enable

@AnyThread
@NonNull
public GeckoResult<WebExtension> enable(@NonNull
 WebExtension extension,
 int source)

Enable an extension that has been disabled. If the extension is already enabled, this method has no effect.

Parameters:

extension - The WebExtension to be enabled.

source - The agent that initiated this action, e.g. if the action has been initiated by the user,use WebExtensionController.EnableSource.USER.

Returns:

the new WebExtension instance, updated to reflect the enablement.

disable

@AnyThread
@NonNull
public GeckoResult<WebExtension> disable(@NonNull
 WebExtension extension,
 int source)

Disable an extension that is enabled. If the extension is already disabled, this method has no effect.

Parameters:

extension - The WebExtension to be disabled.

source - The agent that initiated this action, e.g. if the action has been initiated by the user, use WebExtensionController.EnableSource.USER.

Returns:

the new WebExtension instance, updated to reflect the disablement.

list

@AnyThread
@NonNull
public GeckoResult<List<WebExtension>> list()

List installed extensions for this GeckoRuntime.

The returned list can be used to set delegates on the WebExtension objects using WebExtension.setActionDelegate(org.mozilla.geckoview.WebExtension.ActionDelegate), WebExtension.setMessageDelegate(org.mozilla.geckoview.WebExtension.MessageDelegate, java.lang.String).

Returns:

a GeckoResult that will resolve when the list of extensions is available.

update

@AnyThread
@NonNull
public GeckoResult<WebExtension> update(@NonNull
 WebExtension extension)

Update a web extension.

When checking for an update, GeckoView will download the update manifest that is defined by the web extension's manifest property browser_specific_settings.gecko.update_url. If an update is found it will be downloaded and installed. If the extension needs any new permissions the updatePrompt(org.mozilla.gecko.util.GeckoBundle, org.mozilla.gecko.util.EventCallback) will be triggered.

More information about the update manifest format is available here.

Parameters:

extension - The extension to update.

Returns:

A GeckoResult that will complete when the update process finishes. If an update is found and installed successfully, the GeckoResult will return the updated WebExtension. If no update is available, null will be returned. If the updated extension requires new permissions, the installPromptRequest(org.mozilla.gecko.util.GeckoBundle, org.mozilla.gecko.util.EventCallback) will be called.

See Also:

• updatePrompt(org.mozilla.gecko.util.GeckoBundle, org.mozilla.gecko.util.EventCallback)

setTabActive

@AnyThread
public void setTabActive(@NonNull
 GeckoSession session,
 boolean active)

Notifies extensions about a active tab change over the `tabs.onActivated` event.

Parameters:

session - The GeckoSession of the newly selected session/tab.

active - true if the tab became active, false if the tab became inactive.

createDownload

@Nullable
@UiThread
public WebExtension.Download createDownload(int id)

Creates a new Download object with the specified ID for tracking WebExtension downloads.

Parameters:

id - The unique identifier for the download

Returns:

A new Download object for the specified ID

Throws:

IllegalArgumentException - if a download with this ID already exists