I’m dabbling in several projects developing for mobile devices at the moment, and the first thing I’ve had to do is set up the appropriate development environment(s). One such example was to perform a fresh install of PhoneGap (the last version I used was 0.9, the current version is 2.2.0). As there’s an awful lot of outdated/incorrect information on the ‘net that might cause new users confusion about this, I thought I’d jot a few notes on the process here.
Why would you want PhoneGap?
PhoneGap is an open-source framework allowing you to write code using HTML, Javascript and CSS, which it then packages up into Android, Windows Phone, or iPhone/iPad applications (or various others). This is a pretty neat idea for developers who either don’t want to rewrite their applications for each platform or who, like me, are fairly knowledgeable with HTML/JS but don’t know where to begin with Java/Objective-C used to build native mobile applications. In fact, using PhoneGap as a wrapper around the Bing Maps AJAX control is the recommended way to create Bing Maps applications for Android.
#1: “PhoneGap” == “Apache Cordova”
You can read about the history of PhoneGap here. Not that you need to, but it might explain why you’ll end up following links that say “Getting started with PhoneGap” only to be led to a page titled “Apache Cordova Documentation”.
As at the time of writing, you can consider these two terms completely equivalent names for the same thing, and you’ll notice them used almost interchangeably throughout the examples and documentation.
#2: “PhoneGap” != “PhoneGap Build”
PhoneGap is a set of templates and files that you install to your local machine and which, in combination with the appropriate development SDK (Android/iOS) allow you to package your HTML/JS code as a native mobile app.
PhoneGap Build is an online packaging service, which means you can upload your HTML/JS/CSS and receive an iOS/Android/Windows app back in return without ever needing the SDK installed on your local computer, but you’ll have to pay to build a commercial app using that service.
Note that you can’t compile an iOS app on a Windows PC (with or without PhoneGap) – you’ll either have to get hold of a Mac, or use the PhoneGap Build service instead. But you can compile for Android (and Windows Phone etc.) on a Windows PC, all from the same codebase, so long as you have the relevant SDK installed.
#3: Pre-Requisites for Installation
The requirements stated on the official PhoneGap/Apache Cordova “Getting Started with Android” page are horribly wrong. What you actually need to develop Android applications via PhoneGap on a PC is as follows:
- Java (http://www.java.com/en/download/index.jsp). Note that some sources state you need only the Java Runtime Engine (JRE), whereas others state you need the Java Development Kit (JDK – which includes the JRE). Unfortunately, as I already had both installed, I can’t verify which is correct. But you certainly need at least the JRE installed.
- Download and extract the latest PhoneGap/Cordova 2.2.0 zipball. Note that there is nothing to install – PhoneGap is basically just a set of template files and libraries rather than an application.
- Download and install the Android Developer Tools Bundle for Windows (ADT-bundle) from http://developer.android.com/sdk/index.html.
- That’s it! You do not need to separately download or install Eclipse, the ADT plugin, ANT, or any other nonsense – these are all included and correctly configured in the ADT bundle already.
#4: The Sample Application does not do what you think it will
It seems natural to start by examining the source code for the supplied PhoneGap sample application (located in lib/android/example/). If you look at the javascript file for that application, in assets/www/main.js, you’ll see lots of useful functions, such as:
var deviceInfo = function() {
document.getElementById("platform").innerHTML = device.platform;
document.getElementById("version").innerHTML = device.version;
document.getElementById("uuid").innerHTML = device.uuid;
document.getElementById("name").innerHTML = device.name;
document.getElementById("width").innerHTML = screen.width;
document.getElementById("height").innerHTML = screen.height;
document.getElementById("colorDepth").innerHTML = screen.colorDepth;
};
There’s also functions with what sound like fairly descriptive names:
getLocation() beep() vibrate() show_pic() get_contacts() toggleCompass()
It seems reasonable from looking at these functions to expect that the sample application therefore provides some sort of testing of the device capabilities on which it is running. You might therefore be somewhat surprised to compile and deploy the application only to get this:
That’s it? Where’s all the device info? Has the application crashed? Is it because I’m running it in an emulator that it can’t access the device capabilities?
Nope - the (slightly bizarre) explanation is that the sample PhoneGap application includes loads of extra code that never ever gets executed. In fact, the only thing that actually gets executed is a splash screen with a green pulsating button saying “device is ready”. How this is meant to be a learning aid is beyond me, but if you get the screen above, then your Cordova installation is working fine – that’s all the sample application does. (It seems I’m not the only one surprised by this – see http://stackoverflow.com/questions/13804533/phonegap-2-2-0-cant-get-past-the-device-is-ready-screen-on-android)
#5 Emulation and Deployment
If the Android emulator crashes, try toggling the GPU acceleration/changing Screen Resolution settings. There are known bugs with certain sizes of emulator on Windows 7 64-bit, especially with GPU acceleration enabled, as reported at http://code.google.com/p/android/issues/detail?id=28515 and http://code.google.com/p/android/issues/detail?id=28601
To deploy the packaged PhoneGap app on an actual Android device over USB, you need to install the appropriate USB driver (not just the one that you use to copy files to/from your device). For the Sony Xperia S handset I use, this can be found at developer.sonymobile.com/downloads/drivers/xperia-s-driver-for-ics/ . You can check that the device is installed correctly by executing "adb devices" from a command prompt in the platform-tools directory.
After all that…
Documentation and stability issues aside, I’m actually pretty impressed with PhoneGap – for non-CPU intensive applications it’s a pretty efficient and easy way to get “native” apps installed on your Android phone which, with a little polishing, would be perfectly suitable to publishing in the Google Play store. Note that performance is not going to be as good as a native app, although exactly how the two compare seems to vary quite a bit from device-to-device.
Certainly, if you’re comfortable with HTML/JS and want to try out a quick prototype of a mobile app, I’d recommend you give PhoneGap a try. There are alternatives (I’m also playing around with CocoonJS), but these tend to be for specific purposes – e.g. HTML5 canvas games – whereas PhoneGap is a more universal tool.
