Creating an app with PhoneGap Build – Part 3: Using PhoneGap Build
This is the third part in a series of posts detailing the process of building an HTML5 based website and converting it into an Android app via PhoneGap Build. In this post, I’ll review the PhoneGap Build process.
Preparing the Site for PhoneGap Build
As you recall, I created a single-page HTML5 web site targeted to mobile browsers using the jQuery Mobile framework. In order to compile a website into an installable Android app, you need to create a PhoneGap Build project and configure your web site for PhoneGap Build.
Configuring a website for PhoneGap Build starts by verifying that the landing page is named index.html. By convention, PhoneGap Build will look for this file and set it as the main screen for your app. The other file you’ll need is a config.xml file. This file is PhoneGap Build specific and contains all the PhoneGap and general app settings for your resulting app.
The PhoneGap Build documentation suggests cloning a sample website they have that contains a config.xml file for you to use as a base template. The config.xml documentation spells out in detail all the attributes of the config.xml file. At the very least, you’ll want to personalize the name, description, and id of your app in the config file. There are many other available values that will all use default values if they’re not defined in the config.xml. For instance, if you don’t specify an app icon, you’re output will use the PhoneGap icon. Here is the config.xml for the TRINUG app; you’ll notice that it has Android-specific icon assets defined:
<?xml version="1.0" encoding="UTF-8"?> <widget xmlns = "http://www.w3.org/ns/widgets" xmlns:gap = "http://phonegap.com/ns/1.0" id = "org.trinug.mobile.phonegap" version = "1.0.1"> <name>TRINUG</name> <description> Triangle .NET User Group </description> <author href="https://github.com/justinsaraceno" email="firstname.lastname@example.org"> Justin Saraceno </author> <preference value="1.7.0" name="phonegap-version"/> <!-- icons --> <icon src="icon_057.png" gap:role="default" /> <icon src="Content/images/icons/android/ldpi.png" gap:platform="android" gap:density="ldpi" /> <icon src="Content/images/icons/android/mdpi.png" gap:platform="android" gap:density="mdpi" /> <icon src="Content/images/icons/android/hdpi.png" gap:platform="android" gap:density="hdpi" /> <gap:splash src="splash.png" /> <gap:splash src="splash/android/ldpi.png" gap:platform="android" gap:density="ldpi"/> <gap:splash src="splash/android/mdpi.png" gap:platform="android" gap:density="mdpi"/> <gap:splash src="splash/android/hdpi.png" gap:platform="android" gap:density="hdpi"/> <!-- api access --> <feature name="http://api.phonegap.com/1.0/network"/> <access origin="*" /> <preference name="orientation" value="default" /> </widget>
Creating a PhoneGap Build Project
Once your web site’s files are in place, it’s time to create an account at build.phonegap.com. As of this writing PhoneGap Build is in beta status and non-beta pricing hasn’t been made official. The TRINUG app is open source so I was able to create it under the free tier. Being under the free tier exposes the compiled install file to anyone who can find it. If there was a need to protect the install, the free tier still allows for one private app.
The PhoneGap Build setup process prompts for the source of your website. The options are to upload a single index.html file, upload a zip file containing the contents of your website, or linking to a source control repository. Since the TRINUG site is hosted on GitHub, I created a link to the repo’s HTTP location as defined in the repo’s public GitHub page:
Once your source is submitted to PhoneGap Build, a project control panel will allow you to manage your application:
From the control panel you are given the option to update your code, rebuild the code, go to a public download page of your app, or download the various platform-specific installs of your compiled app.
Installing the Output on the Phone
At this point the Android build is compiled in to a valid install-able .APK file. It’s not Google Play marketplace ready since it isn’t signed, but you can still install it on your Android device. First, prepare your device by going to your device’s Settings and choosing ‘Applications’. From here, check the checkbox for ‘Unknown sources’ to allow for the install of non-Market applications. At this point you can scan the QR code for the Android build of your application which will open a browser and download the install file. You’ll be able to tell when it’s downloaded by a status message in the Android system tray. At this point you’ll be able to run the install.
In the following post, I’ll detail debugging your PhoneGap Build generated app.