Mobile/GeckoView: Difference between revisions

Revision as of 16:07, 10 October 2018

GeckoView is Firefox Quantum's engine, packaged as a reusable Android library.

Mozilla uses GeckoView to power Firefox Reality, Firefox Focus, and more.

GeckoView serves a similar purpose to Android's built-in WebView, but it has its own APIs and is not a drop in replacement.

Why GeckoView?

While Android offers a built-in WebView, it's not intended for building browsers, and many advanced Web APIs are disabled. Android's WebView is also a moving target: it's impossible know exactly which engine (and what version of that engine) will power a WebView on client devices.

In contrast, GeckoView is:

Full-Featured: GeckoView is designed to expose the entire power of the Web to applications, including being suitable for building web browsers.
Self-Contained: Because GeckoView is a standalone library that you bundle with your application, you can be confident that the code you test is the code that will actually run.
Standards Compliant: Like Firefox, GeckoView offers excellent support for modern Web standards. WebAssembly, CSS Grid, or Variable Fonts? No problem!

Get Started

Building a browser? Check out Android Components, our collection of ready-to-use support libraries!

Configure Gradle

You need to add or edit four stanzas inside your module's build.gradle file.

1. Set the GeckoView version

Like Firefox, GeckoView has three release channels: Stable, Beta, and Nightly. Browse the Maven Repository to see currently available builds.

ext {
    geckoviewChannel = "nightly"
    geckoviewVersion = "64.0.20180927100037"
}

2. Add Mozilla's Maven repository

repositories {
    maven {
        url "https://maven.mozilla.org/maven2/"
    }
}

3. Configure build flavors

Note: Until we resolve Bug 1485045, you must configure a separate build variant for each CPU architecture.

android {
    // ...

    // Note: compileOptions is only required for minSdkVersion < 24
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }

    flavorDimensions "abi"

    productFlavors {
        x86     { dimension "abi" }
        x86_64  { dimension "abi" }
        arm     { dimension "abi" }
        aarch64 { dimension "abi" }
    }
}

4. Add GeckoView Implementations

dependencies {
    // ...

    x86Implementation     "org.mozilla.geckoview:geckoview-${geckoviewChannel}-x86:${geckoviewVersion}"
    x86_64Implementation  "org.mozilla.geckoview:geckoview-${geckoviewChannel}-x86_64:${geckoviewVersion}"
    armImplementation     "org.mozilla.geckoview:geckoview-${geckoviewChannel}-armeabi-v7a:${geckoviewVersion}"
    aarch64Implementation "org.mozilla.geckoview:geckoview-${geckoviewChannel}-arm64-v8a:${geckoviewVersion}"
}

Add GeckoView to a Layout

Inside a layout .xml file, add the following:

<org.mozilla.geckoview.GeckoView
    android:id="@+id/geckoview"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent" />

Initialize GeckoView in an Activity

1. Import the GeckoView classes inside an Activity:

import org.mozilla.geckoview.GeckoRuntime;
import org.mozilla.geckoview.GeckoSession;
import org.mozilla.geckoview.GeckoView;

2. In that activity's onCreate function, add the following:

GeckoView view = findViewById(R.id.geckoview);
GeckoSession session = new GeckoSession();
GeckoRuntime runtime = GeckoRuntime.create(this);

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

You're done!

Your application should now load and display a webpage inside of GeckoView.

To learn more about GeckoView's capabilities, review GeckoView's JavaDoc or the reference application.

Getting Help

Interested in GeckoView? We're here to help.

If you find a bug or need assistance, please reach out by either:

Filing a bug
Talking to us in #mobile on irc.mozilla.org.

Documentation and Examples

APIs

Building / Contributing

Bugs

Products / Examples

