Skip to content

Latest commit

 

History

History
210 lines (153 loc) · 8.07 KB

quick-start.md

File metadata and controls

210 lines (153 loc) · 8.07 KB

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:

Device setup

Easiest configuration is to choose a Google APIs emulator running Android N or higher. See Device Setup 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:

# 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

$ autoninja -C out/Default system_webview_apk

Install WebView and switch provider

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

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

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

*** 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.

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

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.

I couldn't build the APK

Try building Chromium. If that doesn't work, please reach out to the chromium team 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.