mozilla / geckoview

GeckoView is a set of components for embedding Gecko in Android apps

This GitHub repository contains the documentation for GeckoView. If you are looking for the code for GeckoView you can find it at Mozilla Central.

If there is documentation that you feel is missing, or an existing document doesn't cover the aspect that you are looking for, please request it by raising an issue.

If you have a GeckoView bug that you want to raise, please do so on our Bugzilla.

Get Started with GeckoView

• GeckoView Quick Start Guide
• Interacting with Web content and WebExtension

API Documentation

• Changelog
• API

Get Started as a Contributor

• GeckoView Contributor Quick Start Guide
• Mozilla Central Quick Start Guide
• Mozilla Central Contributor Guide
• Guide to Native Debugging in Android Studio

More information

You can read more about GeckoView on the wiki.

geckoview's Issues

Developer documentation for new Git contributors is outdated

I want to contribute a feature to Firefox Preview that requires changes to GeckoView. The Contributor Guide for GeckoView says that Git users should see the Quick Start Guide for Git Users. However, this guide does not work for the latest version of GeckoView. (I use Arch Linux.)

Trying to run git remote update after adding the central and inbound remotes by running the commands in the guide fails with this error.

$ git remote update
Fetching central
adding changesets
adding manifests
adding file changes
added 505303 changesets with 3376734 changes to 549138 files
new changesets 8ba995b74e18:32f84899fc00
fatal: couldn't find remote ref refs/heads/branches/default/tip
error: Could not fetch central
Fetching inbound
no changes found
fatal: couldn't find remote ref refs/heads/branches/default/tip
error: Could not fetch inbound

So I tried adding the remotes without specifying the tip reference and git remote update proceeds, but it takes over a day to download the entire version history of the mozilla-central repository.

Then I gave up and looked at the guide they said was "for Mercurial users" and it says you can specify Git as your VCS using the bootstrap script they provide.

python bootstrap.py --vcs=git

I think this should be clarified since I use Git instead of Mercurial, and saying that if I used Git that I should read the outdated "quick start" guide was confusing.

Can i use GeckoView for my commercial app?

Can i use this geckoview engine for my commercial web browser app and make some benefit?
Where can i see the license to find allowed permissions?

Monitoring questions on StackOverflow

I noticed there are multiple recent opened questions asked related to GeckoView. StackOverflow is the first place to go when developers have questions, I think monitoring and replying could help to bring more developers to GeckoView. I'm not sure if this is the right moment to do it,but it will be helpful to start doing it that at some point.

CODE_OF_CONDUCT.md file missing

As of January 1 2019, Mozilla requires that all GitHub projects include this CODE_OF_CONDUCT.md file in the project root. The file has two parts:

1. Required Text - All text under the headings Community Participation Guidelines and How to Report, are required, and should not be altered.
2. Optional Text - The Project Specific Etiquette heading provides a space to speak more specifically about ways people can work effectively and inclusively together. Some examples of those can be found on the Firefox Debugger project, and Common Voice. (The optional part is commented out in the raw template file, and will not be visible until you modify and uncomment that part.)

If you have any questions about this file, or Code of Conduct policies and procedures, please see Mozilla-GitHub-Standards or email [email protected].

(Message COC001)

Usage Documentation: Permissions

Blocks #8

Documentation showing how to handle permissions when using GeckoView, with special focus on those that require GV integration such as geolocation and payment APIs.

Other things to think about:

• Password manager integration?

Add a section discussing how to use Mozilla's symbol server to debug GeckoView in consuming Apps

GeckoView (and other native code libraries, including megazord libraries built and published by the Application Services team) pushes debug symbols to Mozilla's crash reporting infrastructure. Downstream consuming Apps can fetch those symbols and use them in the Android Studio Native debugger. This ticket tracks documenting how to do this (and making sure that it works, I guess).

In particular, see Ted's scripts for fetching in GDB and for fetching in lldb.

Here's another note here that I posted in Mozilla's #android-tips channel:

Folks, if you need to turn a GeckoView version like 68.0.20190403060632 into an HG revision, you want buildhub: try a query like https://mozilla-services.github.io/buildhub/?platform[0]=android-api-16&locale[0]=en-US&q=20190403060632 and observe the HG revision 6188f3 link.

Bad armImplementation gradle configuration for custom GV build in tutorial

