Saturday, February 15, 2014

PhoneGap installation and setup of Android SDK to create native applications from HTML/CSS/JavaScript

Since the (mobile) platforms a developer can target for his application today are so diverse, the best solution for some might be to find a common denominator to start with.

Having the ability to bring an application without any or with little changes to nearly any platform by using HTML, CSS and JavaScript, as long as the target platform has a web browser installed, is something to consider here.
When targeting mobile devices, often just an extension/change of the user inputs are required, for example using touch events.

The real bummer in this regard has been, that mobile applications often do not work that well in a browser in real life. Some downfalls can be:

  • No fullscreen
  • No access to native APIs like accelerometer etc.
  • No start icon on homescreen
  • No download via store

Luckily some smart people try to fill exactly this gap, and have developed solutions to build native applications, which negate all this downfalls, from plain HTML, CSS, and JavaScript. 
There are CocoonJS and PhoneGap for example, the latter we discuss in this article, since it is free to use, and you can use it to build native applications on your own on your home computer, or in the cloud (which might cost). CocoonJS on the other hand just allows to build applications in the cloud.

For PhoneGap there are a bunch of steps you have to perform, before you can build the first application with it, which we discuss in detail here.

At first, make sure, that you have a computer system, which is capable for compiling native applications for your target device, even when using something like PhoneGap. The reason behind this is, that PhoneGap creates a native app, embedding a WebView (on Android), which practically opens your HTML page locally, and this makes for the requirement of the respective SDK sources.
In short this means, that you have to have a Windows computer to build applications for Android or Windows Phone. If you want to target iOS, you need a Macintosh computer.

If you want to target a device you have no build computer for, or you do not want to install all the stuff required for building on your computer, you can use the cloud build services of PhoneGap or CocoonJS.
You simply upload your sources to their service, and they build and provide the native installation files for download.

So, let's start.
(In the following you might use Cordova instead of PhoneGap, as PhoneGap builds on it, and they should share the same functionality.)

We'll use the Android SDK and a Windows computer in this example, to target Android devices. If you want to target iOS devices, hopefully most of the steps you can adapt to your Macintosh environment.

What you will need are these applications, which you can install right away:
  • PhoneGap
  • Android SDK
    The Android SDK to work well with PhoneGap, needs to have some information added to the PATH environment variable. You can access it by navigating to your Control Center/System/Extended System Settings/Environmentvariables...
    There you have to edit the Uservariable PATH, and add this (where <SDK Folder> has to be replaced by the installation folder name you have chosen on your computer): C:\Program Files\<SDK Folder>\sdk\platform-tools;C:\Program Files\<SDK Folder>\sdk\tools;
If you edit an environment variable, remember to close and reopen your Windows Command Prompt afterwards (if open), to take effect (if in doubt, restart your computer).

You also have to install some further stuff:

  • Java Development Kit and Java Runtime Environment
    Create a new environment variable with the Name JAVA_HOME, and add the following information to it: C:\Program Files\Java\<JDK Folder>
  • NodeJS
    You have to edit the PATH environment variable again, and add this information: C:\Users\<User>\AppData\Roaming\npm;
  • PhoneGap Command Line Interface
    Install it via NodeJS Node Package Modules, using this command from Windows Command Prompt (which is described here: npm install -g phonegap
  • Apache Ant
    You install it via the NodeJS Node Package Modules, using this command from Windows Command Prompt (which is described here: npm install ant
    Create a new environment variable with the Name ANT_HOME, and add this information: C:\Program Files (x86)\<Apache Ant Folder>
  • Git

When you have installed everything, you should restart your computer to be sure that all changes take effect. Now, if you have a web page you want to deploy to your Android device, perform as follows:

  1. Open up the Windows Command Prompt (by typing cmd into the Windows Execute/Search Bar).
  2. In the Command Prompt navigate to a folder you want your sources to be stored.
  3. Type in phonegap create <Folder name>, where <Folder name> is the name of the folder PhoneGap should create for you in the current folder.
  4. Navigate to the folder www in that newly created folder.
  5. Now copy your sources, the HTML, Javascript, and CSS, into the respective subfolders. Your HTML file should reside directly in www, your JavaScript files in js, and your CSS files in css.
    You might have to edit the paths to your ressources in your files accordingly.
  6. Now, from the folder www, type in phonegap run android to build and run your application directly on your virtual device or phone.
    Alternatively you can just build your application by typing phonegap build android, or just install/run it on your virtual device/phone with phonegap install android.

That's it, you should have deployed your first application created with plain HTML, CSS, and JavaScript, and the help of PhoneGap, to make a native application, to your Android device.

Possible Issues, which might occur:

In the current implementation of the WebView in Android 4.4. KitKat, there is a bug, which makes applications which are using the HTML5 canvas, behave extremly slow. Further information about the status of this bug can be found on the official developer pages of Chromium:

If you have trouble deploying to your Android device (as I had with the new Nexus 5), check if the device has a small yellow exclamation mark next to it in the Windows device manager. If so, update the driver with the one coming with the Android SDK, usually located at C:\Program Files\<SDK Folder>\sdk\extras\google\usb_driver.

If you want to use the native APIs of your phone, like accelerometer for example, you have to install each plugin additionaly. For example, to use the accelerometer, navigate to the folder www in your applications folder, and execute by Command Prompt: phonegap local plugin add
Further details are explained here:

Please let me know, if something is not working, if I forgot something, or if something just needs further explanation. I will update the article accordingly.


  1. Why is restarting Windows a requirement? Just close the cmd window you are working in and open a new one; works in Windows 7 at least (for a user with developer and admin rights).
    Why are both cordova and phonegap listed as requirements? Given that phonegap online documentation is starting to lean towards using the cordova command, and recommends not using phonegap, you could probably stick with just cordova and help remove the confusion for beginners trying to follow the phonegap documentation. Otherwise, thanks for this, it helped calm my nerves after trying to follow the mixed up phonegap documentation.

    1. I am glad this article helped.

      You are right, a restart is not necessary, I updated the post.
      I also deleted the Cordova part, but added it as an alternative. Currently I am a bit confused myself, which is the recommended API.

  2. This would've cost me a few days to figure it all out on my own and now I just had to read your post. Great work putting all this together!

    1. I uploaded it because it actually cost me a few days.

  3. Thank you for publishing this guide.

    Everything worked for me till here:
    npm http GET
    npm http 304
    npm WARN engine ant@0.2.0: wanted: {"node":"~0.8.0"} (current: {"node":"v0.10.26","npm":"1.4.3"})

    Has anyone any idea how to fix this?

    1. Try this: npm cache clear
      Then: npm install ant

      It seems, that the installer caches some files, and therefore throws this error. Source:

  4. Thank you, this saved me a lot of trouble.

    A couple of additional steps that I had to perform:
    - I had to add "C:\Program Files (x86)\Git\cmd" to my PATH for some phonegap commands to work.
    - My ANT_HOME had to be C:\Users\\node_modules\ant\ant\bin
    - During 'phonegap run android' I got an "EPERM, operation not permitted" error. I worked around it by giving full permissions to Everyone in the folder mentioned in the error message. (There should be a better solution, like giving permission to just the user under which this process runs, but I don't know which user that is.)

    1. Thank you. I hope this helps other users.

  5. Replies
    1. These steps have been performed on Windows 8.