This is an automated email from the ASF dual-hosted git repository.
github-bot pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/cordova-docs.git
The following commit(s) were added to refs/heads/asf-site by this push:
new 783c76653 Deploying to asf-site from @
apache/cordova-docs@d510793550601b6c5e927663a9081cfea3cdbb66 🚀
783c76653 is described below
commit 783c76653302230849ee12bb73a642fcde467b84
Author: erisu <er...@users.noreply.github.com>
AuthorDate: Wed Jul 13 04:59:15 2022 +0000
Deploying to asf-site from @
apache/cordova-docs@d510793550601b6c5e927663a9081cfea3cdbb66 🚀
---
docs/en/11.x/guide/platforms/android/index.html | 638 ++++++++++--------------
docs/en/dev/guide/platforms/android/index.html | 638 ++++++++++--------------
feed.xml | 4 +-
3 files changed, 538 insertions(+), 742 deletions(-)
diff --git a/docs/en/11.x/guide/platforms/android/index.html
b/docs/en/11.x/guide/platforms/android/index.html
index 83c16b777..4c1fc1f47 100644
--- a/docs/en/11.x/guide/platforms/android/index.html
+++ b/docs/en/11.x/guide/platforms/android/index.html
@@ -2270,23 +2270,13 @@
<div id="page-toc-source">
<h1>Android Platform Guide</h1>
-<p>This guide shows how to set up your SDK environment to deploy Cordova
-apps for Android devices, and how to optionally use Android-centered
-command-line tools in your development workflow. You need to install
-the Android SDK regardless of whether you want to use these
-platform-centered shell tools or cross-platform Cordova CLI for
-development. For a comparison of the two development paths, see the
-<a href="../../overview/index.html#development-paths">Overview</a>. For
details on
-the CLI, see <a href="../../../reference/cordova-cli/index.html">Cordova CLI
Reference</a>.</p>
-
-<h2>Requirements and Support</h2>
-
-<p>Cordova for Android requires the Android SDK which can be installed
-on OS X, Linux or Windows. See the Android SDK's
-<a href="http://developer.android.com/sdk/index.html#Requirements";>System
Requirements</a>.
-Cordova's latest Android package supports up to Android <a
href="https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels";>API
Level</a> 30.
-The supported Android API Levels and Android Versions for the past
-few cordova-android releases can be found in this table:</p>
+<p>This guide will help set up your development environment for building
Cordova apps for Android devices and optionally use Android-specific
command-line tools within your development workflow.</p>
+
+<p>You will need to install and set up the requirements regardless of whether
you want to use the Android-specific command-line tools or Cordova CLI
commands.</p>
+
+<h2>Android API Level Support</h2>
+
+<p>The supported <a
href="https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels";>Android
API Levels</a> (versions of Android) corresponding with the Cordova-Android
released versions are listed in the table below:</p>
<table>
<thead>
@@ -2297,6 +2287,11 @@ few cordova-android releases can be found in this
table:</p>
</tr>
</thead>
<tbody>
+ <tr>
+ <td>11.X.X</td>
+ <td>22 - 32</td>
+ <td>5.1 - 12.0.0 (L)</td>
+ </tr>
<tr>
<td>10.X.X</td>
<td>22 - 30</td>
@@ -2345,93 +2340,103 @@ few cordova-android releases can be found in this
table:</p>
</tbody>
</table>
-<p>Please note that the versions listed here are for Cordova's Android
package,
-<a href="https://github.com/apache/cordova-android";>cordova-android</a>, and
not for the
-Cordova CLI. To determine what version of Cordova's Android package is
installed
-in your Cordova project, run the command <code>cordova platform ls</code> in
the directory
-that holds your project.</p>
+<p><em><strong>Note:</strong> The <a
href="https://github.com/apache/cordova-android";>cordova-android</a> versions
listed above are not for the Cordova CLI.</em></p>
+
+<p>To determine what version of the Cordova-Android package is installed in
your Cordova project, run the command <code>cordova platform ls</code> in your
project's root directory.</p>
+
+<p>As a general rule, Android versions become unsupported by Cordova as they
dip below 5% on Google's <a
href="https://developer.android.com/about/dashboards/index.html";>distribution
dashboard</a>.</p>
+
+<h2>System Requirements</h2>
+
+<p>Cordova-Android requires the Android SDK, which can be installed on either
macOS, Linux, or Windows.</p>
-<p>As a general rule, Android versions become unsupported by Cordova as
-they dip below 5% on Google's
-<a
href="http://developer.android.com/about/dashboards/index.html";>distribution
dashboard</a>.</p>
+<p>For the base system requirements, see the Android Studio's <a
href="https://developer.android.com/studio#Requirements";>System
Requirements</a>.</p>
-<h2>Installing the Requirements</h2>
+<h2>The Required Software & Tools</h2>
<h3>Java Development Kit (JDK)</h3>
-<p>Install <a
href="https://www.oracle.com/java/technologies/javase/javase-jdk8-downloads.html";>Java
Development Kit (JDK) 8</a>
-or you can install <a
href="https://www.oracle.com/java/technologies/javase-jdk11-downloads.html";>Java
Development Kit (JDK) 11</a>
-if using <code>cordova-android</code> version 10+.</p>
+<p>If you are using <code>cordova-android</code> 10.0.0 or greater, install
the <a
href="https://www.oracle.com/java/technologies/javase-jdk11-downloads.html";>Java
Development Kit (JDK) 11</a>.</p>
-<p>When installing on Windows you also need to set <code>JAVA_HOME</code>
Environment Variable
-according to your JDK installation path (see <a
href="#setting-environment-variables">Setting Environment Variables</a>)</p>
+<p>If you are using any version below <code>cordova-android</code> 10.0.0,
install the <a
href="https://www.oracle.com/java/technologies/javase/javase-jdk8-downloads.html";>Java
Development Kit (JDK) 8</a>.</p>
+
+<p>The <code>JAVA_HOME</code> environment variable must be set according to
your JDK installation path when installing on a Windows environment. See the <a
href="#setting-environment-variables">Setting Environment Variables</a> section
on how to set up environment variables.</p>
<h3>Gradle</h3>
-<p>As of Cordova-Android 6.4.0, <a
href="https://gradle.org/install/";>Gradle</a> is now required to be installed
to build Android.</p>
+<p>As of Cordova-Android 6.4.0, <a
href="https://gradle.org/install/";>Gradle</a> is required to be installed.</p>
+
+<p>When installing on Windows, you need to add the path to the Gradle's
binary directory to your <code>path</code> environment variable. See <a
href="#setting-environment-variables">Setting Environment Variables</a>) on how
to configure system environment variables.</p>
-<p>When installing on Windows, you need to add Gradle to your path, (see <a
href="#setting-environment-variables">Setting Environment Variables</a>)</p>
+<p><em><strong>Note:</strong> This is the system's Gradle version. The
system's Gradle binary will create the Gradle Wrapper file that declares
and obtains the appropriate version of Gradle needed for building the Android
application. The system-level and project-level version of Gradle may not and
does not need to match. The project-level's version of Gradle is defined in
the Cordova-Android's package and set based on what Android
supports.</em></p>
-<h3>Android SDK</h3>
+<h3>Android Studio</h3>
-<p>Install <a href="https://developer.android.com/studio/index.html";>Android
Studio</a>. Follow the instructions at the linked Android Developer site to get
started.
-Opening Android Studio for the first time will guide you through the process
of installing the Android SDK.</p>
+<p>Download and install <a
href="https://developer.android.com/studio/index.html";>Android Studio</a>.
Follow the instructions at the linked Android Developer site to get started.</p>
+
+<p>Opening Android Studio for the first time will guide you through the
process of installing the Android SDK packages.</p>
<h4>Adding SDK Packages</h4>
-<p>After installing the Android SDK, you must also install the packages for
-whatever <a
href="http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels";>API
level</a>
-you wish to target. It is recommended that you install the highest SDK version
-that your version of cordova-android supports (see <a
href="#requirements-and-support">Requirements and Support</a>).</p>
+<p>It is recommended to install the highest supported version of the SDK
Platform and Build Tools based on the project's installed version of
Cordova-Android. Please see the <a href="#android-api-level-support">Android
API Level Support</a> to find the supported version based on the
Cordova-Android versions.</p>
-<p>Open the Android SDK Manager (<code>Tools > SDK Manager</code> in
Android Studio, or <code>sdkmanager</code> on the command line),
-and make sure the following are installed:</p>
+<p>In the Android Studio, open the <strong>SDK Manager</strong> (<code>Tools
> SDK Manager</code>) and confirm that the following are installed for the
targeted version of Android.:</p>
-<ol>
- <li>Android Platform SDK for your targeted version of Android</li>
- <li>Android SDK build-tools version 29.0.2 or higher</li>
-</ol>
+<ul>
+ <li>Android's <strong>SDK Platform</strong> for your targeted API
Level</li>
+ <li><strong>Android SDK Build-Tools</strong> under the <strong>SDK
Tools</strong> tab, for the targeted version.</li>
+</ul>
+
+<h4>Android SDK Tools</h4>
-<h4>Android SDK Tools:</h4>
-<p>In Android Studio 3.6 or later, you need to manually add the old version of
the Android SDK Tools. To do this:</p>
+<p>In Android Studio 3.6 or later, the obsolete Android SDK Tools will need to
be intalled. To do this:</p>
<ol>
- <li>Open the Android Studio <strong>SDK Manager</strong></li>
- <li>In the Android <strong>SDK Tools</strong> tab, uncheck <code>Hide
Obsolete Packages</code></li>
+ <li>Open the Android Studio</li>
+ <li>Open the <strong>SDK Manager</strong> (<code>Tools > SDK
Manager</code>)</li>
+ <li>Navigate to the <strong>SDK Tools</strong> tab</li>
+ <li>Uncheck <code>Hide Obsolete Packages</code></li>
<li>Check <code>Android SDK Tools (Obsolete)</code></li>
</ol>
-<p>See Android's documentation on <a
href="https://developer.android.com/studio/intro/update";>Installing SDK
Packages</a>
-for more details.</p>
+<p>See Android's documentation on how to <a
href="https://developer.android.com/studio/intro/update#sdk-manager";>Update
your tools with the SDK Manager</a> for more details.</p>
<h3>Setting environment variables</h3>
-<p>Cordova's CLI tools require some environment variables to be set in
order to
-function correctly. The CLI will attempt to set these variables for you, but
-in certain cases you may need to set them manually. The following variables
-should be updated:</p>
+<p>Cordova's CLI requires specific environment variables so it can
function correctly. If the environment variables are missing, the CLI will
attempt to resolve the variable temporarily. If the missing variables fail to
resolve, they must be set manually.</p>
-<ol>
- <li>Set the <code>JAVA_HOME</code> environment variable to the location of
your JDK
-installation</li>
- <li>Set the <code>ANDROID_SDK_ROOT</code> environment variable to the
location of your Android
-SDK installation</li>
- <li>It is also recommended that you add the Android SDK's
<code>cmdline-tools/latest/bin</code>, <code>emulator</code>
-and <code>platform-tools</code> directories to your <code>PATH</code></li>
- <li>For apksigner and zipalign, the Android SDK's
<code>build-tools</code> must also be added to your <code>PATH</code></li>
-</ol>
+<p>The following variables must be set:</p>
+
+<ul>
+ <li><code>JAVA_HOME</code> - The environment variable to the location of
your JDK installation</li>
+ <li><code>ANDROID_SDK_ROOT</code> - The environment variable to the location
of your Android SDK installation</li>
+</ul>
+
+<p>It is also recommended to update the <code>PATH</code> environment variable
to include the following directories.</p>
+
+<ul>
+ <li><code>cmdline-tools/latest/bin</code></li>
+ <li><code>emulator</code></li>
+ <li><code>platform-tools</code></li>
+ <li><code>build-tools</code>
+ <ul>
+ <li>This is required for the <code>apksigner</code> and
<code>zipalign</code> tools.</li>
+ </ul>
+ </li>
+</ul>
-<h4>OS X and Linux</h4>
+<p><em><strong>Note:</strong> The directories above are generally located in
the Android SDK ROOT.</em></p>
-<p>On a Mac or Linux, you can use a text editor to create or modify the
-<code>~/.bash_profile</code> file. To set an environment variable, add a line
that uses
-<code>export</code> like so (substitute the path with your local
installation):</p>
+<h4>macOS and Linux</h4>
+
+<p>On a Mac or Linux, with a text editor, create or modify the
<code>~/.bash_profile</code> file.</p>
+
+<p>To set an environment variable, add a line that uses <code>export</code>
like so (substitute the path with your local installation):</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="nb">export </span><span
class="nv">ANDROID_SDK_ROOT</span><span
class="o">=</span>/Development/android-sdk/
</code></pre></div></div>
-<p>To update your <code>PATH</code>, add a line resembling the following
(substitute the paths
-with your local Android SDK installation's location):</p>
+<p>To update your <code>PATH</code>, add a line resembling the following
(substitute the paths with your local Android SDK installation's
location):</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="nb">export </span><span
class="nv">PATH</span><span class="o">=</span><span
class="nv">$PATH</span>:<span
class="nv">$ANDROID_SDK_ROOT</span>/platform-tools/
<span class="nb">export </span><span class="nv">PATH</span><span
class="o">=</span><span class="nv">$PATH</span>:<span
class="nv">$ANDROID_SDK_ROOT</span>/cmdline-tools/latest/bin/
@@ -2440,78 +2445,77 @@ with your local Android SDK installation's
location):</p>
<p>Reload your terminal to see this change reflected or run the following
command:</p>
-<div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="nv">$ </span><span
class="nb">source</span> ~/.bash_profile
+<div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="nb">source</span> ~/.bash_profile
</code></pre></div></div>
<h4>Windows</h4>
-<p>These steps may vary depending on your installed version of Windows. Close
and
-reopen any command prompt windows after making changes to see them
reflected.</p>
+<p>These steps may vary depending on your installed version of Windows. Close
and reopen any command prompt windows after making changes to see them
reflected.</p>
<ol>
- <li>
- <p>Click on the <strong>Start</strong> menu in the lower-left corner of
the desktop</p>
- </li>
- <li>
- <p>In the search bar, search for <strong>Environment Variables</strong>
and select <strong>Edit the
-system Environment Variables</strong> from the options that appear</p>
- </li>
- <li>
- <p>In the window that appears, click the <strong>Environment
Variables</strong> button</p>
- </li>
+ <li>Click on the <strong>Start</strong> menu or Press on the
<strong>Windows</strong> Key (<strong>Win</strong>)</li>
+ <li>Type in the search bar <code>Environment Variables</code></li>
+ <li>Select <strong>Edit the system environment variables</strong>
options</li>
+ <li>Click on the <strong>Environment Variables…</strong> button in the
window that appears.</li>
</ol>
-<h5>To create a new environment variable:</h5>
+<h5>To create a new environment variable</h5>
<ol>
- <li>Click <strong>New…</strong> and enter the variable name and
value</li>
+ <li>Click on the <strong>New…</strong> button</li>
+ <li>Type in the <strong>Variable name</strong></li>
+ <li>Type in the <strong>Variable value</strong></li>
+ <li>Click on the <strong>OK</strong> button</li>
</ol>
-<h5>To set your <strong>PATH</strong>:</h5>
+<h5>To set your PATH</h5>
<ol>
- <li>
- <p>Select the <strong>PATH</strong> variable and press
<strong>Edit</strong>.</p>
- </li>
- <li>
- <p>Add entries for the relevant locations to the <strong>PATH</strong>.
For example
-(substitute the paths with your local Android SDK installation's
location):</p>
-
- <div class="language-plaintext highlighter-rouge"><div
class="highlight"><pre class="highlight"><code> C:\Users\[your
user]\AppData\Local\Android\Sdk\platform-tools
- C:\Users\[your user]\AppData\Local\Android\Sdk\cmdline-tools\latest\bin
- C:\Users\[your user]\AppData\Local\Android\Sdk\tools\emulator
-</code></pre></div> </div>
- </li>
+ <li>Select <strong>PATH</strong> from the liste of already defined
variable</li>
+ <li>Click on the <strong>Edit…</strong> button</li>
+ <li>Click on the <strong>New</strong> button</li>
+ <li>Type in the relevant location.</li>
</ol>
+<p>Repeat step 3 and 4 until all paths are added.</p>
+
+<p>Example paths (substitute the paths with your local Android SDK
installation's location):</p>
+
+<pre><code class="language-txt">C:\Users\[your
user]\AppData\Local\Android\Sdk\platform-tools
+C:\Users\[your user]\AppData\Local\Android\Sdk\cmdline-tools\latest\bin
+C:\Users\[your user]\AppData\Local\Android\Sdk\tools\emulator
+</code></pre>
+
+<p>Once all paths are added, click the <strong>OK</strong> button until all
opened windows for setting & editing environment variables are closed.</p>
+
<h2>Project Configuration</h2>
<h3>Setting up an Emulator</h3>
-<p>If you wish to run your Cordova app on an Android emulator, you will first
need
-to create an Android Virtual Device (AVD). See the Android documentation for
-<a href="https://developer.android.com/studio/run/managing-avds.html";>managing
AVDs</a>,
-<a
href="https://developer.android.com/studio/run/emulator.html#about";>configuring
the emulator</a>,
-and <a
href="https://developer.android.com/studio/run/emulator-acceleration.html";>setting
up hardware acceleration</a>.</p>
+<p>If you wish to run your Cordova app on an Android emulator, you will first
need to create an Android Virtual Device (AVD).</p>
+
+<p>See the following Android documentation for more details on:</p>
-<p>Once your AVD is configured correctly, you should be able to deploy your
Cordova
-application to the emulator by running:</p>
+<ul>
+ <li><a
href="https://developer.android.com/studio/run/managing-avds.html";>Create and
manage virtual devices</a></li>
+ <li><a
href="https://developer.android.com/studio/run/emulator.html#about";>Run apps on
the Android Emulator</a></li>
+ <li><a
href="https://developer.android.com/studio/run/emulator-acceleration.html";>Configure
hardware acceleration for the Android Emulator</a>.</li>
+</ul>
-<div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="nv">$ </span>cordova run <span
class="nt">--emulator</span>
+<p>Once your AVD is configured correctly, you should be able to deploy your
Cordova application to the emulator by running the following command:</p>
+
+<div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code>cordova run <span class="nt">--emulator</span>
</code></pre></div></div>
<h3>Configuring Gradle</h3>
-<p>As of <strong>cordova-android@4.0.0</strong>, Cordova for Android projects
are built using
-<a href="http://www.gradle.org/";>Gradle</a>. For instructions on building with
Ant, refer
-to older versions of the documentation. Please note that Ant builds are
-deprecated as of the Android SDK Tools 25.3.0.</p>
+<p>Cordova-Android projects are built by using <a
href="https://gradle.org/";>Gradle</a>.</p>
<h4>Setting Gradle Properties</h4>
-<p>It is possible to configure the Gradle build by setting the values of
certain
-<a
href="https://docs.gradle.org/current/userguide/build_environment.html";>Gradle
properties</a>
-that Cordova exposes. The following properties are available to be set:</p>
+<p>It is possible to configure the Gradle build by setting the values of
certain <a
href="https://docs.gradle.org/current/userguide/build_environment.html";>Gradle
properties</a> that Cordova exposes.</p>
+
+<p>The following properties are available:</p>
<table>
<thead>
@@ -2521,87 +2525,106 @@ that Cordova exposes. The following properties are
available to be set:</p>
</tr>
</thead>
<tbody>
+ <tr>
+ <td><code>cdvAndroidXAppCompatVersion</code></td>
+ <td>Sets the version of the <code>androidx.appcompat:appcompat</code>
library.</td>
+ </tr>
+ <tr>
+ <td><code>cdvAndroidXWebKitVersion</code></td>
+ <td>Sets the version of the <code>androidx.webkit:webkit</code>
library.</td>
+ </tr>
+ <tr>
+ <td><code>cdvBuildArch</code></td>
+ <td>Overrides the build architecture of which the app is built for. The
default value is automatically detected by Cordova's build script.</td>
+ </tr>
<tr>
<td><code>cdvBuildMultipleApks</code></td>
<td>If this is set, then multiple APK files will be generated: One per
native platform supported by library projects (x86, ARM, etc). This can be
important if your project uses large native libraries, which can drastically
increase the size of the generated APK. If not set, then a single APK will be
generated which can be used on all devices</td>
</tr>
<tr>
- <td><code>cdvVersionCode</code></td>
- <td>Overrides the versionCode set in
<code>AndroidManifest.xml</code></td>
+ <td><code>cdvBuildToolsVersion</code></td>
+ <td>Overrides the automatically detected
<code>android.buildToolsVersion</code> value</td>
</tr>
<tr>
- <td><code>cdvReleaseSigningPropertiesFile</code></td>
- <td><em>Default: <code>release-signing.properties</code></em><br />Path
to a .properties file that contains signing information for release builds (see
<a href="#signing-an-app">Signing an App</a>)</td>
+ <td><code>cdvCompileSdkVersion</code></td>
+ <td>Sets the SDK version of the framework which the app is been compiled
for. Setting will override the automatic detection of the
<code>android.compileSdkVersion</code> value.</td>
</tr>
<tr>
<td><code>cdvDebugSigningPropertiesFile</code></td>
<td><em>Default: <code>debug-signing.properties</code></em><br />Path to
a .properties file that contains signing information for debug builds (see <a
href="#signing-an-app">Signing an App</a>). Useful when you need to share a
signing key with other developers</td>
</tr>
+ <tr>
+ <td><code>cdvMaxSdkVersion</code></td>
+ <td>set the maximum API Level which the application can run on</td>
+ </tr>
<tr>
<td><code>cdvMinSdkVersion</code></td>
<td>Overrides the value of <code>minSdkVersion</code> set in
<code>AndroidManifest.xml</code>. Useful when creating multiple APKs based on
SDK version</td>
</tr>
<tr>
- <td><code>cdvBuildToolsVersion</code></td>
- <td>Overrides the automatically detected
<code>android.buildToolsVersion</code> value</td>
+ <td><code>cdvReleaseSigningPropertiesFile</code></td>
+ <td><em>Default: <code>release-signing.properties</code></em><br />Path
to a .properties file that contains signing information for release builds (see
<a href="#signing-an-app">Signing an App</a>)</td>
</tr>
<tr>
- <td><code>cdvCompileSdkVersion</code></td>
- <td>Overrides the automatically detected
<code>android.compileSdkVersion</code> value</td>
+ <td><code>cdvSdkVersion</code></td>
+ <td>Overrides the <code>targetSdkVersion</code> value.</td>
+ </tr>
+ <tr>
+ <td><code>cdvVersionCode</code></td>
+ <td>Overrides the versionCode set in
<code>AndroidManifest.xml</code></td>
+ </tr>
+ <tr>
+ <td><code>cdvVersionCodeForceAbiDigit</code></td>
+ <td>Whether to append a 0 "abi digit" to versionCode when only
a single APK is build.</td>
</tr>
</tbody>
</table>
<p>You can set these properties in one of four ways:</p>
-<ol>
+<ul>
<li>
- <p>By setting environment variables like so:</p>
+ <p>Using an Environment Variables:</p>
+
+ <p><strong>Example:</strong></p>
- <div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code> <span class="nv">$ </span><span class="nb">export
</span><span class="nv">ORG_GRADLE_PROJECT_cdvMinSdkVersion</span><span
class="o">=</span>20
- <span class="nv">$ </span>cordova build android
+ <div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code> <span class="nb">export </span><span
class="nv">ORG_GRADLE_PROJECT_cdvMinSdkVersion</span><span class="o">=</span>20
+ cordova build android
</code></pre></div> </div>
</li>
<li>
- <p>By using the <code>--gradleArg</code> flag in your Cordova
<code>build</code> or <code>run</code> commands:</p>
+ <p>Using the <code>--gradleArg</code> flag with the Cordova
<code>build</code> or <code>run</code> command:</p>
- <div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code> <span class="nv">$ </span>cordova run android <span
class="nt">--</span> <span class="nt">--gradleArg</span><span
class="o">=</span><span class="nt">-PcdvMinSdkVersion</span><span
class="o">=</span>20
+ <p><strong>Example:</strong></p>
+
+ <div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code> cordova run android <span class="nt">--</span> <span
class="nt">--gradleArg</span><span class="o">=</span><span
class="nt">-PcdvMinSdkVersion</span><span class="o">=</span>20
</code></pre></div> </div>
</li>
<li>
- <p>By placing a file called <code>gradle.properties</code> in your Android
platform
- folder (<code><your-project>/platforms/android</code>) and setting the
properties in it
- like so:</p>
+ <p>Creating a <code>gradle.properties</code> in the project's Android
platform directory</p>
+
+ <p>Create a file named <code>gradle.properties</code> in the directory
<code><project-root>/platforms/android</code> with the contents such
as:</p>
- <div class="language-plaintext highlighter-rouge"><div
class="highlight"><pre class="highlight"><code> # In
<your-project>/platforms/android/app/gradle.properties
- cdvMinSdkVersion=20
+ <p><strong>Example File Contents:</strong></p>
+
+ <div class="language-groovy highlighter-rouge"><div class="highlight"><pre
class="highlight"><code> <span class="n">cdvMinSdkVersion</span><span
class="o">=</span><span class="mi">20</span>
</code></pre></div> </div>
</li>
<li>
- <p>By extending <code>build.gradle</code> via a <a
href="#extending-buildgradle"><code>build-extras.gradle</code> file</a>
- and setting the property like so:</p>
+ <p><a href="#extending-buildgradle">Extending
<code>build.gradle</code></a> with the `build-extras.gradle file</p>
+
+ <p>Create a file named <code>build-extras.gradle</code> in the directory
<code><project-root>/platforms/android/app</code> with the contents such
as:</p>
- <div class="language-groovy highlighter-rouge"><div class="highlight"><pre
class="highlight"><code> <span class="c1">// In
<your-project>/platforms/android/app/build-extras.gradle</span>
- <span class="n">ext</span><span class="o">.</span><span
class="na">cdvMinSdkVersion</span> <span class="o">=</span> <span
class="mi">20</span>
+ <div class="language-groovy highlighter-rouge"><div class="highlight"><pre
class="highlight"><code> <span class="n">ext</span><span
class="o">.</span><span class="na">cdvMinSdkVersion</span> <span
class="o">=</span> <span class="mi">20</span>
</code></pre></div> </div>
</li>
-</ol>
+</ul>
-<p>The latter two options both involve including an extra file in your Android
-platform folder. In general, it is discouraged that you edit the contents of
-this folder because it is easy for those changes to be lost or overwritten.
-Instead, these two files should be copied from another location into that
folder
-as part of the build command by using the <code>before_build</code>
-<a href="../../appdev/hooks/index.html">hook</a>.</p>
+<p>The latter two options both involve including an extra file in your Android
platform folder. In general, it is discouraged to edit the contents of this
folder because it is easy for those changes to be lost or overwritten. Instead,
these files should be copied into the folder as part of the build command by
using the <code>before_build</code> <a
href="../../appdev/hooks/index.html">hook script</a>.</p>
<h4>Extending build.gradle</h4>
-<p>If you need to customize <code>build.gradle</code>, rather than edit it
directly, you
-should create a sibling file named <code>build-extras.gradle</code>. This file
will be
-included by the main <code>build.gradle</code> when present. This file must be
placed in
-the <code>app</code> folder of the Android platform directory
(<code><your-project>/platforms/android/app</code>),
-so it is recommended that you copy it over via a script attached to the
-<code>before_build</code> <a href="../../appdev/hooks/index.html">hook</a>.</p>
+<p>If you need to customize the <code>build.gradle</code> file, rather than
edit it directly, it is recommended to create a sibling file named
<code>build-extras.gradle</code>. This file will be included by the main
<code>build.gradle</code> script when present. This file must be placed in the
<code>app</code> folder of the Android's platform directory
(<code><your-project>/platforms/android/app</code>). It is recommended to
use the <code>before_build</code> <a href="../../appd [...]
<p>Here's an example:</p>
@@ -2636,9 +2659,9 @@ so it is recommended that you copy it over via a script
attached to the
<h4>Configuring Gradle JVM Args</h4>
-<p>To change the Gradle JVM args, the <code>--jvmargs</code> flag can be used
with both cordova build and run commands. This is mostly useful for controlling
how much memory gradle is allowed to use during the build process. It is
recommended to allow at least 2048 MB.</p>
+<p>To change the Gradle JVM args, the <code>--jvmargs</code> flag can be used
with both Cordova's <code>build</code> and <code>run</code> commands. This
is mostly useful for controlling how much memory gradle is allowed to use
during the build process. It is recommended to allow at least 2048 MB.</p>
-<p>By default, JVM args has a value of <code>-Xmx2048m</code>. To increase the
max allowed memory, use the <code>-Xmx</code> JVM arg. Example given below:</p>
+<p>By default, JVM args has a value of <code>-Xmx2048m</code>. To increase the
maximum allowed memory, use the <code>-Xmx</code> JVM arg. Example given
below:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre
class="highlight"><code>cordova build android -- --jvmargs='-Xmx4g'
</code></pre></div></div>
@@ -2674,35 +2697,23 @@ so it is recommended that you copy it over via a script
attached to the
<h3>Setting the Version Code</h3>
-<p>To change the <a
href="https://developer.android.com/studio/publish/versioning.html";>version
code</a>
-for your app's generated apk, set the <code>android-versionCode</code>
attribute in the widget
-element of your application's <a
href="../../../config_ref/index.html">config.xml file</a>.
-If the <code>android-versionCode</code> is not set, the version code will be
determined
-using the <code>version</code> attribute. For example, if the version is
<code>MAJOR.MINOR.PATCH</code>:</p>
+<p>To change the <a
href="https://developer.android.com/studio/publish/versioning";>version code</a>
for your app's generated apk, set the <code>android-versionCode</code>
attribute in the <code>widget</code> element of your application's <a
href="../../../config_ref/index.html">config.xml</a> file.</p>
-<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre
class="highlight"><code>versionCode = MAJOR * 10000 + MINOR * 100 + PATCH
+<p>If the <code>android-versionCode</code> is not set, the version code will
be determined using the <code>version</code> attribute. For example, if the
version is <code>MAJOR.MINOR.PATCH</code>:</p>
+
+<div class="language-groovy highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="n">versionCode</span> <span
class="o">=</span> <span class="n">MAJOR</span> <span class="o">*</span> <span
class="mi">10000</span> <span class="o">+</span> <span class="n">MINOR</span>
<span class="o">*</span> <span class="mi">100</span> <span class="o">+</span>
<span class="n">PATCH</span>
</code></pre></div></div>
-<p>If your application has enabled the <code>cdvBuildMultipleApks</code>
Gradle property (see
-<a href="#setting-gradle-properties">Setting Gradle Properties</a>), the
version code of
-your app will also be multiplied by 10 so that the last digit of the code can
be
-used to indicate the architecture the apk was built for. This multiplication
-will happen regardless of whether the version code is taken from the
-<code>android-versionCode</code> attribute or generated using the
<code>version</code>. Be aware that
-some plugins added to your project (including cordova-plugin-crosswalk-webview)
-may set this Gradle property automatically.</p>
-
-<p><strong>Please Note:</strong> When updating the
<code>android-versionCode</code> property, it is unwise
-to increment the version code taken from built apks. Instead, you should
-increment the code based off the value in your <code>config.xml</code>
file's
-<code>android-versionCode</code> attribute. This is because the
<code>cdvBuildMultipleApks</code>
-property causes the version code to be multiplied by 10 in the built apks and
-thus using that value will cause your next version code to be 100 times the
-original, etc.</p>
+<p>If your application has enabled the <code>cdvBuildMultipleApks</code>
Gradle property (see <a href="#setting-gradle-properties">Setting Gradle
Properties</a>), the version code of your app will also be multiplied by 10 so
that the last digit of the code can be used to indicate the architecture the
apk was built for. This multiplication
+will happen regardless of whether the version code is taken from the
<code>android-versionCode</code> attribute or generated using the
<code>version</code>.</p>
+
+<p><em><strong>Note:</strong> Be aware that some plugins added to your project
may set this Gradle property automatically.</em></p>
+
+<p><em><strong>Note:</strong> When updating the
<code>android-versionCode</code> property, it is not recommended to increment
the version code taken from built apks. It is recommended to increment the code
based off the value in your <code>config.xml</code> file's
<code>android-versionCode</code> attribute. This is because the
<code>cdvBuildMultipleApks</code> property causes the version code to be
multiplied by 10 in the built apks and thus using that value will cause your
next vers [...]
<h2>Signing an App</h2>
-<p>First, you should read the <a
href="https://developer.android.com/studio/publish/app-signing.html";>Android
app signing requirements</a>.</p>
+<p>It is recommended to read Android's documentation for <a
href="https://developer.android.com/studio/publish/app-signing";>Sign your
app</a> first, as it contains the necessary steps in creating required files
for signing.</p>
<h3>Using Flags</h3>
@@ -2745,23 +2756,26 @@ original, etc.</p>
<tr>
<td>Package Type</td>
<td><code>--packageType</code></td>
- <td><em>Default: apk</em><br />Specify whether to build an APK or an
[Android App Bundle] (https://developer.android.com/guide/app-bundle) (.aab)
file.<br />Accepts either <code>apk</code> or <code>bundle</code></td>
+ <td><em>Default: apk</em><br />Specify whether to build an APK or an <a
href="https://developer.android.com/guide/app-bundle";>AAB</a> (Android App
Bundle) file.<br />Acceptable Values: <code>apk</code> or
<code>bundle</code></td>
</tr>
</tbody>
</table>
-<p>These parameters can be specified using the command line arguments above to
-the <a href="../../../reference/cordova-cli/index.html">Cordova CLI</a>
<code>build</code> or <code>run</code> commands.</p>
+<p>The parameters above can be specified as an argument when using the <a
href="../../../reference/cordova-cli/index.html">Cordova CLI</a>
<code>build</code> or <code>run</code> commands.</p>
+
+<p><em><strong>Note</strong>: You should use double <code>--</code> to
indicate that these are platform-specific arguments.</em></p>
-<p><strong>Note</strong>: You should use double <code>--</code> to indicate
that these are platform-specific arguments, for example:</p>
+<p>Example:</p>
<p><code>cordova run android --release --
--keystore=../my-release-key.keystore --storePassword=password
--alias=alias_name --password=password --packageType=bundle</code>.</p>
-<h3>Using build.json</h3>
+<h3>Using <code>build.json</code></h3>
-<p>Alternatively, you could specify them in a build configuration file
(<code>build.json</code>)
-using the <code>--buildConfig</code> argument to the same commands. Here's
a sample of a
-build configuration file:</p>
+<p>Alternatively, you could specify the signing parameters in a build
configuration file (<code>build.json</code>).</p>
+
+<p>By default, if the <code>build.json</code> file exists in the project's
root directory, it will automatically be detected and used. If the file is not
located in the project's root directory or has multiple configuration
files, the command line argument <code>--buildConfig</code> must be supplied
with the path to the file.</p>
+
+<p><strong>Example <code>build.json</code> configuration file:</strong></p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nl">"android"</span><span class="p">:</span><span
class="w"> </span><span class="p">{</span><span class="w">
@@ -2785,131 +2799,73 @@ build configuration file:</p>
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
-<p>There is also support to mix and match command line arguments and
parameters in
-<code>build.json</code>. Values from the command line arguments will get
precedence.
-This can be useful for specifying passwords on the command line.</p>
+<p>There is also support to mix and match command line arguments and
parameters in <code>build.json</code>. Values from the command line arguments
takes precedence. This can be useful for specifying passwords on the command
line.</p>
<h3>Using Gradle</h3>
-<p>You can also specify signing properties by including a
<code>.properties</code> file and
-pointing to it with the <code>cdvReleaseSigningPropertiesFile</code> and
-<code>cdvDebugSigningPropertiesFile</code> Gradle properties (see <a
href="#setting-gradle-properties">Setting Gradle Properties</a>).
-The file should look like this:</p>
+<p>You can also specify signing properties by including a
<code>.properties</code> file and pointing to it with the
<code>cdvReleaseSigningPropertiesFile</code> and
<code>cdvDebugSigningPropertiesFile</code> Gradle properties (see <a
href="#setting-gradle-properties">Setting Gradle Properties</a>).</p>
-<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre
class="highlight"><code>storeFile=relative/path/to/keystore.p12
-storePassword=SECRET1
-storeType=pkcs12
-keyAlias=DebugSigningKey
-keyPassword=SECRET2
+<p><strong>Example file content:</strong></p>
+
+<div class="language-properties highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="py">storeFile</span><span
class="p">=</span><span class="s">relative/path/to/keystore.p12</span>
+<span class="py">storePassword</span><span class="p">=</span><span
class="s">SECRET1</span>
+<span class="py">storeType</span><span class="p">=</span><span
class="s">pkcs12</span>
+<span class="py">keyAlias</span><span class="p">=</span><span
class="s">DebugSigningKey</span>
+<span class="py">keyPassword</span><span class="p">=</span><span
class="s">SECRET2</span>
</code></pre></div></div>
-<p><code>storePassword</code> and <code>keyPassword</code> are required for
automated signing.</p>
+<p>The <code>storePassword</code> and <code>keyPassword</code> properties are
required for automated signing.</p>
<h2>Debugging</h2>
<p>For details on the debugging tools that come packaged with the Android SDK,
see
<a href="https://developer.android.com/studio/debug/index.html";>Android's
developer documentation for debugging</a>.
-Additionally, Android's developer documentation for <a
href="http://developer.android.com/guide/webapps/debugging.html";>debugging web
apps</a>
+Additionally, Android's developer documentation for <a
href="https://developer.android.com/guide/webapps/debugging.html";>debugging web
apps</a>
provides an introduction for debugging the portion of your app running in the
Webview.</p>
<h3>Opening a Project in Android Studio</h3>
-<p>Cordova for Android projects can be opened in the Android IDE,
-<a href="https://developer.android.com/studio/index.html";>Android Studio</a>.
-This can be useful if you wish to use Android Studio's built in Android
-debugging/profiling tools or if you are developing Android plugins. Please note
-that when opening your project in Android studio, it is recommended that you do
-NOT edit your code in the IDE. This will edit the code in the
<code>platforms</code> folder
-of your project (not <code>www</code>), and changes are liable to be
overwritten. Instead,
-edit the <code>www</code> folder and copy over your changes by running
<code>cordova build</code>.</p>
+<p>Cordova-Android projects can be opened in <a
href="https://developer.android.com/studio/index.html";>Android Studio</a>. This
can be useful if you wish to use Android Studio's built in Android
debugging and profiling tools or if you are developing Android plugins.</p>
-<p>Plugin developers wishing to edit their native code in the IDE should use
the
-<code>--link</code> flag when adding their plugin to the project via
<code>cordova plugin add</code>.
-This will link the files so that changes to the plugin files in the
<code>platforms</code>
-folder are reflected in your plugin's source folder (and vice versa).</p>
+<p><em><strong>Note:</strong> When opening your project in Android Studio, it
is recommended to NOT edit the code within the IDE. Editing in Android Studio
will edit code residing in the <code>platforms</code> directory of your
project. It is not updating the code in the projects root
<code>www</code>)directory. The changes are liable to be overwritten. Instead,
edit the <code>www</code> folder and copy over your changes by running
<code>cordova prepare</code>.</em></p>
-<p>To open a Cordova for Android project in Android Studio:</p>
+<p>Plugin developers wishing to edit their native code in Android Studio
should use the <code>--link</code> flag when adding their plugin to the project
with the <code>cordova plugin add</code>. This will create a symbolic link of
the plugin files from the plugin source directory to the project's
<code>platforms</code> directory.</p>
-<ol>
- <li>
- <p>Launch <strong>Android Studio</strong>.</p>
- </li>
- <li>
- <p>Select <strong>Import Project (Eclipse ADT, Gradle, etc)</strong>.</p>
+<p>To open a Cordova-Android project in Android Studio:</p>
- <p><img src="/static/img/guide/platforms/android/asdk_import_project.png"
alt="" /></p>
- </li>
- <li>
- <p>Select the Android platform directory in your project
(<code><your-project>/platforms/android</code>).</p>
-
- <p><img
src="/static/img/guide/platforms/android/asdk_import_select_location.png"
alt="" /></p>
- </li>
- <li>
- <p>For the <code>Gradle Sync</code> question you can simply answer
<strong>Yes</strong>.</p>
- </li>
+<ol>
+ <li>Launch <strong>Android Studio</strong></li>
+ <li>Click the <strong>Open</strong> button
+ <img src="/static/img/guide/platforms/android/asdk_import_project.png" alt=""
/></li>
+ <li>Navigate to the project's Android platform directory:
(<code><project-root>/platforms/android</code>)
+ <img
src="/static/img/guide/platforms/android/asdk_import_select_location.png"
alt="" /></li>
+ <li>For the <code>Gradle Sync</code> question you can simply answer
<strong>Yes</strong>.</li>
</ol>
-<p>Once it finishes importing, you should be able to build and run the app
directly
-from <strong>Android Studio</strong>. See <a
href="https://developer.android.com/studio/intro/index.html";>Android Studio
Overview</a>
-and <a href="https://developer.android.com/studio/run/index.html";>Building and
Running from Android Studio</a>
-for more details.</p>
-
-<p><img src="/static/img/guide/platforms/android/asdk_import_done.png" alt=""
/></p>
-
-<h2>Platform Centered Workflow</h2>
-
-<p>cordova-android includes a number of scripts that allow the platform to be
used
-without the full Cordova CLI. This development path may offer you a greater
-range of development options in certain situations than the cross-platform
-cordova CLI. For example, you need to use shell tools when deploying a custom
-Cordova WebView alongside native components. Before using this development
path,
-you must still configure the Android SDK environment as described in
-<a href="#requirements-and-support">Requirements and Support</a> above.</p>
-
-<p>For each of the scripts discussed below, refer to <a
href="../../../reference/cordova-cli/index.html">Cordova CLI Reference</a>
-for more information on their arguments and usage. Each script has a name that
-matches the corresponding CLI command. For example,
<code>cordova-android/bin/create</code>
-is equivalent to <code>cordova create</code>.</p>
-
-<p>To get started, either download the cordova-android package from
-<a href="https://www.npmjs.com/package/cordova-android";>npm</a> or
-<a href="https://github.com/apache/cordova-android";>Github</a>.</p>
+<p>Once it finishes importing, you should be able to build and run the app
directly from <strong>Android Studio</strong>.</p>
-<p>To create a project using this package, run the <code>create</code> script
in the <code>bin</code>
-folder:</p>
+<p>For more resources, please see:</p>
-<div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="nv">$ </span>cordova-android/bin/create
-</code></pre></div></div>
-
-<p>The created project will have a folder named <code>cordova</code> inside
that contains
-scripts for the project-specific Cordova commands (e.g. <code>run</code>,
<code>build</code>, etc.).
-Additionally, the project will feature a structure different from that of a
-normal Cordova project. Notably, <code>/www</code> is moved to
<code>/assets/www</code>.</p>
+<ul>
+ <li><a href="https://developer.android.com/studio/intro";>Meet Android
Studio</a></li>
+ <li><a href="https://developer.android.com/studio/run/index.html";>Build and
run your app</a></li>
+</ul>
-<p>To install plugins in this project, use the <a
href="../../../plugin_ref/plugman.html">Cordova Plugman Utility</a>.</p>
+<p><img src="/static/img/guide/platforms/android/asdk_import_done.png" alt=""
/></p>
<h2>Upgrading</h2>
-<p>Refer to <a href="./upgrade.html">this</a> article for instructions to
upgrade your
-<code>cordova-android</code> version.</p>
+<p>Refer to <a href="./upgrade.html">this</a> article for instructions to
upgrade your <code>cordova-android</code> version.</p>
<h2>Lifecycle Guide</h2>
<h3>Cordova and Android</h3>
-<p>Native Android apps typically consist of a series of <a
href="http://developer.android.com/reference/android/app/Activity.html";>activities</a>
that the user
-interacts with. Activities can be thought of as the individual screens that
make
-up an application; different tasks in an app will often have their own
activity.
-Each activity has its own lifecycle that is maintained as the activity enters
-and leaves the foreground of a user's device.</p>
+<p>Native Android apps typically consist of a series of <a
href="https://developer.android.com/reference/android/app/Activity";>activities</a>
that the user interacts with. Activities can be thought of as the individual
screens that make
+up an application; different tasks in an app will often have their own
activity. Each activity has its own lifecycle that is maintained as the
activity enters and leaves the foreground of a user's device.</p>
-<p>In contrast, Cordova applications on the Android platform are executed
within a
-Webview that is embedded in a <em>single</em> Android activity. The lifecycle
of this
-activity is exposed to your application through the document events that are
-fired. The events are not guaranteed to line up with Android's lifecycle,
but
-they can provide guidelines for saving and restoring your state. These events
-roughly map to Android callbacks as follows:</p>
+<p>In contrast, Cordova applications on the Android platform are executed
within a Webview that is embedded in a <em>single</em> Android activity. The
lifecycle of this activity is exposed to your application through the document
events that are fired. The events are not guaranteed to line up with
Android's lifecycle, but they can provide guidelines for saving and
restoring your state. These events roughly map to Android callbacks as
follows:</p>
<table>
<thead>
@@ -2938,48 +2894,19 @@ roughly map to Android callbacks as follows:</p>
</tbody>
</table>
-<p>Most other Cordova platforms have a similar concept of lifecycles and should
-fire these same events when similar actions happen on a user's device.
However,
-Android presents some unique challenges that can sometimes show up thanks to
the
-native Activity lifecycle.</p>
+<p>Most other Cordova platforms have a similar concept of lifecycles and
should fire these same events when similar actions happen on a user's
device. However, Android presents some unique challenges that can sometimes
show up thanks to the native Activity lifecycle.</p>
<h3>What makes Android different?</h3>
-<p>In Android, the OS can choose to kill activities in the background in order
to
-free up resources if the device is low on memory. Unfortunately, when the
-activity holding your application is killed, the Webview in which your
-application lives will be destroyed as well. Any state that your application is
-maintaining will be lost in this case. When the user navigates back to your
-application, the Activity and Webview will be recreated by the OS, but state
-will not be automatically restored for your Cordova app. For this reason, it is
-imperative that your application be aware of the lifecycle events that are
fired
-and maintain whatever state is appropriate to make sure a user's context
in your
-app is not lost when they leave the application.</p>
+<p>In Android, the OS can choose to kill activities in the background in order
to free up resources if the device is low on memory. Unfortunately, when the
activity holding your application is killed, the Webview in which your
application lives will be destroyed as well. Any state that your application is
maintaining will be lost in this case. When the user navigates back to your
application, the Activity and Webview will be recreated by the OS, but state
will not be automatically restor [...]
<h3>When can this happen?</h3>
-<p>Your application is susceptible to being destroyed by the OS whenever it
leaves
-the sight of the user. There are two main situations in which this can occur.
-The first and most obvious case is when the user presses the home button or
-switches to another application.</p>
-
-<p>However, there is a second (and much more subtle) case that certain plugins
can
-introduce. As noted above, Cordova applications are usually confined to the
-single activity that contains the Webview. However, there are instances in
which
-other activities may be launched by plugins and temporarily push the Cordova
-activity to the background. These other Activities are typically launched in
-order to perform a specific task using a native application installed on the
-device. For example, the <a
href="../../../reference/cordova-plugin-camera/index.html">Cordova camera
plugin</a>
-launches whatever camera activity is natively installed on the device in order
-to take a photo. Reusing the installed camera application in this way makes
your
-application feel much more like a native app when the user tries to take a
-photo. Unfortunately, when the native Activity pushes your app to the
background
-there is a chance the OS will kill it.</p>
-
-<p>For a clearer understanding of this second case, let's walk through an
example
-using the camera plugin. Imagine you have an application that requires the user
-to take a profile photo. The flow of events in the application when everything
-goes as planned will look something like this:</p>
+<p>Your application is susceptible to being destroyed by the OS whenever it
leaves the sight of the user. There are two main situations in which this can
occur. The first and most obvious case is when the user presses the home button
or switches to another application.</p>
+
+<p>However, there is a second (and much more subtle) case that certain plugins
can introduce. As noted above, Cordova applications are usually confined to the
single activity that contains the Webview. However, there are instances in
which other activities may be launched by plugins and temporarily push the
Cordova activity to the background. These other Activities are typically
launched in order to perform a specific task using a native application
installed on the device. For example, [...]
+
+<p>For a clearer understanding of this second case, let's walk through an
example using the camera plugin. Imagine you have an application that requires
the user to take a profile photo. The flow of events in the application when
everything goes as planned will look something like this:</p>
<ol>
<li>The user is interacting with your app and needs to take a picture</li>
@@ -2997,9 +2924,7 @@ goes as planned will look something like this:</p>
<li>The user is returned to your application where they left off</li>
</ol>
-<p>However, this flow of events can be disrupted if a device is low on memory.
If
-the Activity is killed by the OS, the above sequence of events instead plays
out
-as follows:</p>
+<p>However, this flow of events can be disrupted if a device is low on memory.
If the Activity is killed by the OS, the above sequence of events instead plays
out as follows:</p>
<ol>
<li>The user is interacting with your app and needs to take a picture</li>
@@ -3017,54 +2942,30 @@ as follows:</p>
<li>The user is confused as to why they are suddenly back at your app's
login screen</li>
</ol>
-<p>In this instance, the OS killed the application in the background and the
-application did not maintain its state as part of the lifecycle. When the user
-returned to the app, the Webview was recreated and the app appeared to have
-restarted from scratch (hence the user's confusion). This sequence of
events is
-equivalent to what happens when the home button is pressed or the user switches
-applications. The key to preventing the above experience is subscribing to
-events and properly maintaining state as part of the activity lifecycle.</p>
+<p>In this instance, the OS killed the application in the background and the
application did not maintain its state as part of the lifecycle. When the user
returned to the app, the Webview was recreated and the app appeared to have
restarted from scratch (hence the user's confusion). This sequence of
events is equivalent to what happens when the home button is pressed or the
user switches applications. The key to preventing the above experience is
subscribing to events and properly m [...]
<h3>Respecting the Lifecycle</h3>
-<p>In the examples above, the javascript events that are fired are noted in
-italics. These events are your opportunity to save and restore your
-application's state. You should register callbacks in your
application's
-<code>bindEvents</code> function that respond to the lifecycle events by
saving state. What
-information you save and how you save it is left to your discretion, but you
-should be sure to save enough information so that you can restore the user to
-exactly where they left off when they return to your application.</p>
-
-<p>There is one additional factor in the example above that only applies in the
-second-discussed situation (i.e. when a plugin launches an external activity).
-Not only was the state of the application lost when the user finished taking a
-photo, but so was the photo that the user took. Normally, that photo would be
-delivered to your application through the callback that was registered with the
-camera plugin. However, when the Webview was destroyed that callback was lost
-forever. Luckily, cordova-android 5.1.0 and above provide a means for getting
-the result of that plugin call when your application resumes.</p>
+<p>In the examples above, the javascript events that are fired are noted in
italics. These events are your opportunity to save and restore your
+application's state. You should register callbacks in your
application's <code>bindEvents</code> function that respond to the
lifecycle events by saving state. What information you save and how you save it
is left to your discretion, but you should be sure to save enough information
so that you can restore the user to exactly where they left off when they
return to your application.</p>
+
+<p>There is one additional factor in the example above that only applies in
the second-discussed situation (i.e. when a plugin launches an external
activity). Not only was the state of the application lost when the user
finished taking a photo, but so was the photo that the user took. Normally,
that photo would be delivered to your application through the callback that was
registered with the camera plugin. However, when the Webview was destroyed that
callback was lost forever. Luckily, [...]
<h3>Retrieving plugin callback results (cordova-android 5.1.0+)</h3>
-<p>When the OS destroys the Cordova activity that was pushed into the
background
-by a plugin, any pending callbacks are lost as well. This means that if you
-passed a callback to the plugin that launched the new activity (e.g. the camera
-plugin), that callback will NOT be fired when the application is recreated.
-However, starting in cordova-android <strong>5.1.0</strong>, the
<code>resume</code> event's payload will
-contain any pending plugin results from the plugin request that launched the
-external activity made prior to the activity being destroyed.</p>
+<p>When the OS destroys the Cordova activity that was pushed into the
background by a plugin, any pending callbacks are lost as well. This means that
if you passed a callback to the plugin that launched the new activity (e.g. the
camera plugin), that callback will NOT be fired when the application is
recreated. However, starting in cordova-android <strong>5.1.0</strong>, the
<code>resume</code> event's payload will contain any pending plugin results
from the plugin request that launc [...]
<p>The payload for the <code>resume</code> event adheres to the following
format:</p>
-<div class="language-text highlighter-rouge"><div class="highlight"><pre
class="highlight"><code>{
- action: "resume",
- pendingResult: {
- pluginServiceName: string,
- pluginStatus: string,
- result: any
- }
-}
-</code></pre></div></div>
+<div class="language-json highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="p">{</span><span class="w">
+ </span><span class="err">action:</span><span class="w"> </span><span
class="s2">"resume"</span><span class="p">,</span><span class="w">
+ </span><span class="err">pendingResult:</span><span class="w">
</span><span class="p">{</span><span class="w">
+ </span><span class="err">pluginServiceName:</span><span class="w">
</span><span class="err">string</span><span class="p">,</span><span class="w">
+ </span><span class="err">pluginStatus:</span><span class="w">
</span><span class="err">string</span><span class="p">,</span><span class="w">
+ </span><span class="err">result:</span><span class="w"> </span><span
class="err">any</span><span class="w">
+ </span><span class="p">}</span><span class="w">
+</span><span class="p">}</span><span class="w">
+</span></code></pre></div></div>
<p>The fields of that payload are defined as follows:</p>
@@ -3075,6 +2976,7 @@ external activity made prior to the activity being
destroyed.</p>
</ul>
<p>The possible values for <code>pluginStatus</code> in the
<code>pendingResult</code> field include the following:</p>
+
<ul>
<li><code>"OK"</code> - The plugin call was successful</li>
<li><code>"No Result"</code> - The plugin call ended with no result</li>
@@ -3092,18 +2994,11 @@ external activity made prior to the activity being
destroyed.</p>
</li>
</ul>
-<p>Please note that it is up to the plugin to decide what is contained in the
-<code>result</code> field and the meaning of the <code>pluginStatus</code>
that is returned. Reference
-the API of the plugin you are using to see what you should expect those fields
-to contain and how to use their values.</p>
+<p><em><strong>Note:</strong> It is up to the plugin to decide what is
contained in the <code>result</code> field and the meaning of the
<code>pluginStatus</code> that is returned. Refer to the plugin's API
documentationf or the expect results and how to use the values.</em></p>
<h4>Example</h4>
-<p>Below is a brief example application that uses the <code>resume</code> and
<code>pause</code> events
-to manage state. It uses the Apache camera plugin as an example of how to
-retrieve the results of a plugin call from the <code>resume</code> event
payload. The
-portion of the code dealing with the <code>resume</code>'s
<code>event.pendingResult</code> object
-requires cordova-android <strong>5.1.0+</strong></p>
+<p>Below is a brief example application that uses the <code>resume</code> and
<code>pause</code> events to manage state. It uses the Apache camera plugin as
an example of how to retrieve the results of a plugin call from the
<code>resume</code> event payload. The portion of the code dealing with the
<code>resume</code>'s <code>event.pendingResult</code> object requires
cordova-android <strong>5.1.0+</strong></p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="c1">// This state represents the state of
our application and will be saved and</span>
<span class="c1">// restored by onResume() and onPause()</span>
@@ -3227,12 +3122,15 @@ requires cordova-android <strong>5.1.0+</strong></p>
<span class="nt"></body></span>
<span class="nt"></html></span>
</code></pre></div></div>
+
<h3>Android Quirks</h3>
-<p>The default API level in the Cordova Android platform has been upgraded. On
an Android 9 device, clear text communication is now disabled by default.</p>
+
+<p>The default API level in the Cordova-Android platform has been upgraded. On
an Android 9 device, clear text communication is now disabled by default.</p>
<p>By default HTTP and FTP etc. will refuse the apps requests to use cleartext
traffic. The key reason for avoiding cleartext traffic is the lack of
confidentiality, authenticity, and protections against tampering; a network
attacker can eavesdrop on transmitted data and also modify it without being
detected. You can learn more about the
<code>android:usesCleartextTraffic</code> or any other android application
elements setting in the <a href="https://developer.android.com/guide/topics/m
[...]
<p>To allow clear text communication again, set the
<code>android:usesCleartextTraffic</code> on your application tag to true in
<code>config.xml</code> file:</p>
+
<div class="language-xml highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="nt"><platform</span> <span
class="na">name=</span><span class="s">"android"</span><span
class="nt">></span>
<span class="nt"><edit-config</span> <span class="na">file=</span><span
class="s">"app/src/main/AndroidManifest.xml"</span> <span
class="na">mode=</span><span class="s">"merge"</span> <span
class="na">target=</span><span class="s">"/manifest/application"</span><span
class="nt">></span>
<span class="nt"><application</span> <span
class="na">android:usesCleartextTraffic=</span><span class="s">"true"</span>
<span class="nt">/></span>
@@ -3240,9 +3138,13 @@ requires cordova-android <strong>5.1.0+</strong></p>
<span class="nt"></platform></span>
</code></pre></div></div>
-<p>And also you need to add Android XML namespace
<code>xmlns:android="http://schemas.android.com/apk/res/android";</code> to your
widget tag in the same <code>config.xml</code>, like so:
-<code><widget id="io.cordova.hellocordova" version="0.0.1"
android-versionCode="13" xmlns="http://www.w3.org/ns/widgets";
xmlns:cdv="http://cordova.apache.org/ns/1.0";
xmlns:android="http://schemas.android.com/apk/res/android">
-</widget></code></p>
+<p>And also you need to add Android XML namespace
<code>xmlns:android="http://schemas.android.com/apk/res/android";</code> to your
widget tag in the same <code>config.xml</code>.</p>
+
+<p><strong>Example:</strong></p>
+
+<div class="language-xml highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="nt"><widget</span> <span
class="na">id=</span><span class="s">"io.cordova.hellocordova"</span> <span
class="na">version=</span><span class="s">"0.0.1"</span> <span
class="na">android-versionCode=</span><span class="s">"13"</span> <span
class="na">xmlns=</span><span class="s">"http://www.w3.org/ns/widgets";</span>
<span class="na">xmlns:cdv=</span><span class="s">"http://cordova. [...]
+<span class="nt"></widget></span>
+</code></pre></div></div>
<h3>Android Manifest Information</h3>
@@ -3250,11 +3152,7 @@ requires cordova-android <strong>5.1.0+</strong></p>
<h3>Testing the Activity Lifecycle</h3>
-<p>Android provides a developer setting for testing Activity destruction on low
-memory. Enable the "Don't keep activities" setting in the
Developer Options menu
-on your device or emulator to simulate low memory scenarios. You should always
-do some amount of testing with this setting enabled to make sure that your
-application is properly maintaining state.</p>
+<p>Android provides a developer setting for testing Activity destruction on
low memory. Enable the "Don't keep activities" setting in the
Developer Options menu on your device or emulator to simulate low memory
scenarios. You should always do some amount of testing with this setting
enabled to make sure that your application is properly maintaining state.</p>
diff --git a/docs/en/dev/guide/platforms/android/index.html
b/docs/en/dev/guide/platforms/android/index.html
index 3a9898b54..cc46d373e 100644
--- a/docs/en/dev/guide/platforms/android/index.html
+++ b/docs/en/dev/guide/platforms/android/index.html
@@ -2278,23 +2278,13 @@
<div id="page-toc-source">
<h1>Android Platform Guide</h1>
-<p>This guide shows how to set up your SDK environment to deploy Cordova
-apps for Android devices, and how to optionally use Android-centered
-command-line tools in your development workflow. You need to install
-the Android SDK regardless of whether you want to use these
-platform-centered shell tools or cross-platform Cordova CLI for
-development. For a comparison of the two development paths, see the
-<a href="../../overview/index.html#development-paths">Overview</a>. For
details on
-the CLI, see <a href="../../../reference/cordova-cli/index.html">Cordova CLI
Reference</a>.</p>
-
-<h2>Requirements and Support</h2>
-
-<p>Cordova for Android requires the Android SDK which can be installed
-on OS X, Linux or Windows. See the Android SDK's
-<a href="http://developer.android.com/sdk/index.html#Requirements";>System
Requirements</a>.
-Cordova's latest Android package supports up to Android <a
href="https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels";>API
Level</a> 30.
-The supported Android API Levels and Android Versions for the past
-few cordova-android releases can be found in this table:</p>
+<p>This guide will help set up your development environment for building
Cordova apps for Android devices and optionally use Android-specific
command-line tools within your development workflow.</p>
+
+<p>You will need to install and set up the requirements regardless of whether
you want to use the Android-specific command-line tools or Cordova CLI
commands.</p>
+
+<h2>Android API Level Support</h2>
+
+<p>The supported <a
href="https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels";>Android
API Levels</a> (versions of Android) corresponding with the Cordova-Android
released versions are listed in the table below:</p>
<table>
<thead>
@@ -2305,6 +2295,11 @@ few cordova-android releases can be found in this
table:</p>
</tr>
</thead>
<tbody>
+ <tr>
+ <td>11.X.X</td>
+ <td>22 - 32</td>
+ <td>5.1 - 12.0.0 (L)</td>
+ </tr>
<tr>
<td>10.X.X</td>
<td>22 - 30</td>
@@ -2353,93 +2348,103 @@ few cordova-android releases can be found in this
table:</p>
</tbody>
</table>
-<p>Please note that the versions listed here are for Cordova's Android
package,
-<a href="https://github.com/apache/cordova-android";>cordova-android</a>, and
not for the
-Cordova CLI. To determine what version of Cordova's Android package is
installed
-in your Cordova project, run the command <code>cordova platform ls</code> in
the directory
-that holds your project.</p>
+<p><em><strong>Note:</strong> The <a
href="https://github.com/apache/cordova-android";>cordova-android</a> versions
listed above are not for the Cordova CLI.</em></p>
+
+<p>To determine what version of the Cordova-Android package is installed in
your Cordova project, run the command <code>cordova platform ls</code> in your
project's root directory.</p>
+
+<p>As a general rule, Android versions become unsupported by Cordova as they
dip below 5% on Google's <a
href="https://developer.android.com/about/dashboards/index.html";>distribution
dashboard</a>.</p>
+
+<h2>System Requirements</h2>
+
+<p>Cordova-Android requires the Android SDK, which can be installed on either
macOS, Linux, or Windows.</p>
-<p>As a general rule, Android versions become unsupported by Cordova as
-they dip below 5% on Google's
-<a
href="http://developer.android.com/about/dashboards/index.html";>distribution
dashboard</a>.</p>
+<p>For the base system requirements, see the Android Studio's <a
href="https://developer.android.com/studio#Requirements";>System
Requirements</a>.</p>
-<h2>Installing the Requirements</h2>
+<h2>The Required Software & Tools</h2>
<h3>Java Development Kit (JDK)</h3>
-<p>Install <a
href="https://www.oracle.com/java/technologies/javase/javase-jdk8-downloads.html";>Java
Development Kit (JDK) 8</a>
-or you can install <a
href="https://www.oracle.com/java/technologies/javase-jdk11-downloads.html";>Java
Development Kit (JDK) 11</a>
-if using <code>cordova-android</code> version 10+.</p>
+<p>If you are using <code>cordova-android</code> 10.0.0 or greater, install
the <a
href="https://www.oracle.com/java/technologies/javase-jdk11-downloads.html";>Java
Development Kit (JDK) 11</a>.</p>
-<p>When installing on Windows you also need to set <code>JAVA_HOME</code>
Environment Variable
-according to your JDK installation path (see <a
href="#setting-environment-variables">Setting Environment Variables</a>)</p>
+<p>If you are using any version below <code>cordova-android</code> 10.0.0,
install the <a
href="https://www.oracle.com/java/technologies/javase/javase-jdk8-downloads.html";>Java
Development Kit (JDK) 8</a>.</p>
+
+<p>The <code>JAVA_HOME</code> environment variable must be set according to
your JDK installation path when installing on a Windows environment. See the <a
href="#setting-environment-variables">Setting Environment Variables</a> section
on how to set up environment variables.</p>
<h3>Gradle</h3>
-<p>As of Cordova-Android 6.4.0, <a
href="https://gradle.org/install/";>Gradle</a> is now required to be installed
to build Android.</p>
+<p>As of Cordova-Android 6.4.0, <a
href="https://gradle.org/install/";>Gradle</a> is required to be installed.</p>
+
+<p>When installing on Windows, you need to add the path to the Gradle's
binary directory to your <code>path</code> environment variable. See <a
href="#setting-environment-variables">Setting Environment Variables</a>) on how
to configure system environment variables.</p>
-<p>When installing on Windows, you need to add Gradle to your path, (see <a
href="#setting-environment-variables">Setting Environment Variables</a>)</p>
+<p><em><strong>Note:</strong> This is the system's Gradle version. The
system's Gradle binary will create the Gradle Wrapper file that declares
and obtains the appropriate version of Gradle needed for building the Android
application. The system-level and project-level version of Gradle may not and
does not need to match. The project-level's version of Gradle is defined in
the Cordova-Android's package and set based on what Android
supports.</em></p>
-<h3>Android SDK</h3>
+<h3>Android Studio</h3>
-<p>Install <a href="https://developer.android.com/studio/index.html";>Android
Studio</a>. Follow the instructions at the linked Android Developer site to get
started.
-Opening Android Studio for the first time will guide you through the process
of installing the Android SDK.</p>
+<p>Download and install <a
href="https://developer.android.com/studio/index.html";>Android Studio</a>.
Follow the instructions at the linked Android Developer site to get started.</p>
+
+<p>Opening Android Studio for the first time will guide you through the
process of installing the Android SDK packages.</p>
<h4>Adding SDK Packages</h4>
-<p>After installing the Android SDK, you must also install the packages for
-whatever <a
href="http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels";>API
level</a>
-you wish to target. It is recommended that you install the highest SDK version
-that your version of cordova-android supports (see <a
href="#requirements-and-support">Requirements and Support</a>).</p>
+<p>It is recommended to install the highest supported version of the SDK
Platform and Build Tools based on the project's installed version of
Cordova-Android. Please see the <a href="#android-api-level-support">Android
API Level Support</a> to find the supported version based on the
Cordova-Android versions.</p>
-<p>Open the Android SDK Manager (<code>Tools > SDK Manager</code> in
Android Studio, or <code>sdkmanager</code> on the command line),
-and make sure the following are installed:</p>
+<p>In the Android Studio, open the <strong>SDK Manager</strong> (<code>Tools
> SDK Manager</code>) and confirm that the following are installed for the
targeted version of Android.:</p>
-<ol>
- <li>Android Platform SDK for your targeted version of Android</li>
- <li>Android SDK build-tools version 29.0.2 or higher</li>
-</ol>
+<ul>
+ <li>Android's <strong>SDK Platform</strong> for your targeted API
Level</li>
+ <li><strong>Android SDK Build-Tools</strong> under the <strong>SDK
Tools</strong> tab, for the targeted version.</li>
+</ul>
+
+<h4>Android SDK Tools</h4>
-<h4>Android SDK Tools:</h4>
-<p>In Android Studio 3.6 or later, you need to manually add the old version of
the Android SDK Tools. To do this:</p>
+<p>In Android Studio 3.6 or later, the obsolete Android SDK Tools will need to
be intalled. To do this:</p>
<ol>
- <li>Open the Android Studio <strong>SDK Manager</strong></li>
- <li>In the Android <strong>SDK Tools</strong> tab, uncheck <code>Hide
Obsolete Packages</code></li>
+ <li>Open the Android Studio</li>
+ <li>Open the <strong>SDK Manager</strong> (<code>Tools > SDK
Manager</code>)</li>
+ <li>Navigate to the <strong>SDK Tools</strong> tab</li>
+ <li>Uncheck <code>Hide Obsolete Packages</code></li>
<li>Check <code>Android SDK Tools (Obsolete)</code></li>
</ol>
-<p>See Android's documentation on <a
href="https://developer.android.com/studio/intro/update";>Installing SDK
Packages</a>
-for more details.</p>
+<p>See Android's documentation on how to <a
href="https://developer.android.com/studio/intro/update#sdk-manager";>Update
your tools with the SDK Manager</a> for more details.</p>
<h3>Setting environment variables</h3>
-<p>Cordova's CLI tools require some environment variables to be set in
order to
-function correctly. The CLI will attempt to set these variables for you, but
-in certain cases you may need to set them manually. The following variables
-should be updated:</p>
+<p>Cordova's CLI requires specific environment variables so it can
function correctly. If the environment variables are missing, the CLI will
attempt to resolve the variable temporarily. If the missing variables fail to
resolve, they must be set manually.</p>
-<ol>
- <li>Set the <code>JAVA_HOME</code> environment variable to the location of
your JDK
-installation</li>
- <li>Set the <code>ANDROID_SDK_ROOT</code> environment variable to the
location of your Android
-SDK installation</li>
- <li>It is also recommended that you add the Android SDK's
<code>cmdline-tools/latest/bin</code>, <code>emulator</code>
-and <code>platform-tools</code> directories to your <code>PATH</code></li>
- <li>For apksigner and zipalign, the Android SDK's
<code>build-tools</code> must also be added to your <code>PATH</code></li>
-</ol>
+<p>The following variables must be set:</p>
+
+<ul>
+ <li><code>JAVA_HOME</code> - The environment variable to the location of
your JDK installation</li>
+ <li><code>ANDROID_SDK_ROOT</code> - The environment variable to the location
of your Android SDK installation</li>
+</ul>
+
+<p>It is also recommended to update the <code>PATH</code> environment variable
to include the following directories.</p>
+
+<ul>
+ <li><code>cmdline-tools/latest/bin</code></li>
+ <li><code>emulator</code></li>
+ <li><code>platform-tools</code></li>
+ <li><code>build-tools</code>
+ <ul>
+ <li>This is required for the <code>apksigner</code> and
<code>zipalign</code> tools.</li>
+ </ul>
+ </li>
+</ul>
-<h4>OS X and Linux</h4>
+<p><em><strong>Note:</strong> The directories above are generally located in
the Android SDK ROOT.</em></p>
-<p>On a Mac or Linux, you can use a text editor to create or modify the
-<code>~/.bash_profile</code> file. To set an environment variable, add a line
that uses
-<code>export</code> like so (substitute the path with your local
installation):</p>
+<h4>macOS and Linux</h4>
+
+<p>On a Mac or Linux, with a text editor, create or modify the
<code>~/.bash_profile</code> file.</p>
+
+<p>To set an environment variable, add a line that uses <code>export</code>
like so (substitute the path with your local installation):</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="nb">export </span><span
class="nv">ANDROID_SDK_ROOT</span><span
class="o">=</span>/Development/android-sdk/
</code></pre></div></div>
-<p>To update your <code>PATH</code>, add a line resembling the following
(substitute the paths
-with your local Android SDK installation's location):</p>
+<p>To update your <code>PATH</code>, add a line resembling the following
(substitute the paths with your local Android SDK installation's
location):</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="nb">export </span><span
class="nv">PATH</span><span class="o">=</span><span
class="nv">$PATH</span>:<span
class="nv">$ANDROID_SDK_ROOT</span>/platform-tools/
<span class="nb">export </span><span class="nv">PATH</span><span
class="o">=</span><span class="nv">$PATH</span>:<span
class="nv">$ANDROID_SDK_ROOT</span>/cmdline-tools/latest/bin/
@@ -2448,78 +2453,77 @@ with your local Android SDK installation's
location):</p>
<p>Reload your terminal to see this change reflected or run the following
command:</p>
-<div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="nv">$ </span><span
class="nb">source</span> ~/.bash_profile
+<div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="nb">source</span> ~/.bash_profile
</code></pre></div></div>
<h4>Windows</h4>
-<p>These steps may vary depending on your installed version of Windows. Close
and
-reopen any command prompt windows after making changes to see them
reflected.</p>
+<p>These steps may vary depending on your installed version of Windows. Close
and reopen any command prompt windows after making changes to see them
reflected.</p>
<ol>
- <li>
- <p>Click on the <strong>Start</strong> menu in the lower-left corner of
the desktop</p>
- </li>
- <li>
- <p>In the search bar, search for <strong>Environment Variables</strong>
and select <strong>Edit the
-system Environment Variables</strong> from the options that appear</p>
- </li>
- <li>
- <p>In the window that appears, click the <strong>Environment
Variables</strong> button</p>
- </li>
+ <li>Click on the <strong>Start</strong> menu or Press on the
<strong>Windows</strong> Key (<strong>Win</strong>)</li>
+ <li>Type in the search bar <code>Environment Variables</code></li>
+ <li>Select <strong>Edit the system environment variables</strong>
options</li>
+ <li>Click on the <strong>Environment Variables…</strong> button in the
window that appears.</li>
</ol>
-<h5>To create a new environment variable:</h5>
+<h5>To create a new environment variable</h5>
<ol>
- <li>Click <strong>New…</strong> and enter the variable name and
value</li>
+ <li>Click on the <strong>New…</strong> button</li>
+ <li>Type in the <strong>Variable name</strong></li>
+ <li>Type in the <strong>Variable value</strong></li>
+ <li>Click on the <strong>OK</strong> button</li>
</ol>
-<h5>To set your <strong>PATH</strong>:</h5>
+<h5>To set your PATH</h5>
<ol>
- <li>
- <p>Select the <strong>PATH</strong> variable and press
<strong>Edit</strong>.</p>
- </li>
- <li>
- <p>Add entries for the relevant locations to the <strong>PATH</strong>.
For example
-(substitute the paths with your local Android SDK installation's
location):</p>
-
- <div class="language-plaintext highlighter-rouge"><div
class="highlight"><pre class="highlight"><code> C:\Users\[your
user]\AppData\Local\Android\Sdk\platform-tools
- C:\Users\[your user]\AppData\Local\Android\Sdk\cmdline-tools\latest\bin
- C:\Users\[your user]\AppData\Local\Android\Sdk\tools\emulator
-</code></pre></div> </div>
- </li>
+ <li>Select <strong>PATH</strong> from the liste of already defined
variable</li>
+ <li>Click on the <strong>Edit…</strong> button</li>
+ <li>Click on the <strong>New</strong> button</li>
+ <li>Type in the relevant location.</li>
</ol>
+<p>Repeat step 3 and 4 until all paths are added.</p>
+
+<p>Example paths (substitute the paths with your local Android SDK
installation's location):</p>
+
+<pre><code class="language-txt">C:\Users\[your
user]\AppData\Local\Android\Sdk\platform-tools
+C:\Users\[your user]\AppData\Local\Android\Sdk\cmdline-tools\latest\bin
+C:\Users\[your user]\AppData\Local\Android\Sdk\tools\emulator
+</code></pre>
+
+<p>Once all paths are added, click the <strong>OK</strong> button until all
opened windows for setting & editing environment variables are closed.</p>
+
<h2>Project Configuration</h2>
<h3>Setting up an Emulator</h3>
-<p>If you wish to run your Cordova app on an Android emulator, you will first
need
-to create an Android Virtual Device (AVD). See the Android documentation for
-<a href="https://developer.android.com/studio/run/managing-avds.html";>managing
AVDs</a>,
-<a
href="https://developer.android.com/studio/run/emulator.html#about";>configuring
the emulator</a>,
-and <a
href="https://developer.android.com/studio/run/emulator-acceleration.html";>setting
up hardware acceleration</a>.</p>
+<p>If you wish to run your Cordova app on an Android emulator, you will first
need to create an Android Virtual Device (AVD).</p>
+
+<p>See the following Android documentation for more details on:</p>
-<p>Once your AVD is configured correctly, you should be able to deploy your
Cordova
-application to the emulator by running:</p>
+<ul>
+ <li><a
href="https://developer.android.com/studio/run/managing-avds.html";>Create and
manage virtual devices</a></li>
+ <li><a
href="https://developer.android.com/studio/run/emulator.html#about";>Run apps on
the Android Emulator</a></li>
+ <li><a
href="https://developer.android.com/studio/run/emulator-acceleration.html";>Configure
hardware acceleration for the Android Emulator</a>.</li>
+</ul>
-<div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="nv">$ </span>cordova run <span
class="nt">--emulator</span>
+<p>Once your AVD is configured correctly, you should be able to deploy your
Cordova application to the emulator by running the following command:</p>
+
+<div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code>cordova run <span class="nt">--emulator</span>
</code></pre></div></div>
<h3>Configuring Gradle</h3>
-<p>As of <strong>cordova-android@4.0.0</strong>, Cordova for Android projects
are built using
-<a href="http://www.gradle.org/";>Gradle</a>. For instructions on building with
Ant, refer
-to older versions of the documentation. Please note that Ant builds are
-deprecated as of the Android SDK Tools 25.3.0.</p>
+<p>Cordova-Android projects are built by using <a
href="https://gradle.org/";>Gradle</a>.</p>
<h4>Setting Gradle Properties</h4>
-<p>It is possible to configure the Gradle build by setting the values of
certain
-<a
href="https://docs.gradle.org/current/userguide/build_environment.html";>Gradle
properties</a>
-that Cordova exposes. The following properties are available to be set:</p>
+<p>It is possible to configure the Gradle build by setting the values of
certain <a
href="https://docs.gradle.org/current/userguide/build_environment.html";>Gradle
properties</a> that Cordova exposes.</p>
+
+<p>The following properties are available:</p>
<table>
<thead>
@@ -2529,87 +2533,106 @@ that Cordova exposes. The following properties are
available to be set:</p>
</tr>
</thead>
<tbody>
+ <tr>
+ <td><code>cdvAndroidXAppCompatVersion</code></td>
+ <td>Sets the version of the <code>androidx.appcompat:appcompat</code>
library.</td>
+ </tr>
+ <tr>
+ <td><code>cdvAndroidXWebKitVersion</code></td>
+ <td>Sets the version of the <code>androidx.webkit:webkit</code>
library.</td>
+ </tr>
+ <tr>
+ <td><code>cdvBuildArch</code></td>
+ <td>Overrides the build architecture of which the app is built for. The
default value is automatically detected by Cordova's build script.</td>
+ </tr>
<tr>
<td><code>cdvBuildMultipleApks</code></td>
<td>If this is set, then multiple APK files will be generated: One per
native platform supported by library projects (x86, ARM, etc). This can be
important if your project uses large native libraries, which can drastically
increase the size of the generated APK. If not set, then a single APK will be
generated which can be used on all devices</td>
</tr>
<tr>
- <td><code>cdvVersionCode</code></td>
- <td>Overrides the versionCode set in
<code>AndroidManifest.xml</code></td>
+ <td><code>cdvBuildToolsVersion</code></td>
+ <td>Overrides the automatically detected
<code>android.buildToolsVersion</code> value</td>
</tr>
<tr>
- <td><code>cdvReleaseSigningPropertiesFile</code></td>
- <td><em>Default: <code>release-signing.properties</code></em><br />Path
to a .properties file that contains signing information for release builds (see
<a href="#signing-an-app">Signing an App</a>)</td>
+ <td><code>cdvCompileSdkVersion</code></td>
+ <td>Sets the SDK version of the framework which the app is been compiled
for. Setting will override the automatic detection of the
<code>android.compileSdkVersion</code> value.</td>
</tr>
<tr>
<td><code>cdvDebugSigningPropertiesFile</code></td>
<td><em>Default: <code>debug-signing.properties</code></em><br />Path to
a .properties file that contains signing information for debug builds (see <a
href="#signing-an-app">Signing an App</a>). Useful when you need to share a
signing key with other developers</td>
</tr>
+ <tr>
+ <td><code>cdvMaxSdkVersion</code></td>
+ <td>set the maximum API Level which the application can run on</td>
+ </tr>
<tr>
<td><code>cdvMinSdkVersion</code></td>
<td>Overrides the value of <code>minSdkVersion</code> set in
<code>AndroidManifest.xml</code>. Useful when creating multiple APKs based on
SDK version</td>
</tr>
<tr>
- <td><code>cdvBuildToolsVersion</code></td>
- <td>Overrides the automatically detected
<code>android.buildToolsVersion</code> value</td>
+ <td><code>cdvReleaseSigningPropertiesFile</code></td>
+ <td><em>Default: <code>release-signing.properties</code></em><br />Path
to a .properties file that contains signing information for release builds (see
<a href="#signing-an-app">Signing an App</a>)</td>
</tr>
<tr>
- <td><code>cdvCompileSdkVersion</code></td>
- <td>Overrides the automatically detected
<code>android.compileSdkVersion</code> value</td>
+ <td><code>cdvSdkVersion</code></td>
+ <td>Overrides the <code>targetSdkVersion</code> value.</td>
+ </tr>
+ <tr>
+ <td><code>cdvVersionCode</code></td>
+ <td>Overrides the versionCode set in
<code>AndroidManifest.xml</code></td>
+ </tr>
+ <tr>
+ <td><code>cdvVersionCodeForceAbiDigit</code></td>
+ <td>Whether to append a 0 "abi digit" to versionCode when only
a single APK is build.</td>
</tr>
</tbody>
</table>
<p>You can set these properties in one of four ways:</p>
-<ol>
+<ul>
<li>
- <p>By setting environment variables like so:</p>
+ <p>Using an Environment Variables:</p>
+
+ <p><strong>Example:</strong></p>
- <div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code> <span class="nv">$ </span><span class="nb">export
</span><span class="nv">ORG_GRADLE_PROJECT_cdvMinSdkVersion</span><span
class="o">=</span>20
- <span class="nv">$ </span>cordova build android
+ <div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code> <span class="nb">export </span><span
class="nv">ORG_GRADLE_PROJECT_cdvMinSdkVersion</span><span class="o">=</span>20
+ cordova build android
</code></pre></div> </div>
</li>
<li>
- <p>By using the <code>--gradleArg</code> flag in your Cordova
<code>build</code> or <code>run</code> commands:</p>
+ <p>Using the <code>--gradleArg</code> flag with the Cordova
<code>build</code> or <code>run</code> command:</p>
- <div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code> <span class="nv">$ </span>cordova run android <span
class="nt">--</span> <span class="nt">--gradleArg</span><span
class="o">=</span><span class="nt">-PcdvMinSdkVersion</span><span
class="o">=</span>20
+ <p><strong>Example:</strong></p>
+
+ <div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code> cordova run android <span class="nt">--</span> <span
class="nt">--gradleArg</span><span class="o">=</span><span
class="nt">-PcdvMinSdkVersion</span><span class="o">=</span>20
</code></pre></div> </div>
</li>
<li>
- <p>By placing a file called <code>gradle.properties</code> in your Android
platform
- folder (<code><your-project>/platforms/android</code>) and setting the
properties in it
- like so:</p>
+ <p>Creating a <code>gradle.properties</code> in the project's Android
platform directory</p>
+
+ <p>Create a file named <code>gradle.properties</code> in the directory
<code><project-root>/platforms/android</code> with the contents such
as:</p>
- <div class="language-plaintext highlighter-rouge"><div
class="highlight"><pre class="highlight"><code> # In
<your-project>/platforms/android/app/gradle.properties
- cdvMinSdkVersion=20
+ <p><strong>Example File Contents:</strong></p>
+
+ <div class="language-groovy highlighter-rouge"><div class="highlight"><pre
class="highlight"><code> <span class="n">cdvMinSdkVersion</span><span
class="o">=</span><span class="mi">20</span>
</code></pre></div> </div>
</li>
<li>
- <p>By extending <code>build.gradle</code> via a <a
href="#extending-buildgradle"><code>build-extras.gradle</code> file</a>
- and setting the property like so:</p>
+ <p><a href="#extending-buildgradle">Extending
<code>build.gradle</code></a> with the `build-extras.gradle file</p>
+
+ <p>Create a file named <code>build-extras.gradle</code> in the directory
<code><project-root>/platforms/android/app</code> with the contents such
as:</p>
- <div class="language-groovy highlighter-rouge"><div class="highlight"><pre
class="highlight"><code> <span class="c1">// In
<your-project>/platforms/android/app/build-extras.gradle</span>
- <span class="n">ext</span><span class="o">.</span><span
class="na">cdvMinSdkVersion</span> <span class="o">=</span> <span
class="mi">20</span>
+ <div class="language-groovy highlighter-rouge"><div class="highlight"><pre
class="highlight"><code> <span class="n">ext</span><span
class="o">.</span><span class="na">cdvMinSdkVersion</span> <span
class="o">=</span> <span class="mi">20</span>
</code></pre></div> </div>
</li>
-</ol>
+</ul>
-<p>The latter two options both involve including an extra file in your Android
-platform folder. In general, it is discouraged that you edit the contents of
-this folder because it is easy for those changes to be lost or overwritten.
-Instead, these two files should be copied from another location into that
folder
-as part of the build command by using the <code>before_build</code>
-<a href="../../appdev/hooks/index.html">hook</a>.</p>
+<p>The latter two options both involve including an extra file in your Android
platform folder. In general, it is discouraged to edit the contents of this
folder because it is easy for those changes to be lost or overwritten. Instead,
these files should be copied into the folder as part of the build command by
using the <code>before_build</code> <a
href="../../appdev/hooks/index.html">hook script</a>.</p>
<h4>Extending build.gradle</h4>
-<p>If you need to customize <code>build.gradle</code>, rather than edit it
directly, you
-should create a sibling file named <code>build-extras.gradle</code>. This file
will be
-included by the main <code>build.gradle</code> when present. This file must be
placed in
-the <code>app</code> folder of the Android platform directory
(<code><your-project>/platforms/android/app</code>),
-so it is recommended that you copy it over via a script attached to the
-<code>before_build</code> <a href="../../appdev/hooks/index.html">hook</a>.</p>
+<p>If you need to customize the <code>build.gradle</code> file, rather than
edit it directly, it is recommended to create a sibling file named
<code>build-extras.gradle</code>. This file will be included by the main
<code>build.gradle</code> script when present. This file must be placed in the
<code>app</code> folder of the Android's platform directory
(<code><your-project>/platforms/android/app</code>). It is recommended to
use the <code>before_build</code> <a href="../../appd [...]
<p>Here's an example:</p>
@@ -2644,9 +2667,9 @@ so it is recommended that you copy it over via a script
attached to the
<h4>Configuring Gradle JVM Args</h4>
-<p>To change the Gradle JVM args, the <code>--jvmargs</code> flag can be used
with both cordova build and run commands. This is mostly useful for controlling
how much memory gradle is allowed to use during the build process. It is
recommended to allow at least 2048 MB.</p>
+<p>To change the Gradle JVM args, the <code>--jvmargs</code> flag can be used
with both Cordova's <code>build</code> and <code>run</code> commands. This
is mostly useful for controlling how much memory gradle is allowed to use
during the build process. It is recommended to allow at least 2048 MB.</p>
-<p>By default, JVM args has a value of <code>-Xmx2048m</code>. To increase the
max allowed memory, use the <code>-Xmx</code> JVM arg. Example given below:</p>
+<p>By default, JVM args has a value of <code>-Xmx2048m</code>. To increase the
maximum allowed memory, use the <code>-Xmx</code> JVM arg. Example given
below:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre
class="highlight"><code>cordova build android -- --jvmargs='-Xmx4g'
</code></pre></div></div>
@@ -2682,35 +2705,23 @@ so it is recommended that you copy it over via a script
attached to the
<h3>Setting the Version Code</h3>
-<p>To change the <a
href="https://developer.android.com/studio/publish/versioning.html";>version
code</a>
-for your app's generated apk, set the <code>android-versionCode</code>
attribute in the widget
-element of your application's <a
href="../../../config_ref/index.html">config.xml file</a>.
-If the <code>android-versionCode</code> is not set, the version code will be
determined
-using the <code>version</code> attribute. For example, if the version is
<code>MAJOR.MINOR.PATCH</code>:</p>
+<p>To change the <a
href="https://developer.android.com/studio/publish/versioning";>version code</a>
for your app's generated apk, set the <code>android-versionCode</code>
attribute in the <code>widget</code> element of your application's <a
href="../../../config_ref/index.html">config.xml</a> file.</p>
-<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre
class="highlight"><code>versionCode = MAJOR * 10000 + MINOR * 100 + PATCH
+<p>If the <code>android-versionCode</code> is not set, the version code will
be determined using the <code>version</code> attribute. For example, if the
version is <code>MAJOR.MINOR.PATCH</code>:</p>
+
+<div class="language-groovy highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="n">versionCode</span> <span
class="o">=</span> <span class="n">MAJOR</span> <span class="o">*</span> <span
class="mi">10000</span> <span class="o">+</span> <span class="n">MINOR</span>
<span class="o">*</span> <span class="mi">100</span> <span class="o">+</span>
<span class="n">PATCH</span>
</code></pre></div></div>
-<p>If your application has enabled the <code>cdvBuildMultipleApks</code>
Gradle property (see
-<a href="#setting-gradle-properties">Setting Gradle Properties</a>), the
version code of
-your app will also be multiplied by 10 so that the last digit of the code can
be
-used to indicate the architecture the apk was built for. This multiplication
-will happen regardless of whether the version code is taken from the
-<code>android-versionCode</code> attribute or generated using the
<code>version</code>. Be aware that
-some plugins added to your project (including cordova-plugin-crosswalk-webview)
-may set this Gradle property automatically.</p>
-
-<p><strong>Please Note:</strong> When updating the
<code>android-versionCode</code> property, it is unwise
-to increment the version code taken from built apks. Instead, you should
-increment the code based off the value in your <code>config.xml</code>
file's
-<code>android-versionCode</code> attribute. This is because the
<code>cdvBuildMultipleApks</code>
-property causes the version code to be multiplied by 10 in the built apks and
-thus using that value will cause your next version code to be 100 times the
-original, etc.</p>
+<p>If your application has enabled the <code>cdvBuildMultipleApks</code>
Gradle property (see <a href="#setting-gradle-properties">Setting Gradle
Properties</a>), the version code of your app will also be multiplied by 10 so
that the last digit of the code can be used to indicate the architecture the
apk was built for. This multiplication
+will happen regardless of whether the version code is taken from the
<code>android-versionCode</code> attribute or generated using the
<code>version</code>.</p>
+
+<p><em><strong>Note:</strong> Be aware that some plugins added to your project
may set this Gradle property automatically.</em></p>
+
+<p><em><strong>Note:</strong> When updating the
<code>android-versionCode</code> property, it is not recommended to increment
the version code taken from built apks. It is recommended to increment the code
based off the value in your <code>config.xml</code> file's
<code>android-versionCode</code> attribute. This is because the
<code>cdvBuildMultipleApks</code> property causes the version code to be
multiplied by 10 in the built apks and thus using that value will cause your
next vers [...]
<h2>Signing an App</h2>
-<p>First, you should read the <a
href="https://developer.android.com/studio/publish/app-signing.html";>Android
app signing requirements</a>.</p>
+<p>It is recommended to read Android's documentation for <a
href="https://developer.android.com/studio/publish/app-signing";>Sign your
app</a> first, as it contains the necessary steps in creating required files
for signing.</p>
<h3>Using Flags</h3>
@@ -2753,23 +2764,26 @@ original, etc.</p>
<tr>
<td>Package Type</td>
<td><code>--packageType</code></td>
- <td><em>Default: apk</em><br />Specify whether to build an APK or an
[Android App Bundle] (https://developer.android.com/guide/app-bundle) (.aab)
file.<br />Accepts either <code>apk</code> or <code>bundle</code></td>
+ <td><em>Default: apk</em><br />Specify whether to build an APK or an <a
href="https://developer.android.com/guide/app-bundle";>AAB</a> (Android App
Bundle) file.<br />Acceptable Values: <code>apk</code> or
<code>bundle</code></td>
</tr>
</tbody>
</table>
-<p>These parameters can be specified using the command line arguments above to
-the <a href="../../../reference/cordova-cli/index.html">Cordova CLI</a>
<code>build</code> or <code>run</code> commands.</p>
+<p>The parameters above can be specified as an argument when using the <a
href="../../../reference/cordova-cli/index.html">Cordova CLI</a>
<code>build</code> or <code>run</code> commands.</p>
+
+<p><em><strong>Note</strong>: You should use double <code>--</code> to
indicate that these are platform-specific arguments.</em></p>
-<p><strong>Note</strong>: You should use double <code>--</code> to indicate
that these are platform-specific arguments, for example:</p>
+<p>Example:</p>
<p><code>cordova run android --release --
--keystore=../my-release-key.keystore --storePassword=password
--alias=alias_name --password=password --packageType=bundle</code>.</p>
-<h3>Using build.json</h3>
+<h3>Using <code>build.json</code></h3>
-<p>Alternatively, you could specify them in a build configuration file
(<code>build.json</code>)
-using the <code>--buildConfig</code> argument to the same commands. Here's
a sample of a
-build configuration file:</p>
+<p>Alternatively, you could specify the signing parameters in a build
configuration file (<code>build.json</code>).</p>
+
+<p>By default, if the <code>build.json</code> file exists in the project's
root directory, it will automatically be detected and used. If the file is not
located in the project's root directory or has multiple configuration
files, the command line argument <code>--buildConfig</code> must be supplied
with the path to the file.</p>
+
+<p><strong>Example <code>build.json</code> configuration file:</strong></p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nl">"android"</span><span class="p">:</span><span
class="w"> </span><span class="p">{</span><span class="w">
@@ -2793,131 +2807,73 @@ build configuration file:</p>
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
-<p>There is also support to mix and match command line arguments and
parameters in
-<code>build.json</code>. Values from the command line arguments will get
precedence.
-This can be useful for specifying passwords on the command line.</p>
+<p>There is also support to mix and match command line arguments and
parameters in <code>build.json</code>. Values from the command line arguments
takes precedence. This can be useful for specifying passwords on the command
line.</p>
<h3>Using Gradle</h3>
-<p>You can also specify signing properties by including a
<code>.properties</code> file and
-pointing to it with the <code>cdvReleaseSigningPropertiesFile</code> and
-<code>cdvDebugSigningPropertiesFile</code> Gradle properties (see <a
href="#setting-gradle-properties">Setting Gradle Properties</a>).
-The file should look like this:</p>
+<p>You can also specify signing properties by including a
<code>.properties</code> file and pointing to it with the
<code>cdvReleaseSigningPropertiesFile</code> and
<code>cdvDebugSigningPropertiesFile</code> Gradle properties (see <a
href="#setting-gradle-properties">Setting Gradle Properties</a>).</p>
-<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre
class="highlight"><code>storeFile=relative/path/to/keystore.p12
-storePassword=SECRET1
-storeType=pkcs12
-keyAlias=DebugSigningKey
-keyPassword=SECRET2
+<p><strong>Example file content:</strong></p>
+
+<div class="language-properties highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="py">storeFile</span><span
class="p">=</span><span class="s">relative/path/to/keystore.p12</span>
+<span class="py">storePassword</span><span class="p">=</span><span
class="s">SECRET1</span>
+<span class="py">storeType</span><span class="p">=</span><span
class="s">pkcs12</span>
+<span class="py">keyAlias</span><span class="p">=</span><span
class="s">DebugSigningKey</span>
+<span class="py">keyPassword</span><span class="p">=</span><span
class="s">SECRET2</span>
</code></pre></div></div>
-<p><code>storePassword</code> and <code>keyPassword</code> are required for
automated signing.</p>
+<p>The <code>storePassword</code> and <code>keyPassword</code> properties are
required for automated signing.</p>
<h2>Debugging</h2>
<p>For details on the debugging tools that come packaged with the Android SDK,
see
<a href="https://developer.android.com/studio/debug/index.html";>Android's
developer documentation for debugging</a>.
-Additionally, Android's developer documentation for <a
href="http://developer.android.com/guide/webapps/debugging.html";>debugging web
apps</a>
+Additionally, Android's developer documentation for <a
href="https://developer.android.com/guide/webapps/debugging.html";>debugging web
apps</a>
provides an introduction for debugging the portion of your app running in the
Webview.</p>
<h3>Opening a Project in Android Studio</h3>
-<p>Cordova for Android projects can be opened in the Android IDE,
-<a href="https://developer.android.com/studio/index.html";>Android Studio</a>.
-This can be useful if you wish to use Android Studio's built in Android
-debugging/profiling tools or if you are developing Android plugins. Please note
-that when opening your project in Android studio, it is recommended that you do
-NOT edit your code in the IDE. This will edit the code in the
<code>platforms</code> folder
-of your project (not <code>www</code>), and changes are liable to be
overwritten. Instead,
-edit the <code>www</code> folder and copy over your changes by running
<code>cordova build</code>.</p>
+<p>Cordova-Android projects can be opened in <a
href="https://developer.android.com/studio/index.html";>Android Studio</a>. This
can be useful if you wish to use Android Studio's built in Android
debugging and profiling tools or if you are developing Android plugins.</p>
-<p>Plugin developers wishing to edit their native code in the IDE should use
the
-<code>--link</code> flag when adding their plugin to the project via
<code>cordova plugin add</code>.
-This will link the files so that changes to the plugin files in the
<code>platforms</code>
-folder are reflected in your plugin's source folder (and vice versa).</p>
+<p><em><strong>Note:</strong> When opening your project in Android Studio, it
is recommended to NOT edit the code within the IDE. Editing in Android Studio
will edit code residing in the <code>platforms</code> directory of your
project. It is not updating the code in the projects root
<code>www</code>)directory. The changes are liable to be overwritten. Instead,
edit the <code>www</code> folder and copy over your changes by running
<code>cordova prepare</code>.</em></p>
-<p>To open a Cordova for Android project in Android Studio:</p>
+<p>Plugin developers wishing to edit their native code in Android Studio
should use the <code>--link</code> flag when adding their plugin to the project
with the <code>cordova plugin add</code>. This will create a symbolic link of
the plugin files from the plugin source directory to the project's
<code>platforms</code> directory.</p>
-<ol>
- <li>
- <p>Launch <strong>Android Studio</strong>.</p>
- </li>
- <li>
- <p>Select <strong>Import Project (Eclipse ADT, Gradle, etc)</strong>.</p>
+<p>To open a Cordova-Android project in Android Studio:</p>
- <p><img src="/static/img/guide/platforms/android/asdk_import_project.png"
alt="" /></p>
- </li>
- <li>
- <p>Select the Android platform directory in your project
(<code><your-project>/platforms/android</code>).</p>
-
- <p><img
src="/static/img/guide/platforms/android/asdk_import_select_location.png"
alt="" /></p>
- </li>
- <li>
- <p>For the <code>Gradle Sync</code> question you can simply answer
<strong>Yes</strong>.</p>
- </li>
+<ol>
+ <li>Launch <strong>Android Studio</strong></li>
+ <li>Click the <strong>Open</strong> button
+ <img src="/static/img/guide/platforms/android/asdk_import_project.png" alt=""
/></li>
+ <li>Navigate to the project's Android platform directory:
(<code><project-root>/platforms/android</code>)
+ <img
src="/static/img/guide/platforms/android/asdk_import_select_location.png"
alt="" /></li>
+ <li>For the <code>Gradle Sync</code> question you can simply answer
<strong>Yes</strong>.</li>
</ol>
-<p>Once it finishes importing, you should be able to build and run the app
directly
-from <strong>Android Studio</strong>. See <a
href="https://developer.android.com/studio/intro/index.html";>Android Studio
Overview</a>
-and <a href="https://developer.android.com/studio/run/index.html";>Building and
Running from Android Studio</a>
-for more details.</p>
-
-<p><img src="/static/img/guide/platforms/android/asdk_import_done.png" alt=""
/></p>
-
-<h2>Platform Centered Workflow</h2>
-
-<p>cordova-android includes a number of scripts that allow the platform to be
used
-without the full Cordova CLI. This development path may offer you a greater
-range of development options in certain situations than the cross-platform
-cordova CLI. For example, you need to use shell tools when deploying a custom
-Cordova WebView alongside native components. Before using this development
path,
-you must still configure the Android SDK environment as described in
-<a href="#requirements-and-support">Requirements and Support</a> above.</p>
-
-<p>For each of the scripts discussed below, refer to <a
href="../../../reference/cordova-cli/index.html">Cordova CLI Reference</a>
-for more information on their arguments and usage. Each script has a name that
-matches the corresponding CLI command. For example,
<code>cordova-android/bin/create</code>
-is equivalent to <code>cordova create</code>.</p>
-
-<p>To get started, either download the cordova-android package from
-<a href="https://www.npmjs.com/package/cordova-android";>npm</a> or
-<a href="https://github.com/apache/cordova-android";>Github</a>.</p>
+<p>Once it finishes importing, you should be able to build and run the app
directly from <strong>Android Studio</strong>.</p>
-<p>To create a project using this package, run the <code>create</code> script
in the <code>bin</code>
-folder:</p>
+<p>For more resources, please see:</p>
-<div class="language-bash highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="nv">$ </span>cordova-android/bin/create
-</code></pre></div></div>
-
-<p>The created project will have a folder named <code>cordova</code> inside
that contains
-scripts for the project-specific Cordova commands (e.g. <code>run</code>,
<code>build</code>, etc.).
-Additionally, the project will feature a structure different from that of a
-normal Cordova project. Notably, <code>/www</code> is moved to
<code>/assets/www</code>.</p>
+<ul>
+ <li><a href="https://developer.android.com/studio/intro";>Meet Android
Studio</a></li>
+ <li><a href="https://developer.android.com/studio/run/index.html";>Build and
run your app</a></li>
+</ul>
-<p>To install plugins in this project, use the <a
href="../../../plugin_ref/plugman.html">Cordova Plugman Utility</a>.</p>
+<p><img src="/static/img/guide/platforms/android/asdk_import_done.png" alt=""
/></p>
<h2>Upgrading</h2>
-<p>Refer to <a href="./upgrade.html">this</a> article for instructions to
upgrade your
-<code>cordova-android</code> version.</p>
+<p>Refer to <a href="./upgrade.html">this</a> article for instructions to
upgrade your <code>cordova-android</code> version.</p>
<h2>Lifecycle Guide</h2>
<h3>Cordova and Android</h3>
-<p>Native Android apps typically consist of a series of <a
href="http://developer.android.com/reference/android/app/Activity.html";>activities</a>
that the user
-interacts with. Activities can be thought of as the individual screens that
make
-up an application; different tasks in an app will often have their own
activity.
-Each activity has its own lifecycle that is maintained as the activity enters
-and leaves the foreground of a user's device.</p>
+<p>Native Android apps typically consist of a series of <a
href="https://developer.android.com/reference/android/app/Activity";>activities</a>
that the user interacts with. Activities can be thought of as the individual
screens that make
+up an application; different tasks in an app will often have their own
activity. Each activity has its own lifecycle that is maintained as the
activity enters and leaves the foreground of a user's device.</p>
-<p>In contrast, Cordova applications on the Android platform are executed
within a
-Webview that is embedded in a <em>single</em> Android activity. The lifecycle
of this
-activity is exposed to your application through the document events that are
-fired. The events are not guaranteed to line up with Android's lifecycle,
but
-they can provide guidelines for saving and restoring your state. These events
-roughly map to Android callbacks as follows:</p>
+<p>In contrast, Cordova applications on the Android platform are executed
within a Webview that is embedded in a <em>single</em> Android activity. The
lifecycle of this activity is exposed to your application through the document
events that are fired. The events are not guaranteed to line up with
Android's lifecycle, but they can provide guidelines for saving and
restoring your state. These events roughly map to Android callbacks as
follows:</p>
<table>
<thead>
@@ -2946,48 +2902,19 @@ roughly map to Android callbacks as follows:</p>
</tbody>
</table>
-<p>Most other Cordova platforms have a similar concept of lifecycles and should
-fire these same events when similar actions happen on a user's device.
However,
-Android presents some unique challenges that can sometimes show up thanks to
the
-native Activity lifecycle.</p>
+<p>Most other Cordova platforms have a similar concept of lifecycles and
should fire these same events when similar actions happen on a user's
device. However, Android presents some unique challenges that can sometimes
show up thanks to the native Activity lifecycle.</p>
<h3>What makes Android different?</h3>
-<p>In Android, the OS can choose to kill activities in the background in order
to
-free up resources if the device is low on memory. Unfortunately, when the
-activity holding your application is killed, the Webview in which your
-application lives will be destroyed as well. Any state that your application is
-maintaining will be lost in this case. When the user navigates back to your
-application, the Activity and Webview will be recreated by the OS, but state
-will not be automatically restored for your Cordova app. For this reason, it is
-imperative that your application be aware of the lifecycle events that are
fired
-and maintain whatever state is appropriate to make sure a user's context
in your
-app is not lost when they leave the application.</p>
+<p>In Android, the OS can choose to kill activities in the background in order
to free up resources if the device is low on memory. Unfortunately, when the
activity holding your application is killed, the Webview in which your
application lives will be destroyed as well. Any state that your application is
maintaining will be lost in this case. When the user navigates back to your
application, the Activity and Webview will be recreated by the OS, but state
will not be automatically restor [...]
<h3>When can this happen?</h3>
-<p>Your application is susceptible to being destroyed by the OS whenever it
leaves
-the sight of the user. There are two main situations in which this can occur.
-The first and most obvious case is when the user presses the home button or
-switches to another application.</p>
-
-<p>However, there is a second (and much more subtle) case that certain plugins
can
-introduce. As noted above, Cordova applications are usually confined to the
-single activity that contains the Webview. However, there are instances in
which
-other activities may be launched by plugins and temporarily push the Cordova
-activity to the background. These other Activities are typically launched in
-order to perform a specific task using a native application installed on the
-device. For example, the <a
href="../../../reference/cordova-plugin-camera/index.html">Cordova camera
plugin</a>
-launches whatever camera activity is natively installed on the device in order
-to take a photo. Reusing the installed camera application in this way makes
your
-application feel much more like a native app when the user tries to take a
-photo. Unfortunately, when the native Activity pushes your app to the
background
-there is a chance the OS will kill it.</p>
-
-<p>For a clearer understanding of this second case, let's walk through an
example
-using the camera plugin. Imagine you have an application that requires the user
-to take a profile photo. The flow of events in the application when everything
-goes as planned will look something like this:</p>
+<p>Your application is susceptible to being destroyed by the OS whenever it
leaves the sight of the user. There are two main situations in which this can
occur. The first and most obvious case is when the user presses the home button
or switches to another application.</p>
+
+<p>However, there is a second (and much more subtle) case that certain plugins
can introduce. As noted above, Cordova applications are usually confined to the
single activity that contains the Webview. However, there are instances in
which other activities may be launched by plugins and temporarily push the
Cordova activity to the background. These other Activities are typically
launched in order to perform a specific task using a native application
installed on the device. For example, [...]
+
+<p>For a clearer understanding of this second case, let's walk through an
example using the camera plugin. Imagine you have an application that requires
the user to take a profile photo. The flow of events in the application when
everything goes as planned will look something like this:</p>
<ol>
<li>The user is interacting with your app and needs to take a picture</li>
@@ -3005,9 +2932,7 @@ goes as planned will look something like this:</p>
<li>The user is returned to your application where they left off</li>
</ol>
-<p>However, this flow of events can be disrupted if a device is low on memory.
If
-the Activity is killed by the OS, the above sequence of events instead plays
out
-as follows:</p>
+<p>However, this flow of events can be disrupted if a device is low on memory.
If the Activity is killed by the OS, the above sequence of events instead plays
out as follows:</p>
<ol>
<li>The user is interacting with your app and needs to take a picture</li>
@@ -3025,54 +2950,30 @@ as follows:</p>
<li>The user is confused as to why they are suddenly back at your app's
login screen</li>
</ol>
-<p>In this instance, the OS killed the application in the background and the
-application did not maintain its state as part of the lifecycle. When the user
-returned to the app, the Webview was recreated and the app appeared to have
-restarted from scratch (hence the user's confusion). This sequence of
events is
-equivalent to what happens when the home button is pressed or the user switches
-applications. The key to preventing the above experience is subscribing to
-events and properly maintaining state as part of the activity lifecycle.</p>
+<p>In this instance, the OS killed the application in the background and the
application did not maintain its state as part of the lifecycle. When the user
returned to the app, the Webview was recreated and the app appeared to have
restarted from scratch (hence the user's confusion). This sequence of
events is equivalent to what happens when the home button is pressed or the
user switches applications. The key to preventing the above experience is
subscribing to events and properly m [...]
<h3>Respecting the Lifecycle</h3>
-<p>In the examples above, the javascript events that are fired are noted in
-italics. These events are your opportunity to save and restore your
-application's state. You should register callbacks in your
application's
-<code>bindEvents</code> function that respond to the lifecycle events by
saving state. What
-information you save and how you save it is left to your discretion, but you
-should be sure to save enough information so that you can restore the user to
-exactly where they left off when they return to your application.</p>
-
-<p>There is one additional factor in the example above that only applies in the
-second-discussed situation (i.e. when a plugin launches an external activity).
-Not only was the state of the application lost when the user finished taking a
-photo, but so was the photo that the user took. Normally, that photo would be
-delivered to your application through the callback that was registered with the
-camera plugin. However, when the Webview was destroyed that callback was lost
-forever. Luckily, cordova-android 5.1.0 and above provide a means for getting
-the result of that plugin call when your application resumes.</p>
+<p>In the examples above, the javascript events that are fired are noted in
italics. These events are your opportunity to save and restore your
+application's state. You should register callbacks in your
application's <code>bindEvents</code> function that respond to the
lifecycle events by saving state. What information you save and how you save it
is left to your discretion, but you should be sure to save enough information
so that you can restore the user to exactly where they left off when they
return to your application.</p>
+
+<p>There is one additional factor in the example above that only applies in
the second-discussed situation (i.e. when a plugin launches an external
activity). Not only was the state of the application lost when the user
finished taking a photo, but so was the photo that the user took. Normally,
that photo would be delivered to your application through the callback that was
registered with the camera plugin. However, when the Webview was destroyed that
callback was lost forever. Luckily, [...]
<h3>Retrieving plugin callback results (cordova-android 5.1.0+)</h3>
-<p>When the OS destroys the Cordova activity that was pushed into the
background
-by a plugin, any pending callbacks are lost as well. This means that if you
-passed a callback to the plugin that launched the new activity (e.g. the camera
-plugin), that callback will NOT be fired when the application is recreated.
-However, starting in cordova-android <strong>5.1.0</strong>, the
<code>resume</code> event's payload will
-contain any pending plugin results from the plugin request that launched the
-external activity made prior to the activity being destroyed.</p>
+<p>When the OS destroys the Cordova activity that was pushed into the
background by a plugin, any pending callbacks are lost as well. This means that
if you passed a callback to the plugin that launched the new activity (e.g. the
camera plugin), that callback will NOT be fired when the application is
recreated. However, starting in cordova-android <strong>5.1.0</strong>, the
<code>resume</code> event's payload will contain any pending plugin results
from the plugin request that launc [...]
<p>The payload for the <code>resume</code> event adheres to the following
format:</p>
-<div class="language-text highlighter-rouge"><div class="highlight"><pre
class="highlight"><code>{
- action: "resume",
- pendingResult: {
- pluginServiceName: string,
- pluginStatus: string,
- result: any
- }
-}
-</code></pre></div></div>
+<div class="language-json highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="p">{</span><span class="w">
+ </span><span class="err">action:</span><span class="w"> </span><span
class="s2">"resume"</span><span class="p">,</span><span class="w">
+ </span><span class="err">pendingResult:</span><span class="w">
</span><span class="p">{</span><span class="w">
+ </span><span class="err">pluginServiceName:</span><span class="w">
</span><span class="err">string</span><span class="p">,</span><span class="w">
+ </span><span class="err">pluginStatus:</span><span class="w">
</span><span class="err">string</span><span class="p">,</span><span class="w">
+ </span><span class="err">result:</span><span class="w"> </span><span
class="err">any</span><span class="w">
+ </span><span class="p">}</span><span class="w">
+</span><span class="p">}</span><span class="w">
+</span></code></pre></div></div>
<p>The fields of that payload are defined as follows:</p>
@@ -3083,6 +2984,7 @@ external activity made prior to the activity being
destroyed.</p>
</ul>
<p>The possible values for <code>pluginStatus</code> in the
<code>pendingResult</code> field include the following:</p>
+
<ul>
<li><code>"OK"</code> - The plugin call was successful</li>
<li><code>"No Result"</code> - The plugin call ended with no result</li>
@@ -3100,18 +3002,11 @@ external activity made prior to the activity being
destroyed.</p>
</li>
</ul>
-<p>Please note that it is up to the plugin to decide what is contained in the
-<code>result</code> field and the meaning of the <code>pluginStatus</code>
that is returned. Reference
-the API of the plugin you are using to see what you should expect those fields
-to contain and how to use their values.</p>
+<p><em><strong>Note:</strong> It is up to the plugin to decide what is
contained in the <code>result</code> field and the meaning of the
<code>pluginStatus</code> that is returned. Refer to the plugin's API
documentationf or the expect results and how to use the values.</em></p>
<h4>Example</h4>
-<p>Below is a brief example application that uses the <code>resume</code> and
<code>pause</code> events
-to manage state. It uses the Apache camera plugin as an example of how to
-retrieve the results of a plugin call from the <code>resume</code> event
payload. The
-portion of the code dealing with the <code>resume</code>'s
<code>event.pendingResult</code> object
-requires cordova-android <strong>5.1.0+</strong></p>
+<p>Below is a brief example application that uses the <code>resume</code> and
<code>pause</code> events to manage state. It uses the Apache camera plugin as
an example of how to retrieve the results of a plugin call from the
<code>resume</code> event payload. The portion of the code dealing with the
<code>resume</code>'s <code>event.pendingResult</code> object requires
cordova-android <strong>5.1.0+</strong></p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="c1">// This state represents the state of
our application and will be saved and</span>
<span class="c1">// restored by onResume() and onPause()</span>
@@ -3235,12 +3130,15 @@ requires cordova-android <strong>5.1.0+</strong></p>
<span class="nt"></body></span>
<span class="nt"></html></span>
</code></pre></div></div>
+
<h3>Android Quirks</h3>
-<p>The default API level in the Cordova Android platform has been upgraded. On
an Android 9 device, clear text communication is now disabled by default.</p>
+
+<p>The default API level in the Cordova-Android platform has been upgraded. On
an Android 9 device, clear text communication is now disabled by default.</p>
<p>By default HTTP and FTP etc. will refuse the apps requests to use cleartext
traffic. The key reason for avoiding cleartext traffic is the lack of
confidentiality, authenticity, and protections against tampering; a network
attacker can eavesdrop on transmitted data and also modify it without being
detected. You can learn more about the
<code>android:usesCleartextTraffic</code> or any other android application
elements setting in the <a href="https://developer.android.com/guide/topics/m
[...]
<p>To allow clear text communication again, set the
<code>android:usesCleartextTraffic</code> on your application tag to true in
<code>config.xml</code> file:</p>
+
<div class="language-xml highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="nt"><platform</span> <span
class="na">name=</span><span class="s">"android"</span><span
class="nt">></span>
<span class="nt"><edit-config</span> <span class="na">file=</span><span
class="s">"app/src/main/AndroidManifest.xml"</span> <span
class="na">mode=</span><span class="s">"merge"</span> <span
class="na">target=</span><span class="s">"/manifest/application"</span><span
class="nt">></span>
<span class="nt"><application</span> <span
class="na">android:usesCleartextTraffic=</span><span class="s">"true"</span>
<span class="nt">/></span>
@@ -3248,9 +3146,13 @@ requires cordova-android <strong>5.1.0+</strong></p>
<span class="nt"></platform></span>
</code></pre></div></div>
-<p>And also you need to add Android XML namespace
<code>xmlns:android="http://schemas.android.com/apk/res/android";</code> to your
widget tag in the same <code>config.xml</code>, like so:
-<code><widget id="io.cordova.hellocordova" version="0.0.1"
android-versionCode="13" xmlns="http://www.w3.org/ns/widgets";
xmlns:cdv="http://cordova.apache.org/ns/1.0";
xmlns:android="http://schemas.android.com/apk/res/android">
-</widget></code></p>
+<p>And also you need to add Android XML namespace
<code>xmlns:android="http://schemas.android.com/apk/res/android";</code> to your
widget tag in the same <code>config.xml</code>.</p>
+
+<p><strong>Example:</strong></p>
+
+<div class="language-xml highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="nt"><widget</span> <span
class="na">id=</span><span class="s">"io.cordova.hellocordova"</span> <span
class="na">version=</span><span class="s">"0.0.1"</span> <span
class="na">android-versionCode=</span><span class="s">"13"</span> <span
class="na">xmlns=</span><span class="s">"http://www.w3.org/ns/widgets";</span>
<span class="na">xmlns:cdv=</span><span class="s">"http://cordova. [...]
+<span class="nt"></widget></span>
+</code></pre></div></div>
<h3>Android Manifest Information</h3>
@@ -3258,11 +3160,7 @@ requires cordova-android <strong>5.1.0+</strong></p>
<h3>Testing the Activity Lifecycle</h3>
-<p>Android provides a developer setting for testing Activity destruction on low
-memory. Enable the "Don't keep activities" setting in the
Developer Options menu
-on your device or emulator to simulate low memory scenarios. You should always
-do some amount of testing with this setting enabled to make sure that your
-application is properly maintaining state.</p>
+<p>Android provides a developer setting for testing Activity destruction on
low memory. Enable the "Don't keep activities" setting in the
Developer Options menu on your device or emulator to simulate low memory
scenarios. You should always do some amount of testing with this setting
enabled to make sure that your application is properly maintaining state.</p>
diff --git a/feed.xml b/feed.xml
index 7e67eafed..5243226c2 100644
--- a/feed.xml
+++ b/feed.xml
@@ -6,8 +6,8 @@
</description>
<link>https://cordova.apache.org/</link>
<atom:link href="https://cordova.apache.org/feed.xml"; rel="self"
type="application/rss+xml"/>
- <pubDate>Tue, 12 Jul 2022 10:49:21 +0000</pubDate>
- <lastBuildDate>Tue, 12 Jul 2022 10:49:21 +0000</lastBuildDate>
+ <pubDate>Wed, 13 Jul 2022 04:58:08 +0000</pubDate>
+ <lastBuildDate>Wed, 13 Jul 2022 04:58:08 +0000</lastBuildDate>
<generator>Jekyll v4.2.2</generator>
<item>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@cordova.apache.org
For additional commands, e-mail: commits-h...@cordova.apache.org
