GeckoView

https://firefox-source-docs.mozilla.org/mobile/android/geckoview/
Admin
GeckoView is a full-featured web engine library for Android that enables applications and browsers...
Tokens:33,933
Snippets:433
Trust Score:10
Update:6 months ago
Show doc for...
Tokens:
Raw
### WebExtensionController.install

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/design/managing-extensions.html

Starts the process of installing an extension. The embedder will either get the installed extension or an error.

```APIDOC
## POST /WebExtensionController/install

### Description
Initiates the installation of a web extension from a given URI.

### Method
POST

### Endpoint
/WebExtensionController/install

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **uri** (String) - Required - The URI of the extension to install.

### Request Example
```json
{
  "uri": "https://example.com/myextension.zip"
}
```

### Response
#### Success Response (200)
- **WebExtension** (Object) - The installed web extension.

#### Response Example
```json
{
  "metadata": {
    "name": "My Extension",
    "version": "1.0.0",
    "permissions": ["tabs", "storage"]
    // ... other metadata fields
  },
  "isBuiltIn": false,
  "isEnabled": true
}
```
```

--------------------------------

### Install WebExtension with GeckoResult

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/junit.html

Demonstrates how to install a WebExtension and receive the resulting WebExtension object asynchronously via GeckoResult. This is useful for handling operations that complete at a later time.

```java
public GeckoResult<WebExtension> install(...)
```

--------------------------------

### Install MozPhab

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/contributing-to-firefox.html

Install the 'MozPhab' tool using pip. The '--user' flag can be used to install it for the current user only.

```bash
pip install MozPhab [--user]

```

--------------------------------

### WebExtensionController.installBuiltIn

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/design/managing-extensions.html

Installs a built-in WebExtension with privileged permissions. The URI must be resource://.

```APIDOC
## POST /WebExtensionController/installBuiltIn

### Description
Installs a built-in web extension with privileged access. These extensions can run chrome code, do not require signatures, and can access native messaging.

### Method
POST

### Endpoint
/WebExtensionController/installBuiltIn

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **uri** (String) - Required - The resource URI of the built-in extension (e.g., `resource://myextension`).

### Request Example
```json
{
  "uri": "resource://myextension"
}
```

### Response
#### Success Response (200)
- **WebExtension** (Object) - The installed built-in web extension.

#### Response Example
```json
{
  "metadata": {
    "name": "My Built-in Extension",
    "version": "1.0.0",
    "permissions": ["*://*/*"]
    // ... other metadata fields
  },
  "isBuiltIn": true,
  "isEnabled": true
}
```
```

--------------------------------

### Install Navigation and Progress Delegates

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/junit.html

Installs multiple delegate types for the duration of the test. `GeckoSessionTestRule` uses reflection to match delegate calls to the appropriate proxy.

```java
sessionRule.delegateUntilTestEnd(object : NavigationDelegate, ProgressDelegate {})
```

--------------------------------

### WebExtensionController.listInstalled

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/design/managing-extensions.html

Asynchronously retrieves the full list of installed extensions.

```APIDOC
## GET /WebExtensionController/listInstalled

### Description
Retrieves a list of all currently installed web extensions. It is recommended to call this method whenever the extension manager UI is presented to ensure the data is up-to-date.

### Method
GET

### Endpoint
/WebExtensionController/listInstalled

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **List<WebExtension>** (Array) - An array of installed web extension objects.

#### Response Example
```json
[
  {
    "metadata": {
      "name": "Extension 1",
      "version": "1.0.0"
      // ... other metadata fields
    },
    "isBuiltIn": false,
    "isEnabled": true
  },
  {
    "metadata": {
      "name": "Extension 2",
      "version": "2.1.0"
      // ... other metadata fields
    },
    "isBuiltIn": true,
    "isEnabled": false
  }
]
```
```

--------------------------------

### Launch Android Emulator

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/for-gecko-engineers.html

This command installs and launches an x86-64 Android emulator. Use --help for information on available Android images.

```bash
./mach android-emulator

```

--------------------------------

### Install Bundled Extension in GeckoView

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/consumer/web-extensions.html

Use `installBuiltIn` to install an extension bundled within the application's assets. The extension's lifetime is not tied to the GeckoRuntime instance.

```javascript
runtime.getWebExtensionController()
  .installBuiltIn("resource://android/assets/messaging/")
```

--------------------------------

### WebExtensionController.PromptDelegate Interface

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/design/managing-extensions.html

Interface for handling user prompts related to extension installation, updates, and permissions.

```APIDOC
## Interface WebExtensionController.PromptDelegate

### Description
This interface defines callbacks for handling user interactions and decisions regarding web extensions, such as installation prompts, update confirmations, and permission requests.

### Methods
#### onInstallPrompt
- **Description**: Called when the user is prompted to install an extension.
- **Parameters**: `WebExtension extension`
- **Returns**: `GeckoResult<AllowOrDeny>`

