MozillaWiki

Mobile/GeckoView: Difference between revisions

Page Discussion

Mobile/GeckoView (view source)

Revision as of 23:07, 20 September 2023

1,740 bytes added ,  20 September 2023
→‎Documentation and Examples: GeckoView Lite now requires Android 5.0 (API 21) or later.
(→‎Add GeckoView to your build.gradle: Describe GV version numbers)
(→‎Documentation and Examples: GeckoView Lite now requires Android 5.0 (API 21) or later.)
 
(27 intermediate revisions by 10 users not shown)
Line 1: Line 1:
== What is GeckoView ==
'''GeckoView''' wraps Mozilla's [https://wikipedia.org/wiki/Gecko_(software) Gecko browser engine] in a reusable Android library for applications that wish to use Mozilla’s JavaScript, HTML layout, and rendering engines (generally referred to as SpiderMonkey and Gecko).


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://www.mozilla.org/en-US/firefox/browsers/mobile/android/ Firefox for Android], [https://blog.mozilla.org/blog/2018/09/18/firefox-reality-now-available/ Firefox Reality], [https://www.mozilla.org/firefox/mobile/#focus Firefox Focus], and other Android apps. GeckoView serves a similar purpose to Android's built-in WebView, but it has its own APIs and is ''not'' a drop in replacement.


Note that GeckoView is not quite ready to be used in a production environment.
== Why GeckoView? ==


Current API documentation can be viewed here: https://mozilla.github.io/geckoview/javadoc/mozilla-central/
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.


== Testing GeckoView ==
In contrast, GeckoView is:


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.
* '''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.


* [https://github.com/mozilla-mobile/focus-android/wiki/Release-tracks#nightly How to install Focus Nightly]
== About GeckoView ==
* 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].
* 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! :)


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:
Mozilla provides a GeckoView package and a [https://maven.mozilla.org/?prefix=maven2/org/mozilla/geckoview/ Maven Repo] along with [https://mozilla.github.io/geckoview/javadoc/mozilla-central/org/mozilla/geckoview/package-summary.html package documentation]. GeckoView has Stable, Beta, and Nightly channels that follow the [https://wiki.mozilla.org/Release_Management/Calendar Firefox browser’s Release Calendar] which typically ships a new major version to the Stable channel every 4 weeks and the maven repository is updated accordingly.


# Leave the Focus beta program (by clicking the "LEAVE" button in the "You're a beta tester" section of Focus's Google Play page)
When a new version is released to the Stable channel, any relevant security fixes will be published to the [https://www.mozilla.org/en-US/security/advisories/ Mozilla Security Advisories page]. While GeckoView is not explicitly called out in the advisories, most but not strictly all vulnerabilities will affect GeckoView. Exceptions would be vulnerabilities that occur in user-facing components excluded from GeckoView (such as the address bar) or desktop-platform-specific vulnerabilities. Keeping the GeckoView dependency up-to-date is the most effective way to incorporate security fixes.
# 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 ==
== Getting Help ==


==== Add GeckoView to your build.gradle ====
Interested in GeckoView? We're here to help!


GeckoView builds are published in a Maven repository: [https://maven.mozilla.org/?prefix=maven2/org/mozilla/geckoview/ maven.mozilla.org] with three release channels:
If you have questions or need assistance, please reach out to us in the [https://chat.mozilla.org/#/room/#geckoview:mozilla.org #geckoview] Matrix room.


* Nightly: geckoview-nightly-armeabi-v7a
The overall Mozilla security team can be reached at security@mozilla.org.  If you ship GeckoView in your application you are encouraged to let us know at that address.
* Beta: geckoview-beta-armeabi-v7a
* Stable: geckoview-armeabi-v7a


And three different architectures:
== Get Started ==


* armeabi-v7a (32-bit ARM)
''Building a browser? Check out [https://mozilla-mobile.github.io/android-components/ Android Components], our collection of ready-to-use support libraries!''
* arm64-v8a (64-bit ARM aka AArch64)
* x86 (32-bit)
* Coming soon in {{bug|1480834}}: x86-64


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]. New major versions of the Stable channel are released every 6-8 weeks when a new major version of Firefox is released, but 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].
=== Configure Gradle ===


GeckoView build numbers use the format: MAJOR.MINOR.BUILD_ID, e.g. 63.0.20180904170936.
'''1. Set the GeckoView version'''


<pre>
''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.
<syntaxhighlight lang="Groovy">
ext {
    geckoviewChannel = "nightly"
    geckoviewVersion = "70.0.20190712095934"
}
</syntaxhighlight>
 
'''2. Add Mozilla's Maven repository'''
<syntaxhighlight lang="Groovy">
repositories {
repositories {
     maven {
     maven {
      url 'https://maven.mozilla.org/?prefix=maven2/'
        url "https://maven.mozilla.org/maven2/"
     }
     }
}
}
</pre>
</syntaxhighlight>
 
