doc(android): document AndroidInsecureFileModeEnabled

www/docs/en/dev/config_ref/index.md

@@ -292,6 +292,7 @@ Attributes(type) <br/> <span class="sub-header">Only for platform:</span> | Desc
 AllowInlineMediaPlayback(boolean) <br/> ==iOS== | *Default: false* <br/>  Set to true to allow HTML5 media playback to appear inline within the screen layout, using browser-supplied controls rather than native controls. For this to work, add the ```playsinline``` attribute to any ```<video>``` elements. *NOTE*: Prior to iOS 10, ```<video>``` elements need to use the ```webkit-playsinline``` attribute name instead.
 AllowNewWindows(boolean) <br/> ==iOS== | *Default: false* <br/> Set to true to allow JavaScript `window.open` and HTML `target="\_blank"` links to open a new view overlaying the web view.
 AndroidLaunchMode(string) <br/> ==Android== | *Default: singleTop* <br/> Allowed values: standard, singleTop, singleTask, singleInstance <br/>  Sets the Activity android:launchMode attribute. This changes what happens when the app is launched from app icon or intent and is already running.
+AndroidInsecureFileModeEnabled(boolean) <br/> ==Android== | *Default: false* <br/>  If set to `true` loading `file:///` URLs is allowed. __Note__: Enabling this setting allows malicious scripts loaded in a file:// context to launch cross-site scripting attacks, either accessing arbitrary local files including WebView cookies, app private data or even credentials used on arbitrary web sites.
 android-maxSdkVersion(integer) <br/> ==Android== | *Default: Not Specified* <br/>  Sets the `maxSdkVersion` attribute of the `<uses-sdk>` tag in the project's `AndroidManifest.xml` (see [here][uses-sdk]).
 android-minSdkVersion(integer) <br/> ==Android== | *Default: Dependent on cordova-android Version* <br/>  Sets the `minSdkVersion` attribute of the `<uses-sdk>` tag in the project's `AndroidManifest.xml` (see [here][uses-sdk]).
 android-targetSdkVersion(integer) <br/> ==Android== | *Default: Dependent on cordova-android Version* <br/>  Sets the `targetSdkVersion` attribute of the `<uses-sdk>` tag in the project's `AndroidManifest.xml` (see [here][uses-sdk]).
@@ -394,6 +395,7 @@ Examples:
 <preference name="ShowTitle" value="true"/>
 <preference name="LogLevel" value="VERBOSE"/>
 <preference name="AndroidLaunchMode" value="singleTop"/>
+<preference name="AndroidInsecureFileModeEnabled" value="true" />
 <preference name="DefaultVolumeStream" value="call" />
 <preference name="OverrideUserAgent" value="Mozilla/5.0 My Browser" />
 <preference name="AppendUserAgent" value="My Browser" />

www/docs/en/dev/guide/platforms/android/upgrade.md

@@ -27,6 +27,30 @@ Most of these instructions apply to projects created with an older set
 of command-line tools that precede the `cordova` CLI utility. See [The Command-Line Interface](../../cli/index.html) for information how to update the
 version of the CLI.
 
+## Upgrading to 10.x.x
+
+The best way to upgrade to 10.X.X is to simply remove the Android platform from
+your project and re-add it with the new version. For example,
+
+```bash
+cordova platform remove android
+cordova platform add android@10.X.X
+```
+
+If you use the above method, be aware that any changes you made to the android
+platform folder will be lost (editing the contents of this folder is
+discouraged).
+
+### Breaking changes
+
+Version 10.0.0 introduces a signinificant change how URLs are loaded within the app.
+Prior versions load the apps web files like `index.html` via the file protocol.
+Which means the app starts with the URL `file:///android_asset/www/index.html`. Loading `file:///` URLs is considered insecure
+and [Android has deprecated support](https://developer.android.com/reference/android/webkit/WebSettings#setAllowUniversalAccessFromFileURLs(boolean)).
+Cordova Android 10.0.0 now uses an Android API called `WebViewAssetLoader` to load web content via the HTTP(S) scheme (`https://localhost`) by default.
+Therefore the app now starts with the URL `https://localhost/` instead of `file:///android_asset/www/index.html`. Because this is a new origin you might encouter data loss and you need to migrate your web data (Localstorage, IndexedDB etc).
+
+You can use the `config.xml` preference `<preference name="AndroidInsecureFileModeEnabled" value="true" />` to opt-out of the new WebViewAssetLoader and switch back to file URLs.
 
 ## Upgrading to 7.X.X