#### onUpdatePrompt
- **Description**: Called when the user is prompted about an extension update.
- **Parameters**: `WebExtension currentlyInstalled`, `WebExtension updatedExtension`, `List<String> newPermissions`
- **Returns**: `GeckoResult<AllowOrDeny>`

#### onOptionalPrompt
- **Description**: Called when the extension requests optional permissions via `browser.permission.request`.
- **Parameters**: `WebExtension extension`, `List<String> optionalPermissions`
- **Returns**: `GeckoResult<AllowOrDeny>`
```

--------------------------------

### Add Translate Menu Item to Reference Browser

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/translations-toolkit-to-fenix.html

Add a menu item to the Reference Browser to trigger translation. This example shows how to get language tags and invoke the translate use case.

```kotlin
private val menuItems by lazy {
  ...,
  SimpleBrowserMenuItem("Translate (auto)") {
      var detectedFrom =
          store.state.selectedTab?.translationsState?.translationEngineState
              ?.detectedLanguages?.documentLangTag
              ?: "en"
      var detectedTo =
          store.state.selectedTab?.translationsState?.translationEngineState
              ?.detectedLanguages?.userPreferredLangTag
              ?: "en"
      sessionUseCases.translate.invoke(
          fromLanguage = detectedFrom,
          toLanguage = detectedTo,
          options = null,
      )
  },
}

```

--------------------------------

### Ensure Bundled Extension is Installed in GeckoView

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/consumer/web-extensions.html

Use `ensureBuiltIn` to install an extension only if it's not already present. This avoids repeated installations and potential performance issues. It accepts callbacks for success and error.

```javascript
runtime.getWebExtensionController()
  .ensureBuiltIn("resource://android/assets/messaging/", "messaging@example.com")
  .accept(
        extension -> Log.i("MessageDelegate", "Extension installed: " + extension),
        e -> Log.e("MessageDelegate", "Error registering WebExtension", e)
  );
```

--------------------------------

### Initialize GeckoViewTranslations Module in geckoview.js

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/translations-toolkit-to-fenix.html

Sets up the GeckoViewTranslations module by specifying its resource URI for initialization. This example shows how to reference toolkit calls from a GeckoView module.

```javascript
{
  name: "GeckoViewTranslations",
  onInit: {
  resource: "resource://gre/modules/GeckoViewTranslations.sys.mjs",
},

}
```

--------------------------------

### WebExtensionController Interface

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/design/managing-extensions.html

Defines the interface for managing WebExtensions. Use install/uninstall for general extensions and installBuiltIn for privileged ones. The PromptDelegate handles user prompts for installation and updates.

```java
public class WebExtensionController {
  // Start the process of installing an extension,
  // the embedder will either get the installed extension
  // or an error
  GeckoResult<WebExtension> install(String uri);

  // Install a built-in WebExtension with privileged
  // permissions, uri must be resource://
  // Privileged WebExtensions have access to experiments
  // (i.e. they can run chrome code), don’t need signatures
  // and have access to native messaging to the app
  GeckoResult<WebExtension> installBuiltIn(String uri)

  GeckoResult<Void> uninstall(WebExtension extension);

  GeckoResult<WebExtension> enable(WebExtension extension);

  GeckoResult<WebExtension> disable(WebExtension extension);

  GeckoResult<List<WebExtension>> listInstalled();

  // Checks for updates. This method returns a GeckoResult that is
  // resolved either with the updated WebExtension object or null
  // if the extension does not have pending updates.
  GeckoResult<WebExtension> update(WebExtension extension);

  public interface PromptDelegate {
      GeckoResult<AllowOrDeny> onInstallPrompt(WebExtension extension);

      GeckoResult<AllowOrDeny> onUpdatePrompt(
          WebExtension currentlyInstalled,
          WebExtension updatedExtension,
          List<String> newPermissions);

      // Called when the extension calls browser.permission.request
      GeckoResult<AllowOrDeny> onOptionalPrompt(
          WebExtension extension,
          List<String> optionalPermissions);
  }

  void setPromptDelegate(PromptDelegate promptDelegate);
}
```

--------------------------------

### GeckoSessionTestRule Delegate Utilities

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/junit.html

Use these utilities to manage delegate installations and cleanups for the duration of a test or a specific wait period. They simplify verifying that delegate methods are called.

```java
sessionRule.delegateUntilTestEnd(...)
sessionRule.delegateDuringNextWait(...)
sessionRule.waitUntilCalled(...)
sessionRule.forCallbacksDuringWait(...)
```

--------------------------------

### Call Toolkit Functions from GeckoViewTranslations.sys.mjs

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/translations-toolkit-to-fenix.html

Demonstrates how to call toolkit functions, both static and actor-based, from a GeckoView module. Includes examples for checking translation engine support and restoring a page via an actor.

```javascript
// TranslationsParent is in toolkit
ChromeUtils.defineESModuleGetters(lazy, {
  TranslationsParent: "resource://gre/actors/TranslationsParent.sys.mjs",
});

// ...
// Static call example
lazy.TranslationsParent.getIsTranslationsEngineSupported()

