1.. -*- Mode: rst; fill-column: 80; -*-
2
3Getting Started with GeckoView
4######################################
5
6How to use GeckoView in your Android app.
7
8*Building a browser? Check out* `Android Components <https://mozilla-mobile.github.io/android-components/>`_, *our collection of ready-to-use support libraries!*
9
10The 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
14Configure Gradle
15=================
16
17You 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 = "nightly"
27        geckoviewVersion = "70.0.20190712095934"
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 8 required support**
43
44As GeckoView uses some Java 8 APIs, it requires these compatibility flags:
45
46.. code-block:: groovy
47
48    compileOptions {
49        sourceCompatibility JavaVersion.VERSION_1_8
50        targetCompatibility JavaVersion.VERSION_1_8
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
62Add GeckoView to a Layout
63==========================
64
65Inside 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
75Initialize 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**2. In that activity's** ``onCreate`` **function, add the following:**
87
88.. code-block:: java
89
90    GeckoView view = findViewById(R.id.geckoview);
91    GeckoSession session = new GeckoSession();
92    GeckoRuntime runtime = GeckoRuntime.create(this);
93
94    session.open(runtime);
95    view.setSession(session);
96    session.loadUri("about:buildconfig"); // Or any other URL...
97
98You're done!
99==============
100
101Your application should now load and display a webpage inside of GeckoView.
102
103To 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>`_.
104