# WebView quick start
*** promo
Googlers may wish to consult http://go/clank-webview for Google-specific
developer guides.
***
[TOC]
## Overview
This is not a thorough guide for how to build WebView, but is the **fastest**
way to get a local build of WebView up and running.
### Building for preview Android releases
Googlers should see internal instructions. External contributors should switch
to a public (and finalized) Android release (there's no workaround).
## System requirements, tools, etc.
See general Android instructions for:
* [System
requirements](/docs/android_build_instructions.md#System-requirements)
* [Installing
`depot_tools`](/docs/android_build_instructions.md#Install-depot_tools)
* [Getting the code](/docs/android_build_instructions.md#Get-the-code) **or**
[converting a Linux
checkout](/docs/android_build_instructions.md#Converting-an-existing-Linux-checkout)
* [Installing build
dependencies](/docs/android_build_instructions.md#Install-additional-build-dependencies)
**and** [running hooks](/docs/android_build_instructions.md#Run-the-hooks)
## Install adb
If you don't already have `adb` installed, the fastest way is to add chromium's
Android SDK to your `$PATH`. If you use multiple terminal, you'll want to run
this command in each terminal:
```shell
$ source build/android/envsetup.sh
```
## Device setup
The recommend configuration is to use an **Android 10 (Q) emulator**. Android R
or higher is also OK. If you need to use Android N-P instead then you can use
the [old version of this guide](./quick-start-legacy.md). If you need to use any
other configuration, then you need to switch to the full [build
guide](./build-instructions.md) instead.
Set up an [Android emulator](/docs/android_emulator.md). You have 2 options for
this:
1. Preconfigured emulator image. Just run this command in your terminal, which
will launch an emulator window when the emulator is ready. If anything goes
wrong, see [the
documentation](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/android_emulator.md#Using-Prebuilt-CIPD-packages)
or try the next option (see below).
```shell
$ tools/android/avd/avd.py start \
--avd-config tools/android/avd/proto/android_29_google_apis_x86.textpb --emulator-window
```
2. Android Studio Emulator image. [Install the Android Studio
IDE](https://developer.android.com/studio/install) and then follow [these
instructions](https://developer.android.com/studio/run/managing-avds)
to launch the Device Manager GUI. Create an emulator with these settings:
* Skin: any Pixel device skin is fine
* Release name: **10**
* ABI: **x86**
* Target: **Google APIs**
<!-- Keep this part in sync with /docs/android_emulator.md -->
* Select "Show Advanced Settings" > scroll down:
* Set internal storage to 4000MB
* Set SD card to 1000MB
* If in doubt, consult the
[chromium
documentation](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/android_emulator.md#Using-Your-Own-Emulator-Image)
to configure your emulator
Once configured, click the **play** button to launch the emulator.
**Verify your emulator is ready:** after performing either of the steps above,
you should check your emulator by running:
```shell
# If everything worked correctly, this should say "device" in the right column.
$ adb devices
List of devices attached
emulator-5554 device
```
## Setting up the build
Configure GN args (run `gn args out/Default`) as follows:
```gn
target_os = "android"
target_cpu = "x86"
# Recommended: this lets you use System WebView Shell as a test app.
system_webview_shell_package_name = "org.chromium.my_webview_shell"
```
## Build, install, and switch WebView provider {#build}
```shell
# Build
$ autoninja -C out/Default system_webview_apk
# Install the APK
$ out/Default/bin/system_webview_apk install
# Tell Android platform to load a WebView implementation from this APK
$ out/Default/bin/system_webview_apk set-webview-provider
```
**That's it!** Your APK should be installed and should be providing the WebView
implementation for all apps on the system.
## Things to do next
### Start running an app
**Skip this section** if you already have an app you want to test.
You can start testing our your WebView APK with the System WebView Shell test
app. This also shows the WebView version at the top of the app, so you can
verify this is using the version you built locally. You can run this test app
like so:
```shell
# Build
$ autoninja -C out/Default system_webview_shell_apk
# Install
$ out/Default/bin/system_webview_shell_apk install
# Launch a URL
$ out/Default/bin/system_webview_shell_apk launch "https://www.google.com/"
```
For more info about WebView Shell, see [the docs](./webview-shell.md).
### Toggle features or commandline flags
**Skip this section** if you don't need to toggle a specific commandline flag.
If you exposed your flag in [ProductionSupportedFlagList.java], then you can
toggle the flag in WebView DevTools. For more info about WebView DevTools, see
[the docs](./developer-ui.md). You can launch WebView DevTools with:
```shell
$ adb shell am start -a "com.android.webview.SHOW_DEV_UI"
```
If the flag is not exposed, you can instead try following [these
steps](./commandline-flags.md).
### Debug with adb logcat
We recommend starting with "printf-style debugging" on Android:
1. Add some logs in your code:
* In C++ code: add `LOG(ERROR) << "SOMETAG: <your log message goes here>";`
* In Java code: add `org.chromium.base.Log.e("SOMETAG", "<your log message
goes here>");`
2. Recompile and reinstall `system_webview_apk` (see
[steps above](#build)). Re-launch your test app.
3. Read your log messages by running this command:
`adb logcat | grep 'SOMETAG'`
For more guidance, refer to [the logging
documentation](/docs/android_logging.md).
### Run automated tests
We recommend starting with [integration
tests](./test-instructions.md#instrumentation-tests).
### Shutdown your emulator when you're done
The recommended way to turn off your emulator is to just close the emulator
window. If that doesn't work or you can't find the emulator window, then you can
safely shutdown your emulator by running `adb emu kill` in the terminal.
## Troubleshooting
If the install command succeeded but something else is wrong, the best way to
troubleshoot the problem is to query the state of the on-device
WebViewUpdateService:
```shell
$ adb shell dumpsys webviewupdate
Current WebView Update Service state
Fallback logic enabled: true
Current WebView package (name, version): (com.google.android.apps.chrome, 75.0.3741.0)
Minimum WebView version code: 303012512
Number of relros started: 1
Number of relros finished: 1
WebView package dirty: false
Any WebView package installed: true
Preferred WebView package (name, version): (com.google.android.apps.chrome, 75.0.3741.0)
WebView packages:
Valid package com.android.chrome (versionName: 58.0.3029.125, versionCode: 303012512, targetSdkVersion: 26) is installed/enabled for all users
Valid package com.google.android.webview (versionName: 58.0.3029.125, versionCode: 303012500, targetSdkVersion: 26) is NOT installed/enabled for all users
Invalid package com.chrome.beta (versionName: 74.0.3729.23, versionCode: 372902311, targetSdkVersion: 28), reason: No WebView-library manifest flag
Invalid package com.chrome.dev (versionName: 54.0.2840.98, versionCode: 284009811, targetSdkVersion: 24), reason: SDK version too low
Invalid package com.chrome.canary (versionName: 75.0.3741.0, versionCode: 374100010, targetSdkVersion: 25), reason: SDK version too low
Valid package com.google.android.apps.chrome (versionName: 75.0.3741.0, versionCode: 2, targetSdkVersion: 28) is installed/enabled for all users
```
### Invalid package ... No WebView-library manifest flag
This APK does not contain a WebView implementation. Make sure you're building
`system_webview_apk`.
### Invalid package ... Version code too low
This shouldn't happen for userdebug builds. If it does, add this GN arg:
```gn
# Any number >= "Minimum WebView version code":
android_override_version_code = "987654321"
```
### Invalid package ... SDK version too low
The targetSdkVersion of your APK is too low (it must be >= the platform's API
level). This shouldn't happen for local builds using tip-of-tree chromium on
public OS versions (see [note](#Building-for-preview-Android-releases)).
*** note
**Note:** we only support local development using the latest revision of the
main branch. Checking out release branches introduces a lot of complexity, and
it might not even be possible to build WebView for your device.
***
### Invalid package ... Incorrect signature
This shouldn't happen for userdebug devices, and there's no workaround for user
devices. Make sure you have a userdebug device (you can check with `adb shell
getprop ro.build.type`).
### Valid package ... **is** installed/enabled for all users
This is the correct state. If this is not the "preferred WebView package" or the
"current WebView package", call `set-webview-implementation` again.
### Valid package ... **is NOT** installed/enabled for all users
This shouldn't happen for `com.google.android.apps.chrome` (the recommended
package name). If you need to use a different package name, you may be able to
workaround this by enabling "redundant packages" (`adb shell cmd webviewupdate
enable-redundant-packages`), reinstalling, and running `set-webview-provider`
again.
Otherwise, please [reach out to the team][1].
### My package isn't in the list
Either your package didn't install (see below) or you chose a package name which
is [not eligible as a WebView provider](webview-providers.md#Package-name) for
this device. Double-check the package name in your GN args. If you're on AOSP
(any OS level), choose `"com.android.webview"`. If you're on L-M, choose
`"com.google.android.webview"`. In either case, you'll likely need to [remove
the preinstalled WebView
APK](/android_webview/tools/remove_preinstalled_webview.py).
### WebView shell doesn't show the correct version
Check the "Current WebView package" in the dumpsys output. You're probably
hitting one of the cases above.
### INSTALL\_FAILED\_UPDATE\_INCOMPATIBLE: Package ... signatures do not match previously installed version
Double check your emulator is Android 10 (Q) and that this is a **Google APIs**
image. Double check your GN args to make sure you are **not** setting the
`system_webview_package_name` argument (it's OK to set
`system_webview_shell_package_name`, but the other arg should be the default
value). If everything looks correct, try:
```shell
# Try uninstalling any WebView updates
$ adb uninstall com.android.webview
# If the uninstall command succeeded, then try installing your locally compiled
# WebView again:
$ out/Default/bin/system_webview_shell_apk install
$ out/Default/bin/system_webview_shell_apk set-webview-provider
```
### I couldn't install the APK/... is NOT installed.
This could fail for an even wider variety of reasons than already listed. Please
[reach out to the team][1].
### I couldn't **build** the APK
Try building Chromium. If that doesn't work, please reach out to [the chromium
team](https://groups.google.com/a/chromium.org/forum/#!forum/chromium-dev) for
general guidance. If `system_webview_apk` is the only troublesome target, please
reach out to the WebView team (see previous section).
### Apps using WebView crash with "java.lang.RuntimeException: Unable to start activity"
If apps using WebView crash with stack traces like the following:
```
AndroidRuntime: Shutting down VM
AndroidRuntime: FATAL EXCEPTION: main
AndroidRuntime: Process: org.chromium.webview_shell, PID: 6683
AndroidRuntime: java.lang.RuntimeException: Unable to start activity ComponentInfo{org.chromium.webview_shell/org.chromium.webview_shell.WebViewBrowserActivity}: android.util.AndroidRuntimeException: java.lang.reflect.InvocationTargetException
...
AndroidRuntime: Caused by: android.util.AndroidRuntimeException: java.lang.reflect.InvocationTargetException
...
AndroidRuntime: Caused by: org.chromium.base.library_loader.ProcessInitException: errorCode=2
...
AndroidRuntime: Caused by: java.lang.UnsatisfiedLinkError: dlopen failed: library "libc++_chrome.so" not found
...
```
This `UnsatisfiedLinkError` can occur when WebView is built using the
`target_cpu = "x86"` gn arg and the emulator architecture is x86_64. Double
check your emulator is Android 10 (Q) and uses the x86 ABI.
## What if I didn't follow these instructions exactly?
**Proceed at your own risk.** Building and installing WebView is, for a variety
of reasons, complex. If you've deviated from **any** of these instructions (and
don't know what you're doing) there's a good chance of making mistakes (some of
which don't have any error messages).
If you can't follow the quick start guide for some reason, please consult our
[general build instructions](build-instructions.md). You can also try the [old
version of the quick start](./quick-start-legacy.md).
[1]: https://groups.google.com/a/chromium.org/forum/#!forum/android-webview-dev
[ProductionSupportedFlagList.java]: https://source.chromium.org/chromium/chromium/src/+/main:android_webview/java/src/org/chromium/android_webview/common/ProductionSupportedFlagList.java
Codebase Browser
chromium