There's a typo in the armImplementation command in the tutorial about contributing to GV. Patch to follow.

Add metadata for easier Googling

Our docs page isn't easily found on Google. Adding some <meta> tags on the landing page might help the situation.

Usage Documentation: Media

Documenting how to interact with Media using GeckoView.

Blocks #8

how to navigate to unix domain socket when use local server listening on uds?

How to navigate to unix domain socket when use local server listening on uds?

for something like http://udx-fd/xxx.

Add support for general.useragent.override.website.domain

For some reason, support for the general.useragent.override.website.domain option in about:config has been removed in the latest nightlies. I opened a bug on the Fenix issue tracker (mozilla-mobile/fenix#5642), where I was told that the option is not supported in GeckoView.

This is a then a feature request to readd support for this option, since it was working before, it is supported on Gecko (it does work on Fennec, with which you want feature parity, I suppose) and there is already a general.useragent.override option that works for every website, so I don't really see why a per site implementation should not be supported.

WebRequest, WebResponse

I tried to fetch html by using WebRequest class and i got a WebResponse through a GeckoWebExecutor object.
And then i converted the WebResponse object to a string object.
And then i loaded the string object by using loadString or loadData as a text/html mime type.
But it couldn't render the page perfectly like it couldn't print some images which was printed when i just used loadUri with a url.
Could you please tell me why this's happening and how to solve?

User Documentation: Privacy and Security

Blocks #8

Documentation demonstrating the privacy and security options provided by GeckoView and how to implement them for best practice.

Home Page

The GeckoView site needs a landing page. This page should present an overview of GeckoView to developers looking for an alternative to WebView for displaying web content. It should allow developers to quickly decide whether GeckoView is able to meet their needs and provide clear guidance on next steps.

The page should present information about:

• What is GeckoView
• Why makes GeckoView different
• Why should I use GeckoView over WebView or Chromium
• What are GeckoView's top line featutes.

This area should also provide links into Android Components.

Meta bug: https://bugzilla.mozilla.org/show_bug.cgi?id=1519888

Fix broken custom CSS for just-the-docs theme on GitHub Pages

Locally, the css is being correctly overwritten, but when published to GH Pages the custom css is being ignored. This should be investigated and amended to ensure that the correct css is being imported.

Calling methods in android code from JS

I have an app which uses webview as of now for loading html based games. I use @JavascriptInterface in my activity to expose some methods to the JS code because of some requirements. But now i am planning to geckoview due to some reasons.
If anyone can lead to me to some alternatives that i can use while using geckoview to provide the same functionality, that would be great.

Usage Documenation: Debugging

Blocks #8

Documentation showing how to debug web based content in GeckoView

[meta] GeckoView "Consumer" site

One of the purposes of the GeckoView site is to provide information to enable developers who want to use GeckoView inside their app to quickly achieve their goals. This "subsite" of the website should provide developers with:

• Access to GeckoView's API documentation
• List of GeckoView's features with brief descriptions and links to associated API pages
• Usage documentation showing how to achieve common tasks

Meta bug: https://bugzilla.mozilla.org/show_bug.cgi?id=1519888

Intercept network requests

Is it possible to have something like WebView.shouldInterceptRequest in GeckoView? If it is already has, could you please give some examples how to?

Required attribute on input is not respected

When interacting with a form which has the "required" attribute on an input, Firefox Focus will ignore it and submit the form anyway when the input is empty. This only happens in Firefox Focus when GeckoView is enabled. The example here, or any other use of the attribute, will fail to function properly: https://developer.mozilla.org/en-US/docs/Learn/HTML/Forms/Form_validation#The_required_attribute

GeckoView 65
Focus 8.0.8
Android 8.0.1

GeckoView error occurred, Using App Bundle in GooglePlay

Hello, I used GeckoView in my Android app.

Implementation 'org.mozilla.geckoview:geckoview-beta:69.0.20190808090046'
abiFilters "armeabi-v7a", "arm64-v8a"

Using App Bundle in GooglePlay, an error occurred

Load sqlite start
Couldn't get a handle to libnss3!
Throw
Load sqlite done
>>> REPORTING UNCAUGHT EXCEPTION FROM THREAD 6519 ("Gecko")
java.lang.Exception: Error loading sqlite libraries
    at org.mozilla.gecko.mozglue.GeckoLoader.loadSQLiteLibsNative(Native Method)
    at org.mozilla.gecko.mozglue.GeckoLoader.loadSQLiteLibs(GeckoLoader.java:250)
    at org.mozilla.gecko.GeckoThread.initGeckoEnvironment(GeckoThread.java:114)
    at org.mozilla.gecko.GeckoThread.run(GeckoThread.java:165)
Main thread (1) stack:
    android.os.BinderProxy.transactNative(Native Method)
    android.os.BinderProxy.transact(Binder.java:496)
    com.android.internal.view.IInputMethodManager$Stub$Proxy.windowGainedFocus(IInputMethodManager.java:730)
    android.view.inputmethod.InputMethodManager.startInputInner(InputMethodManager.java:1230)
    android.view.inputmethod.InputMethodManager.onWindowFocus(InputMethodManager.java:1447)
    android.view.ViewRootImpl$ViewRootHandler.handleMessage(ViewRootImpl.java:3423)
    android.os.Handler.dispatchMessage(Handler.java:102)
    android.os.Looper.loop(Looper.java:135)
    android.app.ActivityThread.main(ActivityThread.java:5595)
    java.lang.reflect.Method.invoke(Native Method)
    java.lang.reflect.Method.invoke(Method.java:372)
    com.android.internal.os.ZygoteInit$MethodAndArgsCaller.run(ZygoteInit.java:960)
    com.android.internal.os.ZygoteInit.main(ZygoteInit.java:755)
Error getting package info
android.content.pm.PackageManager$NameNotFoundException: org.mozilla.fennec
    at android.app.ApplicationPackageManager.getPackageInfo(ApplicationPackageManager.java:123)
    at org.mozilla.gecko.CrashHandler.getCrashExtras(CrashHandler.java:234)
    at org.mozilla.gecko.GeckoAppShell$1.getCrashExtras(GeckoAppShell.java:143)
    at org.mozilla.gecko.CrashHandler.reportException(CrashHandler.java:377)
    at org.mozilla.gecko.GeckoAppShell$1.reportException(GeckoAppShell.java:187)
    at org.mozilla.gecko.CrashHandler.uncaughtException(CrashHandler.java:428)
    at org.mozilla.gecko.GeckoAppShell$1.uncaughtException(GeckoAppShell.java:162)
    at java.lang.ThreadGroup.uncaughtException(ThreadGroup.java:693)
    at java.lang.ThreadGroup.uncaughtException(ThreadGroup.java:690)

Web extension `WebRequest` is undefined

I made like this:
manifest.json

{
  "manifest_version": 2,
  "name": "messaging",
  "version": "1.0",
  "description": "Example messaging web extension.",
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["messaging.js"],
      "run_at": "document_start"
    }
  ],
  "permissions": [
    "nativeMessaging",
    "geckoViewAddons",
    "webRequest",
    "webRequestBlocking"
  ]
}

