Digital Dandelion

Getting Started with PhoneGap

2009-11-18, Jeremiah

PhoneGap is a tool for creating mobile applications using web technologies. You start by building a typical website using HTML, CSS, and JavaScript. PhoneGap then wraps your web files with a native mobile platform application. By including the PhoneGap JavaScript library, your web application is enriched with access to mobile handset features like accelerometer data, camera, contacts, geographic location, and vibration.

Digital Dandelion recently made a demonstration application using PhoneGap for Sony Ericsson. You can download the project from BitBucket.

Getting Started

1. Download the latest PhoneGap.

   I recommend grabbing the "edge" release if you're working on sexy new Sony Ericsson device.

2. Make the PhoneGap JavaScript library.

   You'll only need to do this on edge releases. Mac OS X or Linux users can follow the instructions below from Terminal. Windows users, you're on your own. I think you'll need Cygwin.

   1. Go to the unpacked PhoneGap directory.

      cd ~/Downloads/phonegap-phonegap-efd5e89

   2. Run "make".

      make

   3. Move the new JavaScript library to your Android project.

      mv lib/android/phonegap-min.js android/assets/www

3. Setup your Android development environment.

   While you only need web developer skills to make an Android application with PhoneGap, you will still need to be able to compile the Android application. I recommend following the Installing the Android SDK documentation. It's incomplete, so here is additional information.

   1. Download and install Eclipse.

      Eclipse comes in 31 flavors. "Eclipse Classic" is a good one.

   2. Download and install the Android SDK.

      Unzip. In Mac OS X, I move the directory to ~/Library.

      For easy access to the Android SDK in terminal, add the tools directory to your bash profile. In Terminal:

      nano ~/.bash_profile

      In the nano text editor:

      export PATH=${PATH}:~/Library/android-sdk-mac/tools

      Hit Ctrl X. Type Y to save changes. Hit return. Then close your Terminal window and open a new one.

      android update sdk

      This will launch the Android SDK Manager. If you get an error message saying "Failed to fetch URL https://dl-ssl.google.com/android/repository/repository.xml, reason:HTTPS SSL error. You might want to force download through HTTP in the settings." Go to Settings and check the box "Force https://... sources to be fetched using http://..." Save & Apply. Close Android. Run the command above again.

      Tick the "Accept All" radio button in the Available Packages window that appears and Install Accepted.

   3. Install Android Development Tools (ADT).

      After following the instructions in the link, open Eclipse. Go to Preferences > Android. Set the SDK Location (~/Library/android-sdk-mac in my case).

4. Import the PhoneGap project.

   In Eclipse, go to File > Import... Under General, select Existing Projects into Workspace. Browse to the android application.

   Once your project is imported, right click on the project name in the Package Explorer (file list on the left) and select Properties. Under Android, set the Project Build Target to Google APIs 1.6. Apply and OK.

5. Change the name of your application.

   In the Package Explorer, right click on com.phonegap under the src directory. Select Refactor > Rename...

   Enter a new package name (com.myapp). Check Update references and Rename subpackages. Eclipse will, inevitably, miss a few. If you see Errors in the Problems panel. Right click on them, select Go to. Change any remaining references to com.phonegap to your new package name.

   Edit res/strings.xml and change the app_name value to your application name.

   Save it all.

6. Change the icon of your application.

   Create a new 57x57 pixel PNG-24 icon and save it in res/drawable/icon.png.

Building Your Application

1. Create your web application.

   Make a webpage as you normally would. Place your files in assets/www/. If you would like to use PhoneGap features, refer to PhoneGap's documentation. I highly recommend reading the Safari Web Content Guide to learn the best practices in formatting content for a mobile browser.

2. Test in the PhoneGap Simulator.

   Download and install the PhoneGap Simulator. This is the fastest way to test your application and the only way to test accelerometer functionality. However, the simulator is not a replacement for the Android Emulator or device testing.

3. Test in the Android Emulator.

   In Eclipse, select the project directory. Go to Run > Run. Choose Android Application.

   If you get an error "No compatible targets were found. Do you wish to add new Android Virtual Device?", click Yes. Create a new AVD by giving your virtual device a name, target of Google APIs - API Level 4, and skin with a resolution of the device you're targeting. The Sony Ericsson is a WVGA854 device. After creating the device, try to run the application again.

4. Export your app for distribution.

   Select your project in the Package Explorer. Right click > Android Tools > Export Signed Application Package.

   If you don't have a keystore, you'll need to create one. Select a location to store it and enter a password. Give your key an alias, another password (it can be the same as the keystore password), 100 years validity, and any of the ownership information. You do not need to enter all of the ownership information, but avoid using commas in any field or you will the error "keytool error: java.io.IOException: Incorrect AVA format."

Potential Gotchas

1. XMLHttpRequest doesn't work locally.

   Your web application runs as a file, not on a localhost webserver. Attempting to load a local XML, JSON, or HTML file will fail for security reasons. However, files loaded from an external website work as expected.

2. File I/O is tricky.

   PhoneGap provides file read and write access for Android with some important exceptions. You can write to two places on an Android device (/sdcard and /data/data/com.yourpackagename), but you should only expect read and write access to /sdcard. Locked devices cannot see the contents of your application's data directory. You should only read and write to /sdcard and that you should not expect your application to be able to access other files within your application using this method.

3. Use iFrames and separate pages instead of dynamically loading local files.

   In the example application, I wanted to load the individual surfer biographies from external HTML files.

4. HTML 5 database storage isn't supported. yet.

   While Android's browser does, Android's WebView doesn't. Fortunately, support is coming in Android 2.0 and PhoneGap will implement it.

5. WebKit doesn't support E4X.

   So parse XML the old fashioned way.

Comments