// Actor call example was registered in ActorManagerParent.sys.mjs
this.getActor("Translations").restorePage();

// Setting up a Java API (see below) can also be used for more control of calling a specific function. The idea here is just to set up a framework for exploring that could become the foundation of the final API.

```

--------------------------------

### Run GeckoView JUnit Test Suite

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/geckoview-quick-start.html

Execute the complete junit test suite for GeckoView to ensure no existing functionality is broken. No setup is required beyond having the necessary testing environment configured.

```bash
./mach geckoview-junit

```

--------------------------------

### Extension Manifest Permissions for Native Messaging

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/consumer/web-extensions.html

Example `manifest.json` snippet showing required permissions for native messaging, including `nativeMessagingFromContent` to allow messages from content scripts.

```json
"permissions": [
  "nativeMessaging",
  "nativeMessagingFromContent",
  "geckoViewAddons"
]
```

--------------------------------

### Run GeckoView JUnit Test via mach

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/junit.html

Example of how to execute a specific GeckoView JUnit test case using the 'mach' command-line interface. This command targets a particular test method within a test class.

```bash
./mach geckoview-junit org.mozilla.geckoview.test.NavigationDelegateTest#loadUnknownHost
```

--------------------------------

### Run GeckoView with Environment Variables

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/consumer/automation.html

Use `./mach run --setenv` to execute GeckoView with specified environment variables. Example: enabling extended logging for `JSComponentLoader`.

```bash
./mach run --setenv MOZ_LOG=JSComponentLoader:5
```

--------------------------------

### Changelog Entry for Deprecated Method

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/geckoview-quick-start.html

Example of how to document a deprecated method in the changelog. Include a warning emoji, the deprecated method, the expected removal version, and the associated bug number.

```markdown
- ⚠️ Deprecated [`GeckoSession.ContentDelegate.onProductUrl`][128.5], will now be removed in v131.
([bug 1898055]({{bugzilla}}1898055))

[128.5]: {{javadoc_uri}}/GeckoSession.ContentDelegate.html#onProductUrl(org.mozilla.geckoview.GeckoSession)
```

--------------------------------

### Push to Try Server

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/contributing-to-firefox.html

Use './mach try fuzzy' to select specific jobs to run and push your changes to the try server for testing, especially if you have Level 1 commit access.

```bash
./mach try fuzzy

```

--------------------------------

### Launch Local Web Server for Javadoc

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/geckoview-quick-start.html

After generating Javadoc, use this command to launch a local HTTP server. Navigate to http://localhost:8000/ in your browser to view the documentation.

```python
python3 -m http.server 8000
```

--------------------------------

### Send Primitive Type Message

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/consumer/web-extensions.html

Example of sending a string primitive instead of a JSON object.

```javascript
runtime.browser.sendNativeMessage("browser", "Hello World!");
```

--------------------------------

### Send Native Message from Content Script

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/consumer/web-extensions.html

Example of sending a JSON message from a content script to the host application.

```javascript
let manifest = document.querySelector("head > link[rel=manifest]");
if (manifest) {
     fetch(manifest.href)
        .then(response => response.json())
        .then(json => {
             let message = {type: "WPAManifest", manifest: json};
             browser.runtime.sendNativeMessage("browser", message);
        });
}
```

--------------------------------

### Initialize TranslationsDialogStore in Fragment

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/translations-toolkit-to-fenix.html

Sets up the store within a ComposeView inside a Fragment, utilizing middleware to bridge browser state and settings.

```kotlin
private lateinit var translationsDialogStore: TranslationsDialogStore

override fun onCreateView(
inflater: LayoutInflater,
container: ViewGroup?,
savedInstanceState: Bundle?,
): View = ComposeView(requireContext()).apply {
  translationsDialogStore = TranslationsDialogStore(
    TranslationsDialogState(),
    listOf(
        TranslationsDialogMiddleware(
        // If we weren’t using the translationsDialogStore, then the calls could also be made from the browserStore.
        browserStore = browserStore,
      settings = requireContext().settings(),),),)
}

// Simplified to avoid some error states or branching behavior
// This can be called to complete a translation.
private fun translate(
translationsDialogState: TranslationsDialogState? = null,
onShowDownloadLanguageFileDialog: () -> Unit,
) {
  translationsDialogStore.dispatch(TranslationsDialogAction.TranslateAction)
}
```

--------------------------------

### Build GeckoView

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/for-gecko-engineers.html

After configuring your mozconfig, run this command to build GeckoView. Ensure your mozconfig includes necessary modifications for native debugging if needed.

```bash
./mach build

```

--------------------------------

### Maven dependency configuration for Glean

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/design/sharing-rust-libraries.html

Example of a Maven dependency declaration for the Glean library within a project's POM file.

```xml
<dependency>
  <groupId>org.mozilla.telemetry</groupId>
  <artifactId>glean</artifactId>
  <version>33.1.2</version>
  <scope>compile</scope>
