android_webview/docs/quick-start.md

# 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)

## Device setup

Easiest configuration is to choose a **Google APIs** emulator running **Android
N or higher**. See [Device Setup](./device-setup.md) for instructions.

*** promo
**Android O or higher** comes with troubleshooting tools, so that's highly
recommended.
***

## Setting up the build

Assuming you took the advice from above, configure GN args (run `gn args
out/Default`) as follows:

```gn
# Minimal
target_os = "android"
target_cpu = "x86"  # Assuming you chose an x86 emulator

# This package name is allowed for debuggable (userdebug) devices, and lets
# devs install a WebView provider without the usual signature checks. This only
# works on N+.
system_webview_package_name = "com.google.android.apps.chrome"
```

## Build WebView

```shell
$ autoninja -C out/Default system_webview_apk
```

## Install WebView and switch provider

```shell
# 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
```

## Start running an app

**That it!** Your APK should be installed and should be providing the WebView
implementation for all apps on the system. If you want to verify this, look at
the steps for [building the System WebView Shell](./webview-shell.md). The
version number in the shell's top bar should match the version number in your
local copy of `//chrome/VERSION`.

## 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
# If you don't have `adb` in your path, you can source this file to use
# the copy from chromium's Android SDK
$ source build/android/envsetup.sh

# Only available on O+
$ 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

This is probably because you've already installed Chrome Debug (ex. with the
Google-only `monochrome_apk` target, or through a Google-only official build).
This guide borrows that app's package name, but the locally compiled APK may not
have the same signing key, causing the `adb install` error. You should remove
the conflicting package with `out/Default/bin/system_webview_apk uninstall`, and
then try installing WebView again.

### 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).

## 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).

[1]: https://groups.google.com/a/chromium.org/forum/#!forum/android-webview-dev