messaging.js
console.log(browser.webRequest)
it's write what it is undefined.
What am i doing wrong?

Also i've tried load as background script

"background": {
    "scripts": ["messaging.js"]
  },

but it doesn't works either.

Add pageload lifecycle docs

Managing page load is definitely tricky. We should at least document what's the expected flow from onLoadStart to onPageStop (or any other way a page request can stop) when an app calls loadUri or similar.

How to add permissions

I find it very hard / impossible to understand how to give GeckoView permission to use the microphone. I tried to google, ask in different forums but could not get an answer.
Could anybody help me with that?
My goal is to give GeckoView permission that a website uses the microphone/records.

Thanks!

Usage Documentation: WebView to GeckoView migration guide

Blocks #8

Many of the developers looking to use GeckoView may be looking to move their apps from WebView based apps to GeckoView, or are at least familiar with the existing WebView API's. This guide should show how a simple browser app that currently uses WebView can be migrated to use GeckoView instead.

Usage Documentation: Tracking Protection

Explain what the different tracking protection options in GeckoView are and how to update the settings. Also explain what the defaults are and what it means.

Usage Documentation: WebExtensions

Document how to use and implement WebExtensions using GeckoView

Blocks #8

Usage Documentation: MultiTab support

Blocks #8

Simple demonstration of how to implement multi-tab support with GV. This should include session management practices and multiprocess support.

Developer Blog

Implement a section of the platform that can be used for blogging purposes so that the team can share interesting work, things learned and start a conversation with developers.