</dependency>
```

--------------------------------

### Build Project Locally

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/apilint.html

Run tests locally by building the project.

```bash
$ ./gradlew build
```

--------------------------------

### Implement Media Permission Delegate

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/consumer/permissions.html

Implement the onMediaPermissionRequest callback to handle requests for camera and microphone access. This includes checking existing Android permissions, presenting a user-facing dialog to select devices, and responding via the MediaCallback. Reject permissions if the associated Android permissions have been denied.

```java
private class ExamplePermissionDelegate implements GeckoSession.PermissionDelegate {
    @Override
    public void onMediaPermissionRequest(final GeckoSession session,
                                         final String uri,
                                         final MediaSource[] video,
                                         final MediaSource[] audio,
                                         final MediaCallback callback) {
        // Reject permission if Android permission has been previously denied.
        if ((audio != null
                && ContextCompat.checkSelfPermission(GeckoViewActivity.this,
                    Manifest.permission.RECORD_AUDIO) != PackageManager.PERMISSION_GRANTED)
            || (video != null
                && ContextCompat.checkSelfPermission(GeckoViewActivity.this,
                    Manifest.permission.CAMERA) != PackageManager.PERMISSION_GRANTED)) {
            callback.reject();
            return;
        }

        final String host = Uri.parse(uri).getAuthority();
        final String title;
        if (audio == null) {
            title = getString(R.string.request_video, host);
        } else if (video == null) {
            title = getString(R.string.request_audio, host);
        } else {
            title = getString(R.string.request_media, host);
        }

        // Get the media device name from the `MediaDevice`
        String[] videoNames = normalizeMediaName(video);
        String[] audioNames = normalizeMediaName(audio);

        final AlertDialog.Builder builder = new AlertDialog.Builder(activity);

        // Create drop down boxes to allow users to select which device to grant permission to
        final LinearLayout container = addStandardLayout(builder, title, null);
        final Spinner videoSpinner;
        if (video != null) {
            videoSpinner = addMediaSpinner(builder.getContext(), container, video, videoNames); // create spinner and add to alert UI
        } else {
            videoSpinner = null;
        }

        final Spinner audioSpinner;
        if (audio != null) {
            audioSpinner = addMediaSpinner(builder.getContext(), container, audio, audioNames); // create spinner and add to alert UI
        } else {
            audioSpinner = null;
        }

        builder.setNegativeButton(android.R.string.cancel, null)
               .setPositiveButton(android.R.string.ok,
                                  new DialogInterface.OnClickListener() {
                    @Override
                    public void onClick(final DialogInterface dialog, final int which) {
                        // gather selected media devices and grant access
                        final MediaSource video = (videoSpinner != null)
                                ? (MediaSource) videoSpinner.getSelectedItem() : null;
                        final MediaSource audio = (audioSpinner != null)
                                ? (MediaSource) audioSpinner.getSelectedItem() : null;
                        callback.grant(video, audio);
                    }
                });

        final AlertDialog dialog = builder.create();
        dialog.setOnDismissListener(new DialogInterface.OnDismissListener() {
                    @Override
                    public void onDismiss(final DialogInterface dialog) {
                        callback.reject();
                    }
                });
        dialog.show();
    }
}
```

--------------------------------

### Initialize GeckoView in Activity

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/consumer/geckoview-quick-start.html

Set up the GeckoSession and GeckoRuntime within the Activity's onCreate method.

```java
GeckoView view = findViewById(R.id.geckoview);
GeckoSession session = new GeckoSession();

// Workaround for Bug 1758212
session.setContentDelegate(new GeckoSession.ContentDelegate() {});

if (sRuntime == null) {
  // GeckoRuntime can only be initialized once per process
  sRuntime = GeckoRuntime.create(this);
}

session.open(sRuntime);
view.setSession(session);
session.loadUri("about:buildconfig"); // Or any other URL...
```

--------------------------------

### Deprecation Annotation Example

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/geckoview-quick-start.html

Apply this annotation to deprecate an API. Replace <interface_or_class_of_method>-<method_name> with the specific API identifier and <Current Nightly + 3> with the expected removal version.

```java
@Deprecated
@DeprecationSchedule(id = "<interface_or_class_of_method>-<method_name>", version = <Current Nightly + 3>)
```

--------------------------------

### Publish Plugins

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/apilint.html

Publish the apilint plugin by running the specified Gradle task.

```bash
$ ./gradlew apilint:publishPlugins
```

--------------------------------

### GeckoView Debug Configuration Log Output

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/consumer/automation.html

Example logcat output when GeckoView reads debug configuration from a file, showing added environment variables, arguments, and preferences.

```log
    GeckoRuntime  I  Adding debug configuration from: /data/local/tmp/org.mozilla.geckoview_example-geckoview-config.yaml
GeckoDebugConfig  D  Adding environment variables from debug config: {MOZ_LOG=nsHttp:5}
GeckoDebugConfig  D  Adding arguments from debug config: [--marionette]
GeckoDebugConfig  D  Adding prefs from debug config: {foo.bar.baz=true}

