9. Using PhoneGap Build
As you can see from the previous chapters, building PhoneGap applications for multiple mobile platforms can be a challenging endeavor. You have to install each platform’s SDK, as well as IDEs, build tools, simulators or emulators, and more. As you read through the chapters, you probably said to yourself, “There has got to be an easier way!” Fortunately, there is. The PhoneGap Build service provides the means to build PhoneGap applications in the cloud, without the need to install a bunch of software on a developer workstation. All you have to do is write your web applications using your web content editor of choice, upload the files to the cloud, and then let PhoneGap Build do the rest.
PhoneGap Build currently supports the following mobile platforms:
• Android
• BlackBerry
• iOS
• Symbian
• webOS
This chapter will describe how to use the PhoneGap Build service. It’s important to note that the service is still in beta and the UI for the service changes dramatically on a regular basis. By the time you read this, it will look completely different, although the process should be about the same (or similar) to what is described here.
The Fit
You may be asking yourself if PhoneGap Build is so cool, why would you ever want to use the individual development SDKs to build your PhoneGap applications? With PhoneGap Build still in beta, there’s no clear information regarding how widely adopted it will be by the PhoneGap community. The fact that it’s going to be a for-fee service might also affect adoption of the service.
As you’ll see later in the chapter, PhoneGap Build currently uses a single application icon and a single splash screen image for all versions of the application (except for iOS). If your application needs a different branding or look and feel on different platforms, then you will need to use the native SDK approach rather than PhoneGap Build.
In my testing of the service, I found that the build process could be quite slow, although this could have been caused by the service’s beta status. With Build, the process of getting the built application onto a device, emulator, or simulator was more cumbersome than it would be on some platforms using native SDKs or even command-line tools. On platforms like Android or iOS, since there’s an IDE to work with, saving your code and then building and deploying to a simulator or emulator takes a matter of seconds.
If you’re like me, you’ll write code and then save and test regularly; the delays caused by using Build could extend the length of time you spend working on the application.
On the other hand, as I worked on the chapters that followed, I found that building a single application and uploading it to the Build service in order to generate applications for multiple platforms made it very easy to put each sample application through its paces on multiple mobile platforms simultaneously. Without access to the Build service, it would have taken me much more time to accomplish what I needed for this book.
Getting Started
Before you can use PhoneGap Build for your PhoneGap projects, you must first create an account on the PhoneGap Build web site. Point your browser of choice to http://build.phonegap.com to begin the process. PhoneGap Build is free during the beta period but will switch to a for-fee service when it’s released into production. Table 9-1 lists the planned pricing options for the service.
Table 9-1 PhoneGap Build Pricing Structure
Configuration
Several of the mobile platforms that PhoneGap Build supports require that applications are digitally signed before they can be loaded on devices or deployed to the appropriate application stores. For that reason, you must configure the PhoneGap Build service with the appropriate signing keys for each of the supported platforms.
For Android and BlackBerry devices, the PhoneGap Build process will work without any signing keys, but you will want to configure your specific keys for those platforms before releasing an application for distribution through an application store. Android applications require only a signature before deployment to the Android Market. BlackBerry applications will not run on a device without being signed. By default, PhoneGap Build signs BlackBerry applications using Nitobi’s signing keys, with the expectation that you will provide your own signing keys before releasing the application to distribution.
For iOS development, Apple tightly controls the signing process and severely limits what a developer can do with an application. For this reason, PhoneGap Build will not even build an iOS application without the appropriate developer credentials first being configured in PhoneGap Build.
To configure signing keys in PhoneGap Build, open your browser of choice, and then log into the PhoneGap Build web site using the credentials you supplied when creating an account. Click the “Edit account” link currently located on the bottom of the page. PhoneGap Build will open a page similar to the one shown in Figure 9-1.
Figure 9-1 PhoneGap Build: account configuration
For each of the platforms you will be supporting that require application signing, click the “Add a key” link. PhoneGap Build will open a dialog similar to the one shown in Figure 9-2. Depending on the mobile platform, you may need to upload multiple files as shown in the figure (Android uses only a single file; BlackBerry and iOS require two). Provide a title for the set of keys, select the appropriate files as needed, and click the Create button. Repeat this process as many times as needed for each set of keys you will be using and each platform you will be supporting.
Figure 9-2 PhoneGap Build: key file upload dialog
While a particular developer might need only a single set of keys for Android and BlackBerry applications, the title field shown in the dialog allows you to give a unique name to each set of keys being defined within PhoneGap Build. Since a developer may be building applications for multiple customers and each customer will have a specific set of keys, this allows a developer to define settings for each set of signing keys they work with and then pick the appropriate keys to use on an application-by-application basis. Since Apple’s provisioning profiles are associated with one or more iOS devices, a developer might define different sets of keys depending on which devices will be working with a particular build of an application (during testing for example), switching to a publically distributable profile before releasing through Apple’s App Store.
Once you’ve defined a set of keys for a particular platform, you can configure PhoneGap Build to use that key as the default key for the platform. To enable this feature, in the list of keys shown in Figure 9-1, simply enable the Default radio button (not shown in the current figure) next to the key you want to use as the default for the selected platform.
Creating an Application for PhoneGap Build
When working with PhoneGap Build, a PhoneGap application can be nothing more than a simple index.html file or as complicated as a folder containing the index.html file plus additional JavaScript, CSS, media files, and any additional content the application needs. The application in this case is simply the web content files, nothing else. Unlike what you saw with configuring an application for any of the supported mobile platforms individually, with PhoneGap Build there don’t have to be any special files or special folder structures for the application. All you have to do is get the web content up to the PhoneGap Build server, and it takes care of everything else for you.
Chapter 2 explained that the PhoneGap JavaScript file was named differently depending on which mobile platform you were working with, but with PhoneGap Build your application simply has to make a reference to a generic phonegap.js file, as shown next. You don’t even need to include the phonegap.js file in the package uploaded to the server; PhoneGap Build will make sure the latest version of PhoneGap is copied over and used by the project.
<script type="text/javascript" charset="utf-8"
src="phonegap.js"></script>
PhoneGap Build will use default settings such as application icon, splash screen, security settings, and more unless you tell it differently. To configure application-specific settings for your PhoneGap application, PhoneGap Build uses the config.xml file defined as part of the W3C Widget Packaging and XML Configuration specification described in Chapter 5.
The specification includes the means to define a single set of application icons (a home screen and optionally, for BlackBerry, a hover image) and a loading screen (splash) image. Unfortunately, application icon resolution (and sometimes graphics file format) varies across mobile device platforms and even across mobile devices. To fix this particular problem (and others), the PhoneGap Build developers have implemented some PhoneGap and PhoneGap Build–specific settings to the options available in the config.xml file.
As of this writing, the PhoneGap Build development team is still making enhancements to the features, options, and configuration settings for the service. Because of this, it’s best to refer to their up-to-date documentation for specifics on the supported config.xml file options. Anything I wrote here about those settings could be nullified at any time by the PhoneGap Build development team. Detailed information about the PhoneGap Build–supported settings can be found at http://build.phonegap.com/docs/config-xml.
One of the things I learned when working with the service is that when building applications for iOS, PhoneGap Build requires that the config.xml file’s widget element contains an id attribute that contains a unique in reverse domain format, as shown in the following example:
<widget xmlns=http://www.w3.org/ns/widgets
xmlns:rim=http://www.blackberry.com/ns/widgets
version="1.0.0.0" id="com.phonegapbook.kitchensink">
If you don’t have that setting defined, the application will not build.
Creating a PhoneGap Build Project
When the PhoneGap web application is ready, it’s time to upload the files and start the build process.
Upload Options
PhoneGap Build supports several mechanisms for delivering the application’s files to the build server:
• Index.html Upload: For applications that don’t use any external Java-Script, CSS, or media files, simply upload the index.html file to the PhoneGap Build server. PhoneGap Build will build the application using default settings for all options.
• Zip Upload: For applications that consist of more than one content file (optionally including the config.xml file), compress the application’s files into a zip file and upload to the PhoneGap Build server.
• Pull from Repository: PhoneGap Build retrieves the application’s files from a public Git or Subversion repository. You can even create a new Git repository, hosted by PhoneGap Build, while creating a new PhoneGap Build project.
New Project
When you log into PhoneGap Build and there are no applications defined, PhoneGap Build will prompt you to create a new application project, as shown in Figure 9-3. If adding an additional application project to your account, click the Apps menu item at the top of the page, and then click the New App button.
Figure 9-3 PhoneGap Build: new project dialog
In the dialog, specify a name for the application and the method you’ll use to provide Build with the application’s web content files. The “enable debugging” option will be described later. Depending on which option is chosen for “select upload method,” you will be prompted either to provide the files for upload or for information related to the repository where the application’s files are or will be stored. When everything is set correctly, click the Create button to start the build process. PhoneGap Build will update the page to indicate build status as the process runs, as shown in Figure 9-4.
Figure 9-4 PhoneGap Build: waiting for the build to complete
The Build Process
Unless you have a default key configured for iOS, PhoneGap Build will immediately register an error (the exclamation point icon shown in Figure 9-4) for the iOS application because PhoneGap Build doesn’t have any provisioning profile for the application. You’ll see how to fix that error later. In a few seconds, or a few minutes, depending on how busy the PhoneGap Build servers are, the screen will update to show that the build process has completed for each platform, as shown in Figure 9-5.
Figure 9-5 PhoneGap Build: build complete
Project Configuration
Click on the application’s name to view details for the application project. PhoneGap Build will display a page similar to the one shown in Figure 9-6.
Figure 9-6 PhoneGap Build: application details
If you included a config.xml file with your application’s content files, PhoneGap Build will ignore the project title you supplied when you created the project and instead use the value specified for the config file’s Name element. The application’s description, displayed in Figure 9-6, will be populated from the config file’s Description element.
From this page you can download or install the application executables for each supported mobile platform; this will be described later in the chapter. For now, let’s fix the issue with the iOS application.
The warning symbol shown for the iOS application is indicating that the appropriate signing information has not been defined for the application. To fix this problem, click the Edit button at the top of the page; then on the page that opens, click the Signing button. PhoneGap Build will display a page similar to the one shown in Figure 9-7.
Figure 9-7 Setting the signing options for the application
For each of the operating systems, select a key from the drop-down list shown in Figure 9-7, and click the Update Code button to save your changes and build the application with the selected signing keys.
Dealing with Build Issues
When the build service encounters an error building an application for a particular platform, it will display a frowny face for the particular application’s build status, as shown in Figure 9-8. In this case, it’s indicating that the BlackBerry build process failed.
Figure 9-8 PhoneGap Build: build errors
If you hover your mouse over the frowny icon, the page will display information about the error, as shown in Figure 9-9. If you click the icon, a page will open that lists possible error conditions and recommended solutions for each.
Figure 9-9 PhoneGap Build: build error information
At this point, you will need to dig into the error condition and resolve the problem before continuing. With the service still in beta and the Nitobi folks still working out the kinks, sometimes simply rebuilding the application solves the problem.
As indicated in Figure 9-9, the BlackBerry build process found that there were invalid characters in file names within the application. This particular error has popped up inconsistently with the applications I’ve built using the service. If you looked at the application’s content, you would see that the file names for jQuery Mobile have dashes in them. If you remove the dashes from the file names, update index.html to reflect the file name changes, and upload the updated content to the Build service, you should see that the application builds correctly.
The problem, though, is that this particular issue doesn’t occur with every application; it’s hit-or-miss whether this will occur with any particular build. Additionally, the BlackBerry WebWorks Packager utility (described in Chapter 5), the utility actually doing the build for BlackBerry, doesn’t have any issues with dashes in a file name. This is a clearly a bug with PhoneGap Build that has been in place for a very long time, and I hope it will be addressed before the service goes live or soon thereafter.
Testing Applications
You can load applications created by PhoneGap Build onto a device, simulator, or emulator in several ways.
OTA Download
When the PhoneGap Build process completes, the application’s entry on the service’s web site contains links to the individual application executables for each supported platform, as shown in Figure 9-10. On platforms that support application downloads, on a physical device, or from a device simulator or emulator, you can open a web browser, navigate to the PhoneGap Build web site, log in, and then download the application directly.
Figure 9-10 PhoneGap Build: application download buttons
For Android, Symbian, and webOS, the download link points directly to the application executable, so if you want to download the file first from a desktop browser and then transfer the file to a device for testing, that’s not a problem. For BlackBerry, it points you to the application’s .jad file, which is essentially a text file pointing to the installation executable. If you configure signing keys for the BlackBerry application, a link will be provided that allows you to download the installation files separately.
You will also find similar links on the application details page shown in Figure 9-6.
Via Camera
You can also load an application using a code-scanner application on a compatible smartphone. Many smartphone models ship with some sort of code-scanning application preinstalled. If one is not preinstalled, several free code scanner applications are available in the smartphone app stores; AT&T even offers a free one for many common mobile platforms at www.wireless.att.com/businesscenter/solutions/mobile-marketing/mobile-barcode-download.jsp.
To view an application’s code, open the application’s details page shown in Figure 9-6. For each platform, PhoneGap Build displays a two-dimensional code, as shown in Figure 9-11. To load the application on a physical device, launch a code-scanning application on the device, and point it at the appropriate code for the operating system the device is running. When the scanner application recognizes the code, it will launch the browser and open the downloadable version of the application.
Figure 9-11 PhoneGap Build: application scan code
Debug Mode
When you enable debug mode for an application, PhoneGap Build leverages the Weinre debug server (described in Chapter 2) to allow you to debug the built application directly on a device. With this feature enabled, PhoneGap Build modifies your PhoneGap application so it includes the Weinre JavaScript library Target-script-min.js and then exposes a debug server within the PhoneGap Build console, which allows you to interactively debug the application. Refer to Chapter 2 for more detailed information on how this process works.
When you look at the details page for an application that has been built with debug mode enabled, a Debug button will appear at the top of the page, as shown in Figure 9-12.
Figure 9-12 PhoneGap Build: debug-enabled application
Click the Debug button to begin a debug session on the server. The browser will open a new window and display the Weinre debug server console. At this point, the debug console is waiting for a debug-enabled version of the application to connect to the debug server. On a compatible, network-connected smartphone, open the browser, navigate to the PhoneGap Build web site, and install the application using the instructions provided in this section; then launch the application once the download has completed. After the application has launched and completed its initialization procedures, the application will automatically connect to the debug server. When the debug server receives a connection from the device, it will update the console with information about the device, as shown in Figure 9-13.
Figure 9-13 PhoneGap Build: Weinre debug console, device connected
At this point, you perform the standard debug functions supported by Weinre. As you interact with the application on the device, you can use the console to view console messages, inspect page elements (shown in Figure 9-14), and more. Refer to Chapter 2 or the Weinre documentation for information on the capabilities of Weinre.
Figure 9-14 PhoneGap Build: Weinre debug console