'''3. Configure Java 8 support'''


==== Add geckoview to dependencies ====
<syntaxhighlight lang="Groovy">
android {
    // ...


Again, in build.gradle
    // Note: compileOptions is only required for minSdkVersion < 24
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}
</syntaxhighlight>


<pre>
'''4. Add GeckoView Implementations'''
<syntaxhighlight lang="Groovy">
dependencies {
dependencies {
     implementation 'org.mozilla:geckoview:geckoview-nightly-armeabi-v7a:+'
    // ...
     implementation "org.mozilla.geckoview:geckoview-${geckoviewChannel}:${geckoviewVersion}" 
}
}
</pre>
</syntaxhighlight>
 
=== Add GeckoView to a Layout ===
 
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>


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).
=== Initialize GeckoView in an Activity ===


==== Loading a page in GeckoView ====
'''1. Import the GeckoView classes inside an Activity:'''
<syntaxhighlight lang="Java">
import org.mozilla.geckoview.GeckoRuntime;
import org.mozilla.geckoview.GeckoSession;
import org.mozilla.geckoview.GeckoView;
</syntaxhighlight>


You can now use GeckoView your app by including the following in a layout XML file:
'''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);


<pre>
session.open(runtime);
<org.mozilla.gecko.GeckoView
view.setSession(session);
  android:id="@+id/geckoview"
session.loadUri("about:buildconfig"); // Or any other URL...
  android:layout_width="fill_parent"
</syntaxhighlight>
  android:layout_height="wrap_content" />
</pre>


You can then load a page in your Activity with:
=== You're done! ===


<pre>
Your application should now load and display a webpage inside of GeckoView.
onCreate(...) {
    // Find the GeckoView in our layout
    GeckoView geckoView = (GeckoView) findViewById(R.id.geckoview);


    // Attach the GeckoView to a new GeckoSession
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].
    GeckoSession session = new GeckoSession();
    session.open();
    geckoView.setSession(session);


    // Load a URL
== Documentation and Examples ==
    session.loadUri("http://mozilla.com");
}
</pre>


== Example App ==
'''APIs'''
* [https://mozilla.github.io/geckoview/javadoc/mozilla-central/ GeckoView API Documentation] (JavaDoc format)
* [https://mozilla-mobile.github.io/android-components/reference/ Android Components APIs]


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:
'''Building / Contributing'''


<pre>mach gradle geckoview_example:installLocalWithGeckoBinariesNoMinApiDebug</pre>
* [https://mozilla.github.io/geckoview/contributor/geckoview-quick-start GeckoView Contributor Quick Start Guide].
* [[Mobile/Get_Involved]]
* [https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Introduction Mozilla Developer Guide]


You may find it easier to do this from Android Studio, where geckoview_example appears as a module.
'''Bugs'''


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.
* [https://bugzilla.mozilla.org/enter_bug.cgi?product=GeckoView&component=General File a new GeckoView bug]
* [https://bugzilla.mozilla.org/buglist.cgi?product=GeckoView&component=General&resolution=---&list_id=14532935 All GeckoView Bugs]
* [[Mobile/GeckoView/Bugs|GeckoView Bug Dashboard]] 🐛


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]
'''Products / Examples'''
* [https://blog.mozilla.org/futurereleases/2019/06/27/reinventing-firefox-for-android-a-preview/ Firefox Preview] ([https://github.com/mozilla-mobile/fenix GitHub])
* [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]


== Bugs ==
'''Minimum System Requirements'''


[[Mobile/GeckoView/Bugs|GeckoView bugs 🐛]]
* GeckoView, Fenix, and Focus all require Android 5.0 (API 21) or later.
* 32-bit ARMv7-A, 64-bit ARMv8-A (aka ARM64), 32-bit x86, or x86_64 CPU
* Minimum device specs are quad-core 1.2 GHz and 2 GB RAM (like the [https://www.gsmarena.com/compare.php3?&idPhone3=8104&idPhone2=8721&idPhone1=9008 Moto G4 Play, E4, or E5]), though Mozilla's GeckoView test devices are the [https://en.wikipedia.org/wiki/Moto_G5 Moto G5] with an octa-core 1.4 GHz CPU and 2 GB RAM and the [https://en.wikipedia.org/wiki/Pixel_2 Google Pixel 2] with an octa-core 1.9 GHz CPU and 4 GB RAM.
Cpeterson
Confirmed users
3,339

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/1200856...1248090"