```

--------------------------------

### Implement Login Storage Prompt Delegate

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/design/login-storage-api.html

Extends GeckoSession's PromptDelegate to handle user prompts for login storage actions. Includes types for saving and selecting, and hints for different scenarios like generated logins or private mode.

```java
// Extending existing prompt delegate.
class GeckoSession {
    interface PromptDelegate {
        class LoginStoragePrompt extends BasePrompt {
            class Type {
                int SAVE;
                // TBD: autocomplete selection.
                // int SELECT;
            }

            class Hint {
                // v2
                // @Fenix: Automatically save the login and indicate this
                // to the user.
                int GENERATED;
                // @Fenix: Don’t prompt to save but allow the user to open
                // UI to save if they really want.
                int PRIVATE_MODE;
                // The data looks like it may be some other data (e.g. CC)
                // entered in a password field
                // @Fenix: Don’t prompt to save but allow the user to open
                // UI to save if they want (e.g. in case the CC number is
                // actually the username for a credit card account)
                int LOW_CONFIDENCE;
                // TBD
            }

            // Type
            int type;

            // Hint
            // The hint should help determining the appropriate user
            // prompting behavior.
            // @Fenix: Use the API from application-services/issues/1983 to
            // determine whether to show a Save or Update button on the
            // doorhanger, taking into account un/pw edits in the
            // doorhanger. When the user confirms the save/update.
            int hint;

            // For SAVE, it will hold the login to be stored or updated.
            // For SELECT, it will hold the logins for the autocomplete
            // selection.
            Login[] logins;

            // Confirm SAVE prompt: the login would include a user’s edits
            // to what will be saved.
            // v2
            // Confirm SELECT (autocomplete) prompt by providing the
            // selected login.
            PromptResponse confirm(Login login);

            // Dismiss request.
            PromptResponse dismiss();
        }

        GeckoResult<PromptResponse> onLoginStoragePrompt(
            GeckoSession session,
            LoginStoragePrompt prompt
        );
    }
}

```

--------------------------------

### Clobber and Build Gecko

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/native-debugging.html

Before the first debug build, it's recommended to clobber the object directory to ensure Android Studio picks up debug symbols. Subsequent builds can be done with `./mach build`.

```bash
./mach clobber
```

```bash
./mach build
```

--------------------------------

### Build GeckoView and Consume Locally

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/geckoview-quick-start.html

These commands are used to build a local version of GeckoView from mozilla-central and then consume it in a downstream project. This is essential for development when changes in Gecko or GeckoView need to be reflected.

```bash
cd /path/to/mozilla-central && ./mach build
cd /path/to/project && ./gradlew assembleDebug

```

--------------------------------

### Update Local Firefox Codebase

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/contributing-to-firefox.html

Ensure your local copy of the Firefox codebase is up-to-date before starting work. This command fetches the latest changes and rebases your local branch.

```bash
git remote update && git pull --rebase

```

--------------------------------

### Run Python Linters

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/geckoview-quick-start.html

Execute Python linting checks using flake8 and black. These commands ensure Python code adheres to style guides and quality standards.

```bash
./mach lint --linter flake8

```

```bash
./mach lint --linter black

```

--------------------------------

### WebExtensionController.enable

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/design/managing-extensions.html

Enables a given WebExtension.

```APIDOC
## POST /WebExtensionController/enable

### Description
Activates a disabled web extension, making it functional.

### Method
POST

### Endpoint
/WebExtensionController/enable

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **extension** (WebExtension) - Required - The web extension object to enable.

### Request Example
```json
{
  "extension": {
    "metadata": {
      "name": "My Extension"
      // ... other metadata fields
    },
    "isBuiltIn": false,
    "isEnabled": false
  }
}
```

### Response
#### Success Response (200)
- **WebExtension** (Object) - The enabled web extension.

#### Response Example
```json
{
  "metadata": {
    "name": "My Extension"
    // ... other metadata fields
  },
  "isBuiltIn": false,
  "isEnabled": true
}
```
```

--------------------------------

### Configure GeckoView/Firefox for Android Build

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/for-gecko-engineers.html

Use this mozconfig option to enable building GeckoView or Firefox for Android. Uncomment the target line for physical device testing.

```bash
# Build GeckoView/Firefox for Android:
ac_add_options --enable-project=mobile/android

# If --target is not specified it will default to host architecture for fast
# emulation (x86_64 or aarch64). For testing on physical phones you most likely
# want to use an aarch64 (ARM64) target.
# ac_add_options --target=aarch64

```

--------------------------------

### Define Login Storage Structure

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/design/login-storage-api.html

Defines the structure for storing login credentials, including fields like GUID, origin, username, and password. This is used by the runtime delegate.

```java
class LoginStorage {
    class Login {
        String guid;
        // @Fenix: currently called `hostname` in AsyncLoginsStorage.
        String origin;
        // @Fenix: currently called `formSubmitURL` in AsyncLoginsStorage
        String formActionOrigin;
        String httpRealm;
        String username;
        String password;
    }

