Getting started with PhoneGap
Written by Harry Fairhead   
Tuesday, 13 September 2011
Article Index
Getting started with PhoneGap
Phone Gap SDK
A PhoneGap project

HTML mobile apps are platform independent but this means that they can't make use of any hardware or services that the a particular phone offers. PhoneGap can convert your HTML app into a native app.

While there are advantages in going native, you have to write the same code over again to port to another device. A web app has the advantage that it works everywhere but generally speaking you can't access the phone's hardware and services. A web app running on a mobile phone is just like a web app running in any browser. For many, this disadvantage makes the HTML/JavaScript approach to building mobile apps unattractive.

Introducing Phone Gap

PhoneGap is an open source solution to this problem. It provides access to the services and hardware of the phone by way of a JavaScript library. This library is the same for all phones, so you can really write a single application code base and use it on a range of different platforms. In addition the web app is wrapped in a "runtime" that makes it look like a standard native app so you can submit to app stores and generally treat your web app as if it was a perfectly normal native app. So, it seems to have all of the advantages of a web app and all of the advantages of a native app.

The only disadvantage is that the "runtime" adds to the size of the app. A native "Hello World" app takes about 20KB compared to about 300KB for the equivalent PhoneGap application. This isn't as bad as it sounds because the overhead becomes less as a percentage of the total as you increase the complexity of the app.

If you want to use the open source version you can't completely ignore the SDK for the platform you want to use because you need it to package the web app as a native app. You can avoid all of this, however, if you subscribe to PhoneGap Build. This takes your web app and converts it to a native app running on the platform of your choice You upload your code, the service packages it and returns a runnable app. This really does make life simple but it will cost extra once it is out of beta.

To run the app in an emulator or to debug it the easiest option is to install the device's SDK. So in this "getting started" we are going to use the SDK approach to using PhoneGap with Android. Getting the app running on a single platform via the SDK and then using the Build service to create other phone apps seems like a very good overall approach.

At the moment PhoneGap supports iOS, iOS(XCode4), Android, Blackberry, WebOS, Bada and Symbian. There is also a beta of a system for Windows Phone 7 (Mango). Not all of the platforms support access to all native services so you have to be careful about what you use if you want to port your app to a wide range of phones. However, for the latest iOS, Android and Blackberry support is uniform apart from media access not being supported on Blackberry.

Before we get started a few words on how PhoneGap works. What stops a web app from accessing the services of a mobile device is simply that the browser sandboxes it for security reasons. All PhoneGap does is remove the sandbox and provides a JavaScript API to access the system components. You can think of the PhoneGap runtime as a custom browser designed to do nothing but service the HTML/CSS and JavaScript you have presented it with.  You really can write the web app without any reference to the particular mobile device you are interested in, but the custom browser and how you get it to run your HTML, etc., varies according to the platform. 

Let's take a look at how to do it for the Android - other platforms are very similar.

First steps with Android and PhoneGap

If you already have the Android SDK installed and have it all working you can skip forward to step 5 about installing PhoneGap.

Running through the basics of getting Android up and running isn't a waste of time because not all PhoneGap users will have created an Android app before. It is one of the advantages of PhoneGap that it lets you create an app for a phone you know very little about.

Essentially you have to complete the following steps:

  1. Install the latest Java
  2. Install Eclipse
  3. Install the Android SDK
  4. Install the Eclipse plugin for Android
  5. Download and "install" the PhoneGap SDK
  6. Create a PhoneGap project

Of course you can skip any of the following steps that you have already completed as part of developing Android applications.

1. Install Java

Your first task is to make sure that you have an up-to-date Java 6 (also known as 1.6) installation. You can check by clicking on the following link: Java test page. This requirement will probably change to Java 7 in the near future - just install the latest version.

2. Install Eclipse

You second task is to install Eclipse. There are many prepackaged versions of Eclipse but these only differ in what components are installed, so in principle you could use any version and simply install the components you need. In practice, it is easier to start with a set of preinstalled packages close to what you need. In this case download Eclipse Classic unless you have a strong reason not to. Also notice that you can have multiple versions of Eclipse installed on the same machine and you can set up independent workspaces.

Download Classic from:

If you have never installed Eclipse before it is worth saying that there is nothing much to do. Simply unzip the files into a suitable folder, any folder will do, locate the Eclipse.exe file and run it. You can place a shortcut on the desktop or pin it to the taskbar.

It is a good idea to check that you can run Eclipse and know how to get to its Workbench before you move on.

3. Install the Android SDK

You can now download the Android SDK from

SDK download page

If you are downloading for a Windows installation use the installer - it is much simpler. The files are installed into:

C:\Program Files (x86)\Android\android-sdk

for a 64-bit system or

C:\Program Files\Android\android-sdk

for a 32-bit system.

You need to know the name of the folder in which the SDK is stored. Also due to a bug in the Eclipse add-in you also have to enter the path without any spaces. To do this you need the old MS-DOS name of the directory and to get this you need to start a command prompt and enter:

DIR \ /X

You should discover that Program Files (x86) name is Progra~2 or similar. You will need to use this later - unless the bug has been fixed.

4. Install the Eclipse ADT plugin

To install the Eclipse ADT plugin you have to work with Eclipse and not the operating system.

Start Eclipse and use the command Help>Install New Software. Next click add and enter the name ADT Plugin and the URL

Click OK. Next select Developer Tools and click next, then accept the license agreement and click Finish. At this point th ADT plugin downloads and installs.

Restart Eclipse and configure the plugin. To do this select Window->Preferences and select Android. Now you have to specify the SDK location. As mentioned in the previous section there is a bug which means you can't use a path that has spaces in it. The solution is to use the old MS-DOS name for the directories - see the previous section to discover how to do this. You will enter something like:


Click Apply and then OK. If you need to change it you can simply repeat these steps at any time.

Next we have to install the SDK components into Eclipse. To do this, start the SDK and AVD Manager using the command:

Window->Android SDK and AVD Manager

If you used the Windows installer you don't need this command as the SDK and AVD Manager will be open with a set of SDK components selected - simply click Install. If not select a set of packages to install the SDK and at least one Platform version. In most cases it is simpler to just install everything with the possible exception of the Android Repository and Third party Add-ons.


Last Updated ( Tuesday, 13 September 2011 )