Android Platform Guide

Android Platform Guide

This guide shows how to set up your SDK development environment to deploy Cordova apps for Android devices. It walks you through the process of installing the Android SDK, opening an Android project in Eclipse SDK, and deploying to an emulator or device. You will need to follow this guide to at least Install the Android SDK, regardless of which workflow you are following. (Both the Web Project Dev and Native Platform Dev workflows require the Android SDK to be installed and accessable via your PATH.)

See the following for more detailed platform-specific information:

The command-line tools above refer to versions prior to Cordova 3.0. See The Command-Line Interface for information about the current interface.

Requirements and Support

Cordova for Android requires the Android SDK. See the Android SDK's System Requirements.

Cordova supports Android 2.3.x (Gingerbread, starting with Android API level 10) and 4.x. As a general rule, Android versions become unsupported by Cordova as they dip below 5% on Google's distribution dashboard. Android versions earlier than API level 10, and the 3.x versions (Honeycomb, API levels 11-13) fall significantly below that 5% threshold.

Developers should use the cordova utility in conjunction with the Android SDK. See The Command-Line Interface for information how to install it, add projects, then build and deploy a project.

Install the Android SDK from developer.android.com/sdk. The android sdk is distributed as an 'adt-bundle---' file. On windows, the adt-bundle is packaged with an installer. On OSX and Linux, simply unpack the 'adt-bundle' in the location you store development tools. More detailed information on Android SDK setup can be found here

For Cordova command-line tools to work, you need to include the SDK's tools and platform-tools directories in your PATH environment. On Mac, you can use a text editor to create or modify the ~/.bash_profile file, adding a line such as the following, depending on where the SDK installs:

export PATH=${PATH}:/Development/adt-bundle/sdk/platform-tools:/Development/adt-bundle/sdk/tools

This exposes SDK tools in newly opened terminal windows. Otherwise run this to make them available in the current session:

$ source ~/.bash_profile

To modify the PATH environment on Windows 7:

You may also need to enable Java and Ant. Open a command prompt and type java, and also type ant. Append to the PATH whichever fail to run:

    ;%JAVA_HOME%\bin;%ANT_HOME%\bin

Open a Project in the SDK

Use the cordova utility to set up a new project, as described in The Cordova The Command-Line Interface. For example, in a source-code directory:

    $ cordova create hello com.example.hello "HelloWorld"
    $ cd hello
    $ cordova platform add android
    $ cordova build

Once created, here's how to use the SDK to modify it:

Once the Eclipse window opens, a red X may appear to indicate unresolved problems. If so, follow these additional steps:

Deploy to Emulator

You can use the cordova utility to run an app in an emulator, or you can run it within the SDK. Either way, the SDK must first be configured to display at least one device. To do so, use the Android SDK Manager, a Java application that runs separately from Eclipse. There are two ways to open it:

Once open, the Android SDK Manager displays various runtime libraries:

Choose Tools → Manage AVDs (Android Virtual Devices), then choose any item from Device Definitions in the resulting dialog box:

Press Create AVD, optionally modifying the name, then press OK to accept the changes:

The AVD then appears in the Android Virtual Devices list:

To open the emulator as a separate application, select the AVD and press Start. It launches much as it would on the device, with additional controls available for hardware buttons:

At this point you can use the cordova utility to deploy the application to the emulator from the command line:

    $ cordova emulate android

If instead you work within Eclipse, right-click the project and choose Run As → Android Application. You may be asked to specify an AVD if none are already open.

For a faster experience, use an Intel-based emulator image:

Deploy to Device

To push an app directly to the device, make sure USB debugging is enabled on your device as described on the Android Developer Site, and use a mini USB cable to plug it into your system.

You can push the app to the device from the command line:

    $ cordova run android

Alternately within Eclipse, right-click the project and choose Run As → Android Application.