    interface Delegate {
        // v2
        // Notify that the given login has been used for login.
        // @Fenix: call AsyncLoginsStorage.touch(login.guid).
        void onLoginUsed(Login login);

        // Request logins for the given domain.
        // @Fenix: return AsyncLoginsStorage.getByHostname(domain).
        GeckoResult<Login[]> onLoginFetch(String domain);

        // Request to save or update the given login.
        void onLoginSave(Login login);
    }
}

```

--------------------------------

### Define a Boolean Pref

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/geckoview-architecture.html

Example of how to define a boolean preference in GeckoView. Use `Pref<Boolean>` for boolean types. The pref can be read using `.get` and written using `.commit`.

```java
/* package */ final Pref<Boolean> mPrefExample =
   new Pref<Boolean>("example.pref", false);

```

--------------------------------

### Configure LLDB for Symbols

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/native-debugging.html

Add these lines to your `~/.lldbinit` file to enable inline breakpoints and specify the path where LLDB should search for debug symbols.

```bash
settings set target.inline-breakpoint-strategy always
```

```bash
settings append target.exec-search-paths <PATH>/objdir-android-opt/dist/bin
```

--------------------------------

### Publish to Local Maven Repository

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/apilint.html

Publish the new version of apilint to the local Maven repository.

```bash
$ ./gradlew publishToMavenLocal
```

--------------------------------

### GeckoSession.PromptDelegate.onLoginStoragePrompt

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/design/login-storage-api.html

Handles login-related prompts such as saving or updating credentials.

```APIDOC
## GeckoResult<PromptResponse> onLoginStoragePrompt(GeckoSession session, LoginStoragePrompt prompt)

### Description
Invoked when a login storage prompt (e.g., save or update) needs to be displayed to the user.

### Parameters
- **session** (GeckoSession) - Required - The current session.
- **prompt** (LoginStoragePrompt) - Required - The prompt details including type, hint, and associated logins.

### Response
- **GeckoResult<PromptResponse>** - The result of the user's interaction with the prompt.
```

--------------------------------

### Configure Gradle Packaging Options

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/native-debugging.html

Add this to build.gradle files to prevent stripping of shared object files.

```groovy
android {
    packagingOptions {
        doNotStrip "**/*.so"
    }
}
```

--------------------------------

### Submit Patch using Moz-Phab

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/contributing-to-firefox.html

Submit one or more commits for review using 'moz-phab submit'. You can specify a start and end revision to define the range of commits. If no arguments are given, it defaults to the range from the first non-public changeset to the current one.

```bash
moz-phab submit [start_rev] [end_rev]

```

--------------------------------

### Connect to Native Application from WebExtension

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/consumer/web-extensions.html

Establishes a connection to a native application using the browser.runtime.connectNative API. It includes a listener for incoming messages and sends an initial message.

```javascript
// Establish connection with app
let port = browser.runtime.connectNative("browser");
port.onMessage.addListener(response => {
    // Let's just echo the message back
    port.postMessage(`Received: ${JSON.stringify(response)}`);
});
port.postMessage("Hello from WebExtension!");

```

--------------------------------

### Configure Native Memory Profiling in mozconfig

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/native-debugging.html

Required build options for tracking native memory allocations on aarch64 devices.

```bash
ac_add_options --target=aarch64
ac_add_options --disable-jemalloc
```

--------------------------------

### GeckoView API Mapping Outline

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/translations-toolkit-to-fenix.html

A structural comparison between toolkit calls and their corresponding GeckoView API methods, including session, runtime, and delegate components.

```text
GeckoView API outline:

Session:

* GeckoResult<Void> translate(String fromLanguage, String toLanguage, TranslationOptions options)
  * The use of options is to make this function more extensible.
  * Toolkit call: translate(fromLanguage, toLanguage)
* GeckoResult<Void> restoreOriginalPage()
  * Toolkit call: void restorePage()

Runtime:

* GeckoResult<Boolean> isTranslationsEngineSupported()
  * Toolkit call: bool getIsTranslationsEngineSupported()
* GeckoResult<List<String>> preferredLanguages
  * Toolkit call: string[] getPreferredLanguages
* GeckoResult<Long> checkPairDownloadSize(String fromLanguage, String toLanguage)
  * Toolkit call: Needs to be created.
* GeckoResult<List<LanguageModel>> listModelDownloadStates()
  * Toolkit call: Needs to be created.

Delegate:

* void onOfferTranslate(GeckoSession session)
  * Will listen to message TranslationsParent:LanguageState
* void onTranslationStateChange(GeckoSession session, TranslationState translationState)
  * Will listen to message TranslationsParent:OfferTranslation
```

--------------------------------

### Configure Local GeckoView Dependency Substitution in Gradle

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/geckoview-quick-start.html

Include these lines in a Gradle project's build.gradle file to substitute the published GeckoView dependency with a local version from mozilla-central. Remember to remove these lines when returning to published builds.

```gradle
ext.topsrcdir = "/path/to/mozilla-central"
ext.topobjdir = "/path/to/object-directory" // Optional.
apply from: "${topsrcdir}/substitute-local-geckoview.gradle"

