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. Show
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. Android API Level SupportThe supported Android API Levels (versions of Android) corresponding with the Cordova-Android released versions are listed in the table below:
Note: The cordova-android versions listed above are not for the Cordova CLI. To determine what version of the Cordova-Android package is installed in your Cordova project, run the command As a general rule, Android versions become unsupported by Cordova as they dip below 5% on Google's distribution dashboard. System RequirementsCordova-Android requires the Android SDK, which can be installed on either macOS, Linux, or Windows. For the base system requirements, see the Android Studio's System Requirements. The Required Software & ToolsJava Development Kit (JDK)If
you are using If you are using any version below The GradleAs of Cordova-Android 6.4.0, Gradle is required to be installed. When installing on Windows, you need to add the path to the Gradle's binary directory to your Note: 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. Android StudioDownload and install Android Studio. 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 packages. Adding SDK PackagesIt 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 Android API Level Support to find the supported version based on the Cordova-Android versions. In the Android Studio, open the SDK
Manager (
Android SDK ToolsIn Android Studio 3.6 or later, the obsolete Android SDK Tools will need to be intalled. To do this:
See Android's documentation on how to Update your tools with the SDK Manager for more details. Setting environment variablesCordova'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. The following variables must be set:
It is also recommended to update the
Note: The directories above are generally located in the Android SDK ROOT. macOS and LinuxOn a Mac or Linux, with a text editor, create or modify the To set an environment variable, add a line that uses
To
update your
Reload your terminal to see this change reflected or run the following command: WindowsThese steps may vary depending on your installed version of Windows. Close and reopen any command prompt windows after making changes to see them reflected.
To create a new environment variable
To set your PATH
Repeat step 3 and 4 until all paths are added. Example paths (substitute the paths with your local Android SDK installation's location):
Once all paths are added, click the OK button until all opened windows for setting & editing environment variables are closed. Project ConfigurationSetting up an EmulatorIf you wish to run your Cordova app on an Android emulator, you will first need to create an Android Virtual Device (AVD). See the following Android documentation for more details on:
Once your AVD is configured correctly, you should be able to deploy your Cordova application to the emulator by running the following command: Configuring GradleCordova-Android projects are built by using Gradle. Setting Gradle PropertiesIt is possible to configure the Gradle build by setting the values of certain Gradle properties that Cordova exposes. The following properties are available:
You can set these properties in one of four ways:
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 Extending build.gradleIf you need to customize the Here's an example:
Note that plugins can also include
Configuring Gradle JVM ArgsTo change the Gradle JVM args, the By default, JVM args has a value of
The following units are supported:
Setting the Version CodeTo change the version code for your app's generated apk, set the If the
If your application has enabled the Note: Be aware that some plugins added to your project may set this Gradle property automatically. Note: When updating the Signing an AppIt is recommended to read Android's documentation for Sign your app first, as it contains the necessary steps in creating required files for signing. Using FlagsTo sign an app, you need the following parameters:
The parameters above can be specified as an argument when using the Cordova CLI Note: You should use double Example:
Using build.jsonAlternatively, you could specify the signing parameters in a build
configuration file ( By default, if the Example
There is also support to mix and match command line arguments and parameters in
Using GradleYou can also specify signing properties by including a Example file content:
The DebuggingFor details on the debugging tools that come packaged with the Android SDK, see Android's developer documentation for debugging. Additionally, Android's developer documentation for debugging web apps provides an introduction for debugging the portion of your app running in the Webview. Opening a Project in Android StudioCordova-Android projects can be opened in Android Studio. 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. Note: 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 Plugin developers wishing to edit their native code in Android Studio should use the To open a Cordova-Android project in Android Studio:
Once it finishes importing, you should be able to build and run the app directly from Android Studio. For more resources, please see:
UpgradingRefer to this article for instructions to upgrade your Lifecycle GuideCordova and AndroidNative Android apps typically consist of a series of activities 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. In contrast, Cordova applications on the Android platform are executed within a Webview that is embedded in a single 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:
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. What makes Android different?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. When can this happen?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. 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 Cordova camera plugin 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. 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:
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:
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. Respecting the LifecycleIn 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 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. Retrieving plugin callback results (cordova-android 5.1.0+)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 5.1.0, the The payload for the
The fields of that payload are defined as follows:
The possible values for
Note: It is up to the plugin to decide what is contained in the ExampleBelow is a brief example application that uses the
The corresponding html:
Android QuirksThe default API level in the Cordova-Android platform has been upgraded. On an Android 9 device, clear text communication is now disabled by default. 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 To allow clear text communication again, set the
And also you need to add Android XML namespace Example:
Android Manifest InformationYou can learn more about the Android manifest information in the documentation for Android developers. Testing the Activity LifecycleAndroid 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. |