tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

geckoview-quick-start.rst (3949B)

      1 .. -*- Mode: rst; fill-column: 80; -*-
      2 
      3 Getting Started with GeckoView
      4 ######################################
      5 
      6 How to use GeckoView in your Android app.
      7 
      8 *Building a browser? Check out* `Android Components <https://mozilla-mobile.github.io/firefox-android/>`_, *our collection of ready-to-use support libraries!*
      9 
     10 The following article is a brief guide to embedding GeckoView in an app. For a more in depth tutorial on getting started with GeckoView please read the article we have published on `raywenderlich.com <https://www.raywenderlich.com/1381698-android-tutorial-for-geckoview-getting-started>`_.
     11 
     12 .. contents:: :local:
     13 
     14 Configure Gradle
     15 =================
     16 
     17 You need to add or edit four stanzas inside your module's ``build.gradle`` file.
     18 
     19 **1. Set the GeckoView version**
     20 
     21 *Like Firefox, GeckoView has three release channels: Stable, Beta, and Nightly. Browse the* `Maven Repository <https://maven.mozilla.org/?prefix=maven2/org/mozilla/geckoview/>`_ *to see currently available builds.*
     22 
     23 .. code-block:: groovy
     24 
     25    ext {
     26        geckoviewChannel = <channel>
     27        geckoviewVersion = <version>
     28    }
     29 
     30 
     31 **2. Add Mozilla's Maven repository**
     32 
     33 .. code-block:: groovy
     34 
     35    repositories {
     36        maven {
     37            url "https://maven.mozilla.org/maven2/"
     38        }
     39    }
     40 
     41 
     42 **3. Java 17 required support**
     43 
     44 As GeckoView uses some Java 17 APIs, it requires these compatibility flags:
     45 
     46 .. code-block:: groovy
     47 
     48    compileOptions {
     49        sourceCompatibility JavaVersion.VERSION_17
     50        targetCompatibility JavaVersion.VERSION_17
     51    }
     52 
     53 **4. Add GeckoView Implementations**
     54 
     55 .. code-block:: groovy
     56 
     57    dependencies {
     58        // ...
     59      implementation "org.mozilla.geckoview:geckoview-${geckoviewChannel}:${geckoviewVersion}"
     60    }
     61 
     62 Add GeckoView to a Layout
     63 ==========================
     64 
     65 Inside a layout ``.xml`` file, add the following:
     66 
     67 .. code-block:: xml
     68 
     69    <org.mozilla.geckoview.GeckoView
     70        xmlns:android="http://schemas.android.com/apk/res/android"
     71        android:id="@+id/geckoview"
     72        android:layout_width="fill_parent"
     73        android:layout_height="fill_parent" />
     74 
     75 Initialize GeckoView in an Activity
     76 ====================================
     77 
     78 **1. Import the GeckoView classes inside an Activity:**
     79 
     80 .. code-block:: java
     81 
     82    import org.mozilla.geckoview.GeckoRuntime;
     83    import org.mozilla.geckoview.GeckoSession;
     84    import org.mozilla.geckoview.GeckoView;
     85 
     86 
     87 **2. Create a ``static`` member variable to store the ``GeckoRuntime`` instance.**
     88 
     89 .. code-block:: java
     90 
     91    private static GeckoRuntime sRuntime;
     92 
     93 **3. In that activity's** ``onCreate`` **function, add the following:**
     94 
     95 .. code-block:: java
     96 
     97    GeckoView view = findViewById(R.id.geckoview);
     98    GeckoSession session = new GeckoSession();
     99 
    100    // Workaround for Bug 1758212
    101    session.setContentDelegate(new GeckoSession.ContentDelegate() {});
    102 
    103    if (sRuntime == null) {
    104      // GeckoRuntime can only be initialized once per process
    105      sRuntime = GeckoRuntime.create(this);
    106    }
    107 
    108    session.open(sRuntime);
    109    view.setSession(session);
    110    session.loadUri("about:buildconfig"); // Or any other URL...
    111 
    112 **4. Set the** `windowSoftInputMode <https://developer.android.com/guide/topics/manifest/activity-element#wsoft>`_ **to** ``adjustResize`` **for** `interactive-widget <https://drafts.csswg.org/css-viewport/#interactive-widget-section>`_ **:**
    113 
    114 .. code-block:: xml
    115 
    116    <manifest xmlns:android="http://schemas.android.com/apk/res/android">
    117        <activity android:name=".YourActivity"
    118                  android:windowSoftInputMode="stateUnspecified|adjustResize" />
    119    </manifest>
    120 
    121 You're done!
    122 ==============
    123 
    124 Your application should now load and display a webpage inside of GeckoView.
    125 
    126 To learn more about GeckoView's capabilities, review GeckoView's `JavaDoc <https://mozilla.github.io/geckoview/javadoc/mozilla-central/>`_ or the `reference application <https://searchfox.org/mozilla-central/source/mobile/android/geckoview_example>`_.