```

--------------------------------

### Enable file-based configuration

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/consumer/automation.html

Use this to force GeckoView to read configuration from a specific file path, even in non-debuggable release builds.

```java
new GeckoRuntimeSettings.Builder()
    .configFilePath("/your/app/specific/location")
    .build();
```

--------------------------------

### WebExtensionController Methods

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/design/managing-extensions.html

Methods for managing web extensions.

```APIDOC
## POST /WebExtensionController

### Description
Provides methods to manage web extensions within GeckoView.

### Method
POST

### Endpoint
/WebExtensionController

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
Methods return GeckoResult objects that resolve to specific types or Void.

#### Response Example
```json
{
  "result": "WebExtension object or Void"
}
```
```

--------------------------------

### Test Integration with api-lint

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/apilint.html

Run the api-lint integration test to ensure compatibility with the new apilint version.

```bash
$ ./mach lint -l android-api-lint
```

--------------------------------

### Implement GeckoView Permission Delegate

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/consumer/permissions.html

Implement the PermissionDelegate interface to handle various site permission requests. This includes methods for Android, Content, and Media permissions.

```java
private class ExamplePermissionDelegate implements GeckoSession.PermissionDelegate {
    @Override
    public void onAndroidPermissionsRequest(final GeckoSession session,
                                            final String[] permissions,
                                            final Callback callback) { }

    @Override
    public void onContentPermissionRequest(final GeckoSession session,
                                           final String uri,
                                           final int type, final Callback callback) { }

    @Override
    public void onMediaPermissionRequest(final GeckoSession session,
                                         final String uri,
                                         final MediaSource[] video,
                                         final MediaSource[] audio,
                                         final MediaCallback callback) { }
}
```

--------------------------------

### Preview Expected API Changes

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/geckoview-quick-start.html

Preview the expected changes to the GeckoView API before generating the `api.txt` file. This command helps in understanding the impact of API modifications. The build is expected to fail, providing details on detected changes.

```bash
./mach gradle geckoview:apiLintDebug

```

--------------------------------

### WebExtensionController.setPromptDelegate

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/design/managing-extensions.html

Sets the delegate responsible for handling user prompts.

```APIDOC
## POST /WebExtensionController/setPromptDelegate

### Description
Assigns a `PromptDelegate` object to the `WebExtensionController`. This delegate will be used to handle all user-facing prompts related to extensions.

### Method
POST

### Endpoint
/WebExtensionController/setPromptDelegate

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **promptDelegate** (PromptDelegate) - Required - The delegate object that implements the `PromptDelegate` interface.

### Request Example
```json
{
  "promptDelegate": {
    "onInstallPrompt": "function() { ... }",
    "onUpdatePrompt": "function() { ... }",
    "onOptionalPrompt": "function() { ... }"
  }
}
```

### Response
#### Success Response (200)
- **Void** - Indicates the prompt delegate was successfully set.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Submit GeckoView Patch to Try Server

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/geckoview-quick-start.html

Use this command to submit a GeckoView patch to the try server for automated testing before submitting for review. Ensure critical tests from the GeckoView test suite are run.

```bash
./mach try --preset android-geckoview

```

--------------------------------

### Define LoginStorage structure and Delegate interface

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/design/login-storage-api.html

Defines the core Login data class, Hint constants for prompting behavior, and the Delegate interface for handling login lifecycle events.

```java
class LoginStorage {
    class Login {
        String guid;
        // @Fenix: currently called `hostname` in AsyncLoginsStorage.
        String origin;
        // @Fenix: currently called `formSubmitURL` in AsyncLoginsStorage
        String formActionOrigin;
        String httpRealm;
        String username;
        String password;
    }

    class Hint {
        // @Fenix: Automatically save the login and indicate this to the
        // user.
        int GENERATED;
        // @Fenix: Don’t prompt to save but allow the user to open UI to
        // save if they really want.
        int PRIVATE_MODE;
        // The data looks like it may be some other data (e.g. CC) entered
        // in a password field.
        // @Fenix: Don’t prompt to save but allow the user to open UI to
        // save if they want (e.g. in case the CC number is actually the
        // username for a credit card account)
        int LOW_CONFIDENCE;
        // TBD
    }

    interface Delegate {
        // Notify that the given login has been used for login.
        // @Fenix: call AsyncLoginsStorage.touch(login.guid).
        void onLoginUsed(Login login);

        // Request logins for the given domain.
        // @Fenix: return AsyncLoginsStorage.getByHostname(domain).
        GeckoResult<Login[]> onLoginRequest(String domain);

        // Request to save or update the given login.
        // The hint should help determining the appropriate user prompting
        // behavior.
        // @Fenix: Use the API from application-services/issues/1983 to
        // determine whether to show a Save or Update button on the
        // doorhanger, taking into account un/pw edits in the doorhanger.
        // When the user confirms the save/update,
        void onLoginSave(Login login, int hint);

        // TBD (next API iteration): handle autocomplete selection.
        // GeckoResult<Login> onLoginSelect(Login[] logins);
    }
}
```

