Note: this guide only applies to userdebug/eng devices and emulators. Most users and app developers do not have debuggable devices, and therefore cannot follow this guide.
If you need to toggle flags on production Android devices, you can use WebView DevTools.
You can check which Android image you have on your device with the following:
# 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 # If this outputs "userdebug" or "eng" then you can apply flags following this # guide. If it outputs "user" then you can only use WebView DevTools. $ adb shell getprop ro.build.type userdebug
If the above outputs “user,” then you have two options:
WebView (and Chromium in general) has two different types of “commandline flags:”
--name-of-switch.NameOfFeature.Before applying commandline flags, you should understand which specific flags you want to flip and whether each is a Commandline Switch or Feature Flag. Then follow the steps below.
WebView reads flags from a specific file on the device as part of the startup sequence. Therefore, it‘s important to always kill and restart the WebView-based app you’re examining after modifying commandline flags to ensure the flags are picked up.
WebView always looks for the same file on the device (/data/local/tmp/webview-command-line), regardless of which package is the the WebView provider.
The simplest way to set WebView flags is with the dedicated python script. This works regardless of which package is the WebView provider. Note: this script will overwrite any Commandline Switches or Feature Flags which had previously been applied.
# Overwrite flags (supports multiple) build/android/adb_system_webview_command_line --highlight-all-webviews --force-enable-metrics-reporting # Clear flags build/android/adb_system_webview_command_line "" # Print flags build/android/adb_system_webview_command_line
If you have a locally compiled APK, you may instead set flags using the Generated Wrapper Script like so:
autoninja -C out/Default system_webview_apk # Overwrite flags (supports multiple) out/Default/bin/system_webview_apk argv --args='--highlight-all-webviews --force-enable-metrics-reporting' # Clear flags out/Default/bin/system_webview_apk argv --args='' # Print flags out/Default/bin/system_webview_apk argv
system_webview_* and trichrome_webview_* targets. Be careful when using a monochrome_* target, as this will write to Chrome browser's flags file, and WebView will not pick up these flags. If using Monochrome, you should instead use the python script mentioned above.Or, you can use the adb in your $PATH like so:
FLAG_FILE=/data/local/tmp/webview-command-line # Overwrite flags (supports multiple). The first token is ignored. We use '_' # as a convenient placeholder, but any token is acceptable. adb shell "echo '_ --highlight-all-webviews --force-enable-metrics-reporting' > ${FLAG_FILE}" # Clear flags adb shell "rm ${FLAG_FILE}" # Print flags adb shell "cat ${FLAG_FILE}"
You can add the --webview-verbose-logging flag, which tells WebView to dump its full commandline and variations state to logs during startup. You can filter device logs with:
adb logcat | grep -iE 'Active field trial|WebViewCommandLine'
Feature Flags (also stylized as base::Feature or BASE_FEATURE) are Chromium‘s mechanism for toggling off-by-default code paths. While debugging flags are also off-by-default, Feature Flags typically guard soon-to-launch product enhancements until they’re tested enough for field trials or public launch, at which point the Feature Flag is removed and the legacy code path is no longer supported and removed from the codebase. On the other hand, debugging flags don‘t “launch,” as they’re typically only helpful for debugging issues.
WebView supports the same syntax for toggling Feature Flags as the rest of chromium: --enable-features=feature1,feature2 and --disable-features=feature3,feature4. You can apply --enable-features and --disable-features like any other flags, per the steps above. Please consult base/feature_list.h for details. Examples of toggling Feature Flags:
# Enable a single Feature Flag: build/android/adb_system_webview_command_line --enable-features=WebViewTestFeature # Enable multiple Feature Flags: build/android/adb_system_webview_command_line --enable-features=WebViewTestFeature,WebViewBrotliSupport # Enable and disable Feature Flags: build/android/adb_system_webview_command_line --enable-features=WebViewTestFeature --disable-features=WebViewBrotliSupport # Use Commandline Switches and Feature Flags at the same time: build/android/adb_system_webview_command_line --highlight-all-webviews --enable-features=WebViewTestFeature
As with Commandline Switches, we support multiple tools for toggling Feature Flags (Python script, Generated Wrapper Script, manual).
As before, it‘s important to kill and restart the WebView-based app you’re examining after modifying flags to ensure the flags are picked up.
WebView supports toggling any Commandline Switches or Feature Flags supported in any layer we depend on (//base, //content, etc.). For more details on Chromium's layer architecture, see this diagram (replace “chrome” with “android_webview”). Although we support toggling these flags, not all flags will have an effect when toggled, nor do we guarantee WebView functions correctly when the flag is toggled.
Some interesting Commandline Switches:
--highlight-all-webviews: highlight the entire contents of all WebViews, to quickly identify which app content is rendered by a WebView vs. native Views.--show-composited-layer-borders: highlight rendering layers, to identify possible graphics issues.--force-enable-metrics-reporting: enable UMA metrics reporting (does not override app opt-out)--finch-seed-expiration-age=0 --finch-seed-min-update-period=0 --finch-seed-min-download-period=0 --finch-seed-ignore-pending-download: always request a new finch seed when an app startsWebView also defines its own Commandline Switches and Feature Flags:
aw_switches.cc. We use java_cpp_strings to automatically generate Java switch constants from the C++ switches (see AwSwitches.java).aw_features.cc. We use java_cpp_features to automatically generate Java constants from the C++ Feature Flags (see AwFeatures.java).See CommandLineUtil.java.