chromium/src
0
Fork 0
Code Activity

AW docs: make dev UI doc more general

Browse Source 
This renames "flag-ui.md" to "developer-ui.md." This reorders the doc to
put flag UI content in its own section, and adds an empty section for
the crash UI.

This adds the user guide to the navbar.

Bug: 1058571
Test: tools/md_browser/md_browser.py
Test: Upload to gerrit > open file > click "gitiles"
Change-Id: I8ec1ba45e0e9461164298df13d6cb21df087c99e
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2142376
Reviewed-by: Richard Coles <torne@chromium.org>
Commit-Queue: Nate Fischer <ntfschr@chromium.org>
Cr-Commit-Position: refs/heads/master@{#757587}
This commit is contained in:
Nate Fischer
2020-04-08 21:27:14 +00:00
committed by Commit Bot
parent a3fbe4bdcf
commit 05d0dcbc82
3 changed files with 122 additions and 118 deletions

120
android_webview/docs/developer-ui.md Normal file

@ -0,0 +1,120 @@
# WebView DevTools user guide
[TOC]
## Launching WebView DevTools
WebView DevTools is an on-device suite of tools that ships with WebView itself.
You can launch WebView DevTools by any of the following:
### Launcher icon on pre-stable channels (preferred)
The best way to launch WebView DevTools is to [download WebView Beta, Dev, or
Canary](prerelease.md). These channels will have a launcher icon which will
launch WebView DevTools.
*** note
**Note:** the WebView DevTools icon does not appear by default on Android 7
through 9 (Nougat/Oreo/Pie). To enable the launcher icon, first [change your
WebView provider](prerelease.md#Android-7-through-9-Nougat_Oreo_Pie) and then
launch the same Chrome channel or any WebView app (ex. [WebView shell
browser](webview-shell.md), or open an email in Gmail).
***
### Launch via adb
If you have adb installed, you can connect your Android device to launch
DevTools:
```sh
adb shell am start -a "com.android.webview.SHOW_DEV_UI"
```
### Launch via WebView Shell
Newer versions of [WebView shell](webview-shell.md) have a menu option to launch
WebView DevTools. If your copy of WebView shell doesn't have this option, you
may need to rebuild it yourself.
## Crash UI
TODO(http://crbug.com/1058571): document this.
## Flag UI
While WebView supports [toggling arbitrary flags](commandline-flags.md) on
debuggable devices, we also support toggling a curated set of experimental
flags/features on production Android devices. We expose these features as part
of WebView's on-device DevTools. This is similar to Chrome's `chrome://flags`
tool.
![WebView flag UI](images/webview_flag_ui.png)
Tap the "Flags" option in the bottom navgation bar. You can scroll through the
list to find your desired feature/flag (ex. "highlight-all-webviews"), tap the
dropdown (look for "Default"), and tap "Enabled" in the dialog popup. You can
enable (or disable) as many flags as you need.
*** promo
**Tip:** enabling "highlight-all-webviews" (which tints all WebView objects
yellow) in addition to your desired flag is a great way to verify apps have
picked up WebView flags.
***
Kill and restart WebView apps so they pick up the new flags.
When you're done, open the notification tray and tap the WebView DevTools
notification to go back to the flag UI. Tap "Reset all to default" and kill and
restart WebView apps to go back to the default behavior.
### Overriding variations/Field Trials
Like Chrome, WebView supports A/B experiments and feature rollouts through
variations (AKA "field trials" or "Finch"). The flag UI can override the field
trial config, either to **enable** an experimental feature to ensure your app
works correctly, or to **disable** an experiment to determine if this is the
root cause for a WebView behavior change breaking your app. Simply tap "Enabled"
or "Disabled" in the UI; "Default" means WebView will pick up the random field
trial experiment.
If you find an experiment is the root cause for app breakage, please [file a
bug](https://bugs.chromium.org/p/chromium/issues/entry?template=Webview+Bugs),
mention which experiment, and link to your app's Play Store page for our team to
investigate.
### Accelerating field trial config download
You can also use the flag UI to download new field trial configs ("seeds") more
quickly, to verify the next seed will fix app breakage. Enable all of the
following:
* `finch-seed-expiration-age=0`
* `finch-seed-min-update-period=0`
* `finch-seed-min-download-period=0`
* `finch-seed-ignore-pending-download`
Restart your app, kill it, and restart it a second time. Your app should be
running with the latest WebView variations seed.
### Adding your flags and features to the UI
If you're intending to launch a feature in WebView or start a field trial (AKA
Finch experiment), we **highly encourage** you to [add to the
list](/android_webview/java/src/org/chromium/android_webview/common/ProductionSupportedFlagList.java)
(ex. [CL](https://crrev.com/c/2008007), [CL](https://crrev.com/c/2066144)).
Exposing your feature this way has several benefits:
- This improves the manual test process. Testers can enable your feature with a
button click instead of an adb command.
- Typo-free: someone could mistype a flag or feature name in the commandline,
but this UI ensures flag names are always spelled correctly.
- Because this works on production Android devices, test team can validate your
feature on devices from other OEMs.
- You (and teammates) can dogfood your feature.
- If users or third-party app developers report bugs, this UI is the only way
they can toggle your feature to help root-cause the regression.
### See also
- [Design doc](http://go/webview-dev-ui-flags-design) (Google-only)

119
android_webview/docs/flag-ui.md

@ -1,118 +1 @@
# Flag UI
[TOC]
While WebView supports [toggling arbitrary flags](commandline-flags.md) on
debuggable devices, we also support toggling a curated set of experimental
flags/features on production Android devices. We expose these features as part
of WebView's on-device DevTools. This is similar to Chrome's `chrome://flags`
tool.
![WebView flag UI](images/webview_flag_ui.png)
## Launching WebView DevTools
The flag UI is part of "WebView DevTools," an on-device tool that ships with
device's WebView implementation. You can launch WebView DevTools by any of the
following:
### Launcher icon on pre-stable channels (preferred)
The best way to launch WebView DevTools is to [download WebView Dev or WebView
Canary](prerelease.md). These channels will have a launcher icon which will
launch WebView DevTools.
*** note
**Note:** the WebView DevTools icon does not appear by default on Android 7
through 9 (Nougat/Oreo/Pie). To enable the launcher icon, first [change your
WebView provider](prerelease.md#Android-7-through-9-Nougat_Oreo_Pie) and then
launch the same Chrome channel or any WebView app (ex. [WebView shell
browser](webview-shell.md), or open an email in Gmail).
***
### Launch via adb
If you have adb installed, you can connect your Android device to launch
DevTools:
```sh
adb shell am start -a "com.android.webview.SHOW_DEV_UI"
```
### Launch via WebView Shell
Newer versions of [WebView shell](webview-shell.md) have a menu option to launch
WebView DevTools. If your copy of WebView shell doesn't have this option, you
may need to rebuild it yourself.
## Using the flag UI
Once you've launched WebView DevTools, tap the "Flags" option in the bottom
navgation bar. You can scroll through the list to find your desired feature/flag
(ex. "highlight-all-webviews"), tap the dropdown (look for "Default"), and tap
"Enabled" in the dialog popup. You can enable (or disable) as many flags as you
need.
*** promo
**Tip:** enabling "highlight-all-webviews" (which tints all WebView objects
yellow) in addition to your desired flag is a great way to verify apps have
picked up WebView flags.
***
Kill and restart WebView apps so they pick up the new flags.
When you're done, open the notification tray and tap the WebView DevTools
notification to go back to the flag UI. Tap "Reset all to default" and kill and
restart WebView apps to go back to the default behavior.
### Overriding variations/Field Trials
Like Chrome, WebView supports A/B experiments and feature rollouts through
variations (AKA "field trials" or "Finch"). The flag UI can override the field
trial config, either to **enable** an experimental feature to ensure your app
works correctly, or to **disable** an experiment to determine if this is the
root cause for a WebView behavior change breaking your app. Simply tap "Enabled"
or "Disabled" in the UI; "Default" means WebView will pick up the random field
trial experiment.
If you find an experiment is the root cause for app breakage, please [file a
bug](https://bugs.chromium.org/p/chromium/issues/entry?template=Webview+Bugs),
mention which experiment, and link to your app's Play Store page for our team to
investigate.
### Accelerating field trial config download
You can also use the flag UI to download new field trial configs ("seeds") more
quickly, to verify the next seed will fix app breakage. Enable all of the
following:
* `finch-seed-expiration-age=0`
* `finch-seed-min-update-period=0`
* `finch-seed-min-download-period=0`
* `finch-seed-ignore-pending-download`
Restart your app, kill it, and restart it a second time. Your app should be
running with the latest WebView variations seed.
## Adding your flags and features to the UI
If you're intending to launch a feature in WebView or start a field trial (AKA
Finch experiment), we **highly encourage** you to [add to the
list](/android_webview/java/src/org/chromium/android_webview/common/ProductionSupportedFlagList.java)
(ex. [CL](https://crrev.com/c/2008007), [CL](https://crrev.com/c/2066144)).
Exposing your feature this way has several benefits:
- This improves the manual test process. Testers can enable your feature with a
button click instead of an adb command.
- Typo-free: someone could mistype a flag or feature name in the commandline,
but this UI ensures flag names are always spelled correctly.
- Because this works on production Android devices, test team can validate your
feature on devices from other OEMs.
- You (and teammates) can dogfood your feature.
- If users or third-party app developers report bugs, this UI is the only way
they can toggle your feature to help root-cause the regression.
## See also
- [Design doc](http://go/webview-dev-ui-flags-design) (Google-only)
This content has moved to [developer-ui.md](developer-ui.md).

1
android_webview/docs/navbar.md

@ -9,6 +9,7 @@
* [WebView Shell](/android_webview/docs/webview-shell.md)
* [Commandline flags](/android_webview/docs/commandline-flags.md)
* [Net debugging](/android_webview/docs/net-debugging.md)
* [WebView DevTools](/android_webview/docs/developer-ui.md)
* [FAQ (for users)](/android_webview/docs/faq.md)
* [AOSP system integration](/android_webview/docs/aosp-system-integration.md)
* [Threading](/android_webview/docs/threading.md)