Package org.mozilla.geckoview

Class WebExtensionController

Object
org.mozilla.geckoview.WebExtensionController
public class WebExtensionController extends Object

  • Method Details

    • getPromptDelegate

      @UiThread @Nullable public WebExtensionController.PromptDelegate getPromptDelegate()
      Returns:
      the current WebExtensionController.PromptDelegate instance.
      See Also:

    • 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:

    • 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

    • 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 installPrompt(org.mozilla.gecko.util.GeckoBundle, org.mozilla.gecko.util.EventCallback), 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.
      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:

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

    • 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:

    • 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:

    • 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 installPrompt(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)