--------------------------------

### Create Git Tag

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/apilint.html

Create a git tag with the branch version to mark the release.

```bash
$ git tag X.Y
```

--------------------------------

### Implement Runtime Translation Controller in Java

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/translations-toolkit-to-fenix.html

Java controller for querying runtime translation capabilities via the EventDispatcher.

```java
public class TranslationsController {
  public static class RuntimeTranslation {
    // Events dispatched to toolkit translations
    private static final String ENGINE_SUPPORTED_EVENT =
    "GeckoView:Translations:IsTranslationEngineSupported";

    @AnyThread
    public static @NonNull GeckoResult<Boolean> isTranslationsEngineSupported() {
    // Notice this isn’t the same event dispatcher as the session dispatcher and how to get the return value.
      return EventDispatcher.getInstance()
        .queryBoolean(ENGINE_SUPPORTED_EVENT)
        .map(
          result -> result,
          exception -> new TranslationsException(TranslationsException.ERROR_ENGINE_NOT_SUPPORTED));
    }
  }
}
```

--------------------------------

### Implement Runtime Translation Settings

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/translations-toolkit-to-fenix.html

Handles runtime translation events and registers the module for lazy loading.

```javascript
export const GeckoViewTranslationsSettings = {

  async onEvent(aEvent, aData, aCallback) {
    debug`onEvent ${aEvent} ${aData}`;
      switch (aEvent) {
        case "GeckoView:Translations:IsTranslationEngineSupported": {
         try {
           aCallback.onSuccess(lazy.TranslationsParent.getIsTranslationsEngineSupported());
         ...
}
```

```javascript
GeckoViewUtils.addLazyGetter(this, "GeckoViewTranslationsSettings", {
	module: "resource://gre/modules/GeckoViewTranslations.sys.mjs",
	ged: [
		"GeckoView:Translations:IsTranslationEngineSupported",
		"GeckoView:Translations:PreferredLanguages",
		"GeckoView:Translations:ManageModel",
		"GeckoView:Translations:TranslationInformation",
		"GeckoView:Translations:ModelInformation",
	],
});
```

--------------------------------

### Configure GeckoView Version in Gradle

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/consumer/geckoview-quick-start.html

Define the release channel and version variables in your module's build.gradle file.

```gradle
ext {
    geckoviewChannel = <channel>
    geckoviewVersion = <version>
}
```

--------------------------------

### Generate GeckoView Javadoc Locally

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/geckoview-quick-start.html

Run this command in your mozilla-unified directory to generate local Javadoc for GeckoView. Ensure you have the necessary build tools configured.

```bash
./mach android geckoview-docs
```

--------------------------------

### Configure WebExtension Manifest

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/consumer/web-extensions.html

Required permissions and settings for native messaging in the extension manifest.

```json
{
  "manifest_version": 2,
  "name": "messaging",
  "version": "1.0",
  "description": "Example messaging web extension.",
  "browser_specific_settings": {
    "gecko": {
      "id": "messaging@example.com"
    }
  },
  "content_scripts": [
    {
      "matches": ["*://*.twitter.com/*"],
      "js": ["messaging.js"]
    }
  ],
  "permissions": [
    "nativeMessaging",
    "nativeMessagingFromContent",
    "geckoViewAddons"
  ]
}
```

--------------------------------

### GeckoView Debug Configuration File Format

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/consumer/automation.html

YAML format for GeckoView configuration files, specifying environment variables, command-line arguments, and Gecko preferences.

```yaml
# Contents of /data/local/tmp/com.yourcompany.yourapp-geckoview-config.yaml

env:
  MOZ_LOG: nsHttp:5

args:
  - --marionette
  - --profile
  - "/path/to/gecko-profile"

prefs:
  foo.bar.boolean: true
  foo.bar.string: "string"
  foo.bar.int: 500

```

--------------------------------

### Generate Updated api.txt File

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/geckoview-quick-start.html

Generate a new `api.txt` file reflecting the public API changes. This command should be run after confirming that the API modifications are as expected. The build should pass upon successful generation.

```bash
./mach gradlew geckoview:apiUpdateFileDebug

```

--------------------------------

### Configure Android Debugger Wait

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/contributor/native-debugging.html

Use these commands to force an app or specific child process to wait for a debugger on startup.

```bash
adb shell am set-debug-app -w --persistent org.mozilla.geckoview_example
```

```bash
adb shell am set-debug-app -w --persistent org.mozilla.geckoview_example:gpu_disable_art_image_
```

--------------------------------

### Enable GeckoView Configuration File Reading

Source: https://firefox-source-docs.mozilla.org/mobile/android/geckoview/consumer/automation.html

Use `adb shell am set-debug-app --persistent` to enable GeckoView to read configuration from a file for a specific Android package.

```bash
adb shell am set-debug-app --persistent com.yourcompany.yourapp
```
Tokens:
Raw