The purpose of the developer site is to provide an area where interested developers and potential partners can monitor progress of the project and feel a part of the process.

The blog is also a good place through which to announce/highlight new features, new releases, new partners and new embedding apps.

Usage Documentation: Building a Browser

Blocks #8

Documentation showing, with reference to a simple example application, how to build a browser using GeckoView.

This documentation should link into Android Components.

Some links in Readme give 404

These are the dead links in the readme file.

GeckoView Contributor Quick Start Guide
Mozilla Central Quick Start Guide
Mozilla Central Contributor Guide
Guide to Native Debugging in Android Studio

Duplicated menu sections

Publish Roadmap

Blocks #19

Publish the public roadmap. This should be an overview of the more detailed internal roadmap and be designed as a aid to help potential consumers decide of GV is right for them and to guide potential contributors to work on the right features/bugs.

[Placeholder] GeckoView Features Listing

Child of #8

A page listing GeckoView's features with links to related API documentation and to usage documentation for those features.

TBD: What "features" do we want to place here?

• Navigation
• History
• Multiprocess support
• Session Management
• Content Scripts / JS / CSS interaction

Update Quick Start documentation to include fat AAR instructions.

https://bugzilla.mozilla.org/show_bug.cgi?id=1508976 introduced a single multi-architecture AAR for GeckoView, but our Quick Start guide still refers to setting up multiple architectures. This needs to be updated to reflect the existing requirements.

Wiki changes

FYI: The following changes were made to this repository's wiki:

• defacing spam has been removed

• Restricting write access to contributors is strongly encouraged. Please make that change (documentation).

These were made as the result of a recent automated defacement of publically writeable wikis.

[Meta] "Contributor" site

The website should have an area dedicated to providing resources to developer who wish to work on GeckoView. This includes developers employed by current and potential partners, as well as independent interested parties.

The subsite should contain:

• The current roadmap to enable potential contributors to decide what to work on and for potential consumers to decide if future work will make GV more suitable for their needs.
• Links to bugs and features that need working on
• Tutorial guides to help contributors get up and running with becoming a contributor
• FAQ's to ensure that only commonly asked questions are addressed without recourse to direct contact.
• Contact points for contributors to ask questions

How to get source code of a page

I wanna to know how to get source code a page with GeckoView.

Usage Documentation: Quick Start Guide

Blocks #8

Move the existing quick start guide written by @callahad into the GH pages site.

https://wiki.mozilla.org/Mobile/GeckoView#Get_Started

messaging_example exception

GeckoConsole: [JavaScript Error: "this.manifest is null" {file: "resource://gre/modules/Extension.jsm" line: 1110}]

An error occurred while registering the WebExtension resource://android/assets/messaging/: TypeError: this.manifest is null.

Create a process for proposing and reviewing changes to the GeckoView API

We currently have no process for proposing, curating and reviewing significant changes to GeckoViews APIs. This has led to situations where it has been difficult to receive feedback on APIs before the code has been written, which in turns results in a protracted period of change as the new API evolves to fit the changing requirements.

We propose that that we put in an RFC (Request For Change) process for significant changes to GeckoView APIs. This will consist a template for proposing changes that will guide developers through thinking about the API change, and allow for a format review period to gather feedback and consensus on the change ensuring that the final proposal fits all requirements.

Page looks broken

Something happened to our style? I don't see any change though.

Usage Documentation: Lifecycle Management

Blocks #8

Documentation showing how to implement GV lifecycle management including startup, shutdown, backgrounding, rotation, crash handling and configuration changes.

missing license file

As the title suggests, there's no LICENSE file in the repository, which reduces the usability of the component.
As I'm not certain which license Mozilla uses I couldn't create a pull req.

Changelog links are broken

something broke recently :( let's see if I can figure out what.

Usage Documentation: JS Execution

Documenting the ways in which you can interact with JavaScript using GeckoView including Content Scripts.

Blocks #8

No documentation of build targets

In the Quick Start Guide there is no documentation for existing targets. Running ./mach bootstrap to only get to know possible targets is quite heavy handed.

Doesn't work on pixel 2

See my issue here: https://stackoverflow.com/questions/58766092/geckoview-android-pixel-2-errors

When API Changelog is selected, the menu highlights API documentation too.

Choose Theme for site

We should choose a Jekyll theme for the site

http://jekyllthemes.org/
https://pages.github.com/themes/