@@ Line 1: / Line 1: @@
-== What is GeckoView ==
+'''GeckoView is [https://www.mozilla.org/firefox/ Firefox Quantum's] engine, packaged as a reusable Android library.'''
-GeckoView is an Android library project that allows third-party developers to use Gecko as an Android View in their own applications. GeckoView is similar to Android's built in WebView, but '''it is not a drop in replacement for WebView'''.
+Mozilla uses GeckoView to power [https://blog.mozilla.org/blog/2018/09/18/firefox-reality-now-available/ Firefox Reality], [https://www.mozilla.org/firefox/mobile/#focus Firefox Focus], and more.
-Note that GeckoView is not quite ready to be used in a production environment.
+GeckoView serves a similar purpose to Android's built-in WebView, but it has its own APIs and is ''not'' a drop in replacement.
-Current API documentation can be viewed here: https://mozilla.github.io/geckoview/javadoc/mozilla-central/
+== Why GeckoView? ==
-== Testing GeckoView ==
+While Android offers a built-in WebView, it's not intended for building browsers, and many advanced Web APIs are disabled. Android's WebView is also a moving target: it's impossible know exactly which engine (and what version of that engine) will power a WebView on client devices.
-GeckoView is a library, not a standalone app, but you can test GeckoView by installing Focus Nightly "track" (channel). Focus 6.0 and earlier use Android's WebView, but Focus 7.0 is switching to Mozilla's homegrown Gecko. Unfortunately, Google Play only allows you to install one track (per Google Play account) at a time. Installing Focus Nightly will uninstall the regular Focus and replace it (and your settings) with Focus Nightly. If you have multiple Google Play accounts, then you can install a different Focus track in each account.
+In contrast, GeckoView is:
-* [https://github.com/mozilla-mobile/focus-android/wiki/Release-tracks#nightly How to install Focus Nightly]
+* '''Full-Featured''': GeckoView is designed to expose the entire power of the Web to applications, including being suitable for building web browsers.
-* If you have questions, you're welcome to drop by the #focus IRC channel on [https://wiki.mozilla.org/IRC Mozilla's IRC server] or ask in the [https://groups.google.com/forum/#!forum/focus-klar-nightly focus-klar-nightly Google Group].
+* '''Self-Contained''': Because GeckoView is a standalone library that you bundle with your application, you can be confident that the code you test is the code that will actually run.
-* If you've found a bug in Focus Nightly compared to Focus using WebView, then check the [https://github.com/mozilla-mobile/focus-android/issues Focus bug tracker] to see if there is a bug filed. If not, please file one! :)
+* '''Standards Compliant''': Like Firefox, GeckoView offers excellent support for modern Web standards. WebAssembly, CSS Grid, or Variable Fonts? No problem!
-If you joined the Focus beta program ''before'' subscribing to the focus-klar-nightly Google Group, Google Play might not upgrade you to the new Focus Nightly right away. Google Play treats the Focus beta and nightly tracks as different flavors of beta and can forget to switch you from the regular beta to the nightly "beta" track. In this case, try:
+== Get Started ==
-# Leave the Focus beta program (by clicking the "LEAVE" button in the "You're a beta tester" section of Focus's Google Play page)
+''Building a browser? Check out [https://mozilla-mobile.github.io/android-components/ Android Components], our collection of ready-to-use support libraries!''
-# Uninstall Focus
-# Re-join the beta program
-# Re-install Focus
-# Open the Play Store app, open the "My apps & games" screen, select the "BETA" tab, and check for "Firefox Focus: The privacy browser" UPDATE button.
-== Using GeckoView ==
+=== Configure Gradle ===
-=== GeckoView Releases ===
+You need to add or edit four stanzas inside your module's <code>build.gradle</code> file.
-Like Firefox, GeckoView has three three release channels: '''Nightly''', '''Beta''', and '''Stable''' (production). GeckoView supports three different architectures:
+'''1. Set the GeckoView version'''
-* '''armeabi-v7a''' (32-bit ARM)
+''Like Firefox, GeckoView has three release channels: Stable, Beta, and Nightly. Browse the [https://maven.mozilla.org/?prefix=maven2/org/mozilla/geckoview/ Maven Repository] to see currently available builds.
-* '''arm64-v8a''' (64-bit ARM aka AArch64)
+<syntaxhighlight lang="Groovy">
-* '''x86''' (32-bit)
+ext {
-* Coming soon in {{bug|1480834}}: '''x86-64'''
+    geckoviewChannel = "nightly"
+    geckoviewVersion = "64.0.20180927100037"
+}
+</syntaxhighlight>
-GeckoView build numbers use the format: MAJOR.MINOR.BUILD_ID, e.g. 63.0.20180904170936.
+'''2. Add Mozilla's Maven repository'''
+<syntaxhighlight lang="Groovy">
+repositories {
+    maven {
+        url "https://maven.mozilla.org/maven2/"
+    }
+}
+</syntaxhighlight>
-==== Release Schedule ====
+'''3. Configure build flavors'''
-New major versions of GeckoView Stable are published every 6-8 weeks, following the [https://wiki.mozilla.org/Release_Management/Calendar#Calendars Firefox release schedule]. Minor dot releases with security fixes may be released more frequently. The Stable channel is built from a release branch ("relbranch") in the [mozilla-release repository] with a branch name like [https://hg.mozilla.org/releases/mozilla-release/shortlog/GECKOVIEW_62_RELBRANCH GECKOVIEW_62_RELBRANCH].
+''Note: Until we resolve [https://bugzilla.mozilla.org/show_bug.cgi?id=1485045 Bug 1485045], you must configure a separate build variant for each CPU architecture.''
-New Nightly builds are released every day from Firefox's [https://hg.mozilla.org/mozilla-central/ mozilla-central repository]. New Beta builds are released once or twice a week from Firefox/Gecko's [https://hg.mozilla.org/releases/mozilla-beta mozilla-beta repository].
+<syntaxhighlight lang="Groovy">
+android {
+    // ...
-==== Add GeckoView to your build.gradle ====
+    // Note: compileOptions is only required for minSdkVersion < 24
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+    }
-GeckoView builds are published in a Maven repository: [https://maven.mozilla.org/?prefix=maven2/org/mozilla/geckoview/ maven.mozilla.org] for each release channel and architecture. The build naming convention is "geckoview-$CHANNEL-$ARCH", e.g. geckoview-nightly-armeabi-v7a, geckoview-beta-arm64-v8a, and geckoview-x86.
+    flavorDimensions "abi"
-<pre>
+    productFlavors {
-repositories {
+        x86     { dimension "abi" }
-     maven {
+        x86_64  { dimension "abi" }
-       url 'https://maven.mozilla.org/?prefix=maven2/'
+        arm     { dimension "abi" }
+        aarch64 { dimension "abi" }
      }
 }
-</pre>
+</syntaxhighlight>
+'''4. Add GeckoView Implementations'''
+<syntaxhighlight lang="Groovy">
+dependencies {
+    // ...
+    x86Implementation     "org.mozilla.geckoview:geckoview-${geckoviewChannel}-x86:${geckoviewVersion}"
+    x86_64Implementation  "org.mozilla.geckoview:geckoview-${geckoviewChannel}-x86_64:${geckoviewVersion}"
+    armImplementation     "org.mozilla.geckoview:geckoview-${geckoviewChannel}-armeabi-v7a:${geckoviewVersion}"
+    aarch64Implementation "org.mozilla.geckoview:geckoview-${geckoviewChannel}-arm64-v8a:${geckoviewVersion}"
+}
+</syntaxhighlight>
+=== Add GeckoView to a Layout ===
-==== Add geckoview to dependencies ====
+Inside a layout <code>.xml</code> file, add the following:
+<syntaxhighlight lang="XML">
+<org.mozilla.geckoview.GeckoView
+    android:id="@+id/geckoview"
+    android:layout_width="fill_parent"
+    android:layout_height="fill_parent" />
+</syntaxhighlight>
-Again, in build.gradle
+=== Initialize GeckoView in an Activity ===
-<pre>
+'''1. Import the GeckoView classes inside an Activity:'''
-dependencies {
+<syntaxhighlight lang="Java">
-    implementation 'org.mozilla:geckoview:geckoview-nightly-armeabi-v7a:+'
+import org.mozilla.geckoview.GeckoRuntime;
-}
+import org.mozilla.geckoview.GeckoSession;
-</pre>
+import org.mozilla.geckoview.GeckoView;
+</syntaxhighlight>
-This will always use the latest Nightly in the repository. As GeckoView development continues, we will have Beta and Release repositories that have the expected version names (62.0.0, etc).
+'''2. In that activity's <code>onCreate</code> function, add the following:'''
+<syntaxhighlight lang="Java">
+GeckoView view = findViewById(R.id.geckoview);
+GeckoSession session = new GeckoSession();
+GeckoRuntime runtime = GeckoRuntime.create(this);
-==== Loading a page in GeckoView ====
+session.open(runtime);
+view.setSession(session);
+session.loadUri("about:buildconfig"); // Or any other URL...
+</syntaxhighlight>
-You can now use GeckoView your app by including the following in a layout XML file:
+=== You're done! ===
-<pre>
+Your application should now load and display a webpage inside of GeckoView.
-<org.mozilla.gecko.GeckoView
-  android:id="@+id/geckoview"
-  android:layout_width="fill_parent"
-  android:layout_height="wrap_content" />
-</pre>
-You can then load a page in your Activity with:
+To learn more about GeckoView's capabilities, review GeckoView's [https://mozilla.github.io/geckoview/javadoc/mozilla-central/ JavaDoc] or the [https://searchfox.org/mozilla-central/source/mobile/android/geckoview_example reference application].
-<pre>
+== Getting Help ==
-onCreate(...) {
-    // Find the GeckoView in our layout
-    GeckoView geckoView = (GeckoView) findViewById(R.id.geckoview);
-    // Attach the GeckoView to a new GeckoSession
+Interested in GeckoView? We're here to help.
-    GeckoSession session = new GeckoSession();
-    session.open();
-    geckoView.setSession(session);
-    // Load a URL
+If you find a bug or need assistance, please reach out by either:
-    session.loadUri("http://mozilla.com");
-}
-</pre>
-== Example App ==
+* [https://bugzilla.mozilla.org/enter_bug.cgi?product=Firefox%20for%20Android&component=GeckoView Filing a bug]
+* Talking to us in [ircs://irc.mozilla.org:6697/#mobile #mobile] on [[Irc|irc.mozilla.org]].
-GeckoViewExample is an example app that [https://searchfox.org/mozilla-central/source/mobile/android/geckoview_example/src/main/java/org/mozilla/geckoview_example/GeckoViewActivity.java lives in mozilla-central] and lets you easily exercise GeckoView. You can build/install it with the following gradle command:
+== Documentation and Examples ==
-<pre>mach gradle geckoview_example:installLocalWithGeckoBinariesNoMinApiDebug</pre>
+'''APIs'''
+* [https://mozilla.github.io/geckoview/javadoc/mozilla-central/ JavaDoc API Documentation]
+* [https://mozilla-mobile.github.io/android-components/reference/ Android Components APIs]
-You may find it easier to do this from Android Studio, where geckoview_example appears as a module.
+'''Building / Contributing'''
-Firefox Focus also has a build variant that uses Gecko. To build, check out the Focus code from <code>https://github.com/mozilla-mobile/focus-android</code> and follow the [https://github.com/mozilla-mobile/focus-android/blob/master/README.md instructions]. The only difference is you need to select one of the Gecko build variants from the Android Studio 'Build' menu.
+* [[Mobile/Get_Involved]]
+* [https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Introduction Mozilla Developer Guide]
-The Gecko-related code for Focus lives in [https://github.com/mozilla-mobile/focus-android/blob/90bf62d89919d5ae2d8bd95954491264dcbe1bba/app/src/gecko/java/org/mozilla/focus/web/WebViewProvider.java WebViewProvider.java]
+'''Bugs'''
-== Bugs ==
+* [https://bugzilla.mozilla.org/buglist.cgi?product=Firefox%20for%20Android&component=GeckoView&resolution=---&list_id=14376671 All GeckoView Bugs]
+* [[Mobile/GeckoView/Bugs|GeckoView Bug Dashboard]] 🐛
-[[Mobile/GeckoView/Bugs|GeckoView bugs 🐛]]
+'''Products / Examples'''
+* [https://blog.mozilla.org/blog/2018/09/18/firefox-reality-now-available/ Firefox Reality] ([https://github.com/mozillareality/firefoxreality GitHub])
+* [https://www.mozilla.org/firefox/mobile/#focus Firefox Focus] ([https://github.com/mozilla-mobile/focus-android/ GitHub])
+* [https://searchfox.org/mozilla-central/source/mobile/android/geckoview_example GeckoView Reference Application]

Mobile/GeckoView: Difference between revisions

Revision as of 16:07, 10 October 2018

Contents

Why GeckoView?

Get Started

Configure Gradle

Add GeckoView to a Layout

Initialize GeckoView in an Activity

You're done!

Getting Help

Documentation and Examples

Navigation menu

Mobile/GeckoView: Difference between revisions

Revision as of 16:07, 10 October 2018

Why GeckoView?

Get Started

Configure Gradle

Add GeckoView to a Layout

Initialize GeckoView in an Activity

You're done!

Getting Help

Documentation and Examples

Navigation menu

Search