GeckoView

GeckoView is the embeddable rendering engine Mozilla ships for Android. Think of it as WebView, but Gecko-based, with deep API surface and the same rendering as Firefox proper. Lives in mobile/android/geckoview/.

What it provides

• A GeckoView Android View subclass that renders web content.
• A GeckoSession that owns navigation, history, and content state.
• GeckoRuntime — the singleton process-host used by all sessions.
• A large set of delegates (Java interfaces with @UiThread callbacks) that let an embedder hook into navigation, prompts, content blocking, autofill, permissions, downloads, media, and more.

Directory layout

mobile/android/geckoview/
├── api.txt                # Stable Java API (linted to detect breakages)
├── CHANGELOG.md
├── docs/
├── src/main/java/org/mozilla/geckoview/
│   ├── GeckoView.java
│   ├── GeckoSession.java
│   ├── GeckoRuntime.java
│   ├── GeckoSessionSettings.java
│   ├── GeckoResult.java       # The Promise-like async type
│   ├── ContentBlocking.java
│   ├── ProfilerController.java
│   └── ...
├── src/main/aidl/             # AIDL interfaces for content/parent IPC on Android
└── src/test/, src/androidTest/  # Tests

Architecture

graph TD
    Embedder[Embedder app<br/>Fenix / 3rd-party] --> GeckoView[GeckoView Android View]
    GeckoView --> GeckoSession
    GeckoSession --> Runtime[GeckoRuntime]
    Runtime --> JNI[GeckoView JNI<br/>org.mozilla.gecko.*]
    JNI --> Native[libxul.so]
    Native --> Content[Gecko Content Process]
    Content --> Compositor[GPU compositor]
    Compositor --> Surface[Android Surface]
    GeckoSession <-->|delegates| Embedder

Delegate model

Embedders attach delegates to a GeckoSession to receive callbacks:

Delegate	Events
NavigationDelegate	URL load events, error pages, redirects
ProgressDelegate	Page-load progress, security state
ContentDelegate	Title, fullscreen, context menus
PromptDelegate	alert/confirm/auth/file/select
MediaSession.Delegate	Audio/video session events
ContentBlocking.Delegate	Tracker blocking notifications
PermissionDelegate	Geolocation, camera, etc.
AutocompleteDelegate / Autofill	Form autofill
HistoryDelegate	Visit recording

GeckoSession.setNavigationDelegate(...) etc.

Async with GeckoResult

GeckoView's async pattern is GeckoResult<T> — a Promise-like type defined in mobile/android/geckoview/src/main/java/org/mozilla/geckoview/GeckoResult.java. Methods that may suspend return GeckoResult<...> (e.g., GeckoSession.getSurfaceTexture() for screen captures, runtime APIs).

API stability

GeckoView publishes a binary-stable API checked against mobile/android/geckoview/api.txt. Adding or changing public types requires updating the API file in the same patch and runs through a CI lint to catch incompatible changes.

Building

ac_add_options --enable-application=mobile/android
./mach build
./mach package      # builds AAR under <objdir>/gradle/.../geckoview-*.aar

The resulting AAR can be consumed by any Android app that depends on org.mozilla.geckoview:geckoview.

Examples

• mobile/android/geckoview_example/ — minimal embedding sample.
• mobile/android/fenix/ — the production embedder.

Related

• Firefox for Android
• Process model