12. Using PhoneGap Build
Before the Cordova CLI became available, building Cordova applications for multiple device platforms was a challenge. You had to install the native SDK for each mobile device platform you were supporting and copy your Cordova application’s web application content from project to project. You couldn’t build or test multiple apps simultaneously. The CLI fixes much of that, but there are still limitations.
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, then upload the files to the cloud and let PhoneGap Build do the rest. You still need to have at least a Macintosh computer to create the appropriate mobile OS application signing keys, but the work required to set up a development environment is greatly reduced.
In this chapter, I show you how to set up and use the PhoneGap Build service to package your Cordova applications and share those applications with others. There’s a lot to PhoneGap Build, so I couldn’t cover it all here. This chapter focuses on the Build service and how to use it, not the device platform-specific intricacies.
What Is PhoneGap Build?
PhoneGap Build (https://build.phonegap.com/) is a cloud-based build service for PhoneGap applications. It is a commercial offering from Adobe; there’s a free version of the service plus for-fee options that offer more capabilities.
With Build, a developer loads web application content into an Application definition on the Build server, and the service will automatically build a native application for each of the supported mobile device platforms. Figure 12.1 illustrates how the Build service works.
PhoneGap Build used to support a wider range of target platforms but currently supports packaging applications for only the following mobile device platforms:
Android
iOS
Windows Phone 8
There are many features of the service, many of which will be described later in the chapter. For developers evaluating using the service, there are a few key ones that will be discussed in the following sections.
Quick Prototyping
PhoneGap Build enables a developer to quickly build a web application and deploy it into native applications for multiple mobile device platforms without having a complete, local development environment. This gives designers a quick way to flesh out a concept without having to spend time downloading and configuring mobile SDKs. While this prototyping can be easily done using a mobile web browser, if it is a requirement that the application be distributed in the Cordova (or PhoneGap) container, PhoneGap Build helps jump-start the process.
Once a concept has been validated, the web application source code can be passed on to a developer to add data integration and other complex aspects of the application later. The developer can continue to use the Build service or can switch over to the CLI and local copies of the native SDKs for continued development.
Collaboration
While version control systems allow developers to collaborate on their development projects on-premise or in the cloud, Build allows you to configure a project so others can work on the same PhoneGap Build project with you. You have the ability to define testers who get read-only access and developers who get read/write access.
This feature allows you to provide a private, hidden area of Build where you can collaborate with others and provide them with access to build results so they can easily test your applications as you develop them.
Content Refresh through Hydration
One of the reasons why many developers use Build is so that they can provide testers with a quick and simple mechanism for updating an application they are testing. Mobile application testers are used to having to update native applications on their test devices as they move from app version to app version, but PhoneGap Build makes this process simpler through a feature called Hydration (http://goo.gl/5cCZcK).
When a developer enables Hydration on a PhoneGap Build application, the Build service creates a version of the application that, instead of having its web content packaged within the application, receives its web content directly from the Build server. This feature significantly improves application build time and allows web content updates to be repeatedly deployed to the PhoneGap application over the air, whenever the application launches and a new version is available.
When a developer uploads a new version of the web application content to the Build service, the content is packaged for delivery (instead of the whole native application being packaged). The next time users open the application, the application will notify them that a new version of the application’s content is available. Users can download the update or continue to work with the version of the application they already have.
The Hydration feature is really designed to support the testing process for mobile applications; you shouldn’t try to use this feature with your production applications. For enterprise applications that need this feature, you may want to take a look at the SAP Mobile Platform (SMP); its Hybrid SDK (Kapsel) provides an over-the-air web content update for production applications.
Hydration is supported in PhoneGap 2.0 and higher, and the capability is available for Android and iOS applications.
Using PhoneGap Build
In this section, I’ll show you how to use the PhoneGap Build service. I’ll start by showing you how to create a PhoneGap Build account, and then I’ll walk you through a quick example of creating a PhoneGap application using Build and show you how to leverage more of the configuration options for the service. It all starts by opening your browser of choice and pointing it to the Build service at http://build.phonegap.com/ as shown in Figure 12.2.
If you have an existing Adobe Creative Cloud account, you can sign in using the credentials you already have. If not, you can create a new account or sign in using your GitHub account credentials. Once you’re in, you’ll be able to select your plan from the available choices. The free plan is limited to one private app, but the paid options are more flexible.
A Quick Example
Before I show you all of the intricacies of PhoneGap Build, I thought I’d throw together a quick example. At the barest minimum, all PhoneGap Build needs to have in order to create a mobile application for each supported mobile device platform is just a single HTML file. To prove this, I created a quick HTML5 application, shown in Listing 12.1.
Listing 12.1 Simple index.html File
<!DOCTYPE HTML>
<html>
<head>
<title>PhoneGap Build Example</title>
</head>
<body>
<h1>PhoneGap Build Example</h1>
<p>This is a simple Apache Cordova application to use to demonstrate uploading an
index.html file to PhoneGap Build. Not very exciting, is it?</p>
</body>
</html>
Next, I signed into the PhoneGap Build web site. If you don’t have any applications defined on the system, PhoneGap Build will open to a page where you can create your first application. Otherwise, click the + new app button on the Build home page to create a new application.
In either case, the Build service will open the page shown in Figure 12.3; here you can either provide a URI for a Git repository or upload a file. In this case, the upload button is mislabeled (and I’ve suggested to the Adobe folks that they fix this; more than a year later they still haven’t) because you can upload more than a .zip file—you can also upload an .html file like the one I just showed you. Regardless of which approach you want to use, you have to make sure Build has access to the application file(s) you want packaged into a Cordova application.
For this example, I simply clicked the Upload a .zip file button and pointed to the .html file I created. As soon as I finish that process, the Build service will open the new page shown in Figure 12.4. Since I didn’t provide a configuration file (more on that later), Build sets a default application name of PG Build App as shown in the figure. You should change the application name and provide a brief description of your application so you and others will be able to easily recognize it later.
If you check the Enable debugging checkbox, PhoneGap Build will enable weinre debugging in the packaged application (discussed in Chapter 5, “The Mechanics of Cordova Development”). If you check the Enable hydration checkbox, Build will enable the Hydration feature described earlier in the chapter. Figure 12.5 shows the application definition with a more appropriate name and description.
When you have the application settings set the way you want them, click the Ready to build button to start the packaging process. Build will begin the process and display the page shown in Figure 12.6. What the service does at this point is spawn off a few tasks to build native Cordova applications for each supported mobile platform using the web application content you have provided.
The page will show the platform icon for each supported mobile device platform; you should be able to easily recognize them. Applications with blue icons (not shown) have completed, and red icons indicate that the build has failed.
The build process fails sometimes because of glitches with the Build service. Simply click the Rebuild all button to redo the build, and it usually fixes itself. In this example, though, the build is failing for a specific reason: the application signing keys needed to complete the build process have not been defined for this application.
If you click on the application title in Figure 12.6, or one of the mobile platform icons on the lower-left side of the figure, the Build service will open a page similar to the one shown in Figure 12.7. From this page, you can see more details about the particular application. In this example, you can see where applications have been built successfully and where the build has failed.
When you click any of the Error buttons, the page will expand an area beneath the button and display the error that caused the build to fail; an example of the iOS failure is shown in Figure 12.8; the iOS build failed because of signing key problems.
Most mobile device platforms have some sort of signing process that must be completed before an application can be deployed to a device or into an app store. Apple is much more restrictive than other platforms, so you can’t accomplish anything here without providing keys. Most other platforms either don’t require a key or allow you to build with or without one.
To resolve the build issue, provide the necessary signing key(s) and rebuild the application. To do this, click the appropriate drop-down menu next to the operating systems that have failed as shown in Figure 12.7 and add your keys to the project as shown in Figure 12.9.
When you create the keys, you’re able to provide a title for the key set. This allows developers who work for multiple customers to define signing key settings for different projects or customers and select the appropriate key(s) depending on the scenario.
When you have the appropriate keys added to the project, simply click the individual Rebuild buttons or the Rebuild all button to start the process of rebuilding the application.
On the same page are additional options for the application. The Plugins tab shown in Figure 12.7 (but not displayed) allows you to view information about the plugins that have been added to the application. You will learn how to add plugins to your project later in the chapter.
The Collaborators tab shown in Figure 12.10 allows you to list one or more people who work with you on the project. As shown in the figure, to add a collaborator, click the Add a collaborator button, then provide the email address for the collaborator and identify whether the user will only be allowed to download the application (testers) or can make updates to the application (developers). The collaborators’ email addresses must be associated with PhoneGap Build accounts in order for them to access the system.
The application Settings tab contains general settings for the application. The Basic area shown in Figure 12.11 allows you to update the source for the application as well as to set some properties of the application.
The Configuration section of the Settings page shown in Figure 12.12 allows you to set some application properties. The values shown here can be entered manually by the developer as I’ve done here, but later, when we talk about the application’s config.xml, you’ll see that these values can also be defined with the application content and uploaded to the service.
In the example I’ve shown, I’ve simply uploaded an index.html file containing my application’s simple content. Very few Cordova or PhoneGap applications consist of an index.html file and nothing more. For most applications, you’ll package all of the web application content into a .zip file and upload that to the Build service for packaging. I would show you how that works here, but there’s really not much to it—you zip the files up, using whatever tools you want to use to do the packaging, and upload the .zip file instead of the .html file as I showed earlier. Everything else is the same.
When you zip the files, you’ll want to make sure that the project folder is maintained underneath the project’s start page (typically an index.html page). The start page has to be in the root of the archive, and any other required subfolders containing code needed by the application should be included as well. An example of a .zip archive for one of the sample applications from Chapter 17, “Using Third-Party UI Frameworks with Cordova,” is shown in Figure 12.13.
Configuring a PhoneGap Build Application
As shown in the previous section, 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.
In the previous example, I uploaded just a single .html file to the service and it built the application for me. If I create a properly configured config.xml and include it in a .zip file with all of the web application’s content, the service will use the config.xml file to set many of the properties and security settings for the application. The .zip file can contain just the index.html I used in the previous example, or it can be a complete web application with .html files, JavaScript code, CSS files, and more as I showed in Figure 12.13. It doesn’t matter what the complexity of the app is, as long as it is packaged into a .zip file with the config.xml; the Build service should be able to package it into native Cordova applications for you.
The CLI will generate a config.xml file for you automatically when it creates a Cordova project. Listing 12.2 shows the config.xml file created by the CLI for the Hello World #3 application highlighted in Chapter 2, “Anatomy of a Cordova Application.”
Listing 12.2 Default Cordova Project config.xml File
<?xml version='1.0' encoding='utf-8'?>
<widget id="com.ac4p.ex23" version="0.0.1"
xmlns="http://www.w3.org/ns/widgets"
xmlns:cdv="http://cordova.apache.org/ns/1.0">
<name>Ex2.3</name>
<description>
A sample Apache Cordova application that responds to the deviceready event.
</description>
<author email="[email protected]" href="http://cordova.io">
Apache Cordova Team
</author>
<content src="index.html" />
<access origin="*" />
</widget>
The example config.xml file lists a limited amount of information needed to describe the application and a little bit about the application’s preferences. If you updated the application name and author information in that file, packaged the config.xml into an archive, and uploaded it to PhoneGap Build, you would see that the new application project would be created using those settings.
The PhoneGap Build config.xml file can be pretty complicated. It has to contain settings that apply across multiple device platforms such as settings for application icons, splash screen graphics, and more. It also has to accommodate specific security settings that need to be enabled depending on which PhoneGap APIs are used. I’m not going to go into the details of all of the possible settings for the config.xml; they’re all clearly documented in the PhoneGap Build Docs located at http://docs.build.phonegap.com/ and updated regularly when new capabilities are added.
It’s never fun to edit an XML file, and since the PhoneGap Build service supports so many options, it’s hard to make sure that you have all of the settings you need and that they’re set correctly. To simplify this for you, an industrious developer published an application called ConfiGAP (http://configap.com/) that provides a simple interface you can use to define all of the settings you need in a PhoneGap Build config.xml file. The application is free and can be downloaded from the provided URL. The application is an Adobe Air application, so you’ll need to have Air (http://get.adobe.com/air) installed in order to run the application.
When you run the application, you’re prompted to either create a new config.xml or open an existing one. When you select the appropriate option, you will be presented with a screen similar to Figure 12.14. From this panel, you can set general settings for the application, some of the same settings I showed in Figure 12.2.
Across the top of the window are tabs you can select to access other settings. Figure 12.15 shows the contents of the Advanced Settings tab; you would use these settings to control how the application renders and operates on a mobile device.
One of the things the Cordova CLI does for you that you used to have to do manually is manage the permissions settings for device-side capabilities exposed by the Cordova APIs. When a developer adds a plugin to an application that utilizes the Camera or some other native capability, the device OS expects that the developer has identified that he or she is using the API so that it can tell during installation what it needs to prompt the user for permission. If the permissions are not set correctly, even though you might have a plugin such as Camera added to the application, the camera functionality won’t work.
The ConfiGAP Permissions tab, shown in Figure 12.16, includes options for setting the necessary API permissions as well as allowing you to define the domain whitelist described in Chapter 5.
And finally, Figure 12.17 shows the content of the Plugins tab; here you can enable the plugins that will be added to your project by the build process. I’ll explain how plugins work with the PhoneGap Build service in the next section.
Listing 12.3 shows the complete config.xml file generated by ConfiGAP; all of the settings I enabled in the application are represented here.
Listing 12.3 PhoneGap Build config.xml File Generated by ConfiGAP
<?xml version="1.0" encoding="UTF-8" ?>
<widget xmlns="http://www.w3.org/ns/widgets"
xmlns:gap="http://phonegap.com/ns/1.0" id="com.johnwargo.debug"
versionCode="1.0.0" version="1.0.0">
<name>Cordova Debug</name>
<description>
A simple application designed to be used to demonstrate Cordova
application debugging tools.</description>
<author href="www.johnwargo.com" email="[email protected]">
John M. Wargo
</author>
<preference name="phonegap-version" value="3.6.3" />
<preference name="orientation" value="default" />
<preference name="fullscreen" value="false" />
<preference name="target-device" value="universal" />
<preference name="webviewbounce" value="true" />
<preference name="prerendered-icon" value="true" />
<preference name="stay-in-webview" value="true" />
<preference name="ios-statusbarstyle" value="default" />
<preference name="detect-data-types" value="true" />
<preference name="exit-on-suspend" value="false" />
<preference name="show-splash-screen-spinner" value="true" />
<preference name="auto-hide-splash-screen" value="true" />
<preference name="EnableViewportScale" value="true" />
<preference name="MediaPlaybackRequiresUserAction" value="false" />
<preference name="AllowInlineMediaPlayback" value="false" />
<preference name="BackupWebStorage" value="cloud" />
<preference name="TopActivityIndicator" value="gray" />
<preference name="KeyboardDisplayRequiresUserAction" value="false" />
<preference name="HideKeyboardFormAccessoryBar" value="false" />
<preference name="SuppressesIncrementalRendering" value="false" />
<preference name="android-minSdkVersion" value="17" />
<preference name="android-targetSdkVersion" value="17" />
<preference name="android-installLocation" value="internalOnly" />
<preference name="SplashScreenDelay" value="5000" />
<preference name="ErrorUrl" value="" />
<preference name="BackgroundColor" value="0x000000" />
<preference name="KeepRunning" value="true" />
<preference name="DisallowOverscroll" value="false" />
<preference name="LoadingDialog" value="," />
<preference name="LoadUrlTimeoutValue" value="20000" />
<preference name="disable-cursor" value="false" />
<gap:platform name="ios" />
<gap:platform name="android" />
<gap:platform name="winphone" />
<feature name="http://api.phonegap.com/1.0/camera" />
<gap:plugin name="org.apache.cordova.camera.CameraLauncher" />
<gap:plugin name="org.apache.cordova.console" />
<gap:plugin name="org.apache.cordova.device.Device" />
<gap:plugin name="org.apache.cordova.dialogs.Notification" />
</widget>
You could make a custom config.xml file for each project, or you can create one base config.xml file and edit it as needed per project.
Adding Plugins to a PhoneGap Build Project
As described in Chapter 1, “The What, How, Why, and More of Apache Cordova,” Cordova (and PhoneGap, of course) applications are all about access to native capabilities. These capabilities are typically exposed to an application through plugins. I’m not sure what limitation drives this, but PhoneGap Build supports only a subset of the available plugins. You can find a list of the supported plugins in the PhoneGap Build plugins repository (https://build.phonegap.com/plugins).
The repository contains a good-size catalog of plugins, plus you can submit your own for approval. In order for PhoneGap Build to be able to accept your plugin, you must agree to a license and your plugin must conform to the following requirements:
Must be a Cordova plugin compatible with Plugman (described in Chapter 4, “Using the Cordova Command-Line Interfaces”)
Must be licensed under the Apache 2.0 or MIT license
Must be distributed as source code only and contain no binary code
Can be no larger than 15MB
Plugins are added to a PhoneGap Build project through the config.xml file as described at http://goo.gl/g3iBOM. For each plugin, you must add a gap entry as shown in the following example:
<gap:plugin name="plugin_name" />
As an example, to add the Cordova Device plugin to an application, you would add the following entry to the project’s config.xml:
<gap:plugin name="org.apache.cordova.device.Device" />
You can see an example of this entry in a real config.xml in Listing 12.3.
You can also specify a specific version of a plugin by adding a version attribute to the XML element:
<gap:plugin name="plugin_name" version="plugin_version" />
So, to lock the Device plugin example to a specific version, use
<gap:plugin name="org.apache.cordova.device.Device" version="0.2.22" />
As you’ll see in Chapter 16, “Creating Cordova Plugins,” the plugin reference in the config.xml can include additional parameters that are used to configure the plugin:
<gap:plugin name="com.johnwargo.myplugin">
<param name="Param1" value="42" />
<param name="DebugMode" value="true" />
</gap:plugin>
With the appropriate entries added to the config.xml and the plugin listed as an approved plugin in the Plugin Registry, the PhoneGap Build service should be able to add the plugin(s) to the application and complete the build process.
Deploying PhoneGap Build Applications
When the build process completes, it will provide you with access to the packaged applications for each of the supported mobile device platforms. You can deploy these applications to mobile devices in different ways, depending on what is supported by the device manufacturer and even the mobile carrier. In this section of the chapter, I’ll show you in general how to deploy the applications; you will have to refer to the specific documentation for each mobile device platform to determine which options are appropriate for the platform.
The simplest way to deploy an application built using PhoneGap Build is to grab a compatible device and use a code-scanning application on the device to scan the Quick Response (QR) code shown in the upper-right corner of Figure 12.7. The code-scanning application will convert the scanned code into a URL and open the web page on the mobile device. All the user has to do is follow the instructions on the web page to initiate the application download and installation.
Each mobile device platform has restrictions on what can be loaded directly onto a device, so you may have to change settings on the device to allow the application installation. Android, for example, has an issue with downloading applications from unknown sources, but a quick configuration change can enable it. The setting is typically in the Security area of the Settings application and should refer to Unknown Sources. You can see an example of the setting in Figure 12.18.
In some cases, you will want to have access to the native application executable file. In this case, you can download the packaged application directly to your development system. If you take another look at Figure 12.7, you’ll see that there are buttons to the right of each mobile device platform shown at the bottom of the figure. If you click the button for a particular mobile device platform, the browser will download the appropriate files for the platform, downloading an .apk file for Android, a .xap file for a Windows application, and so on.
You can also click the Install button immediately below the QR code shown in Figure 12.7 to be taken to another page where you can download all of the application files directly as shown in Figure 12.19.
Once you have the application files downloaded, you can distribute the applications to others and deploy the applications directly to supported devices.
To test these applications on one or more device simulators, you can open the mobile browser on the simulator, then navigate and log in to the PhoneGap Build service using your credentials. If the simulator supports it, you can click the Install link and download the application’s files directly to the device from the site as shown in Figure 12.20.
Modern Android devices might warn the user about the risks of downloading the file as shown in Figure 12.21.
When you install the application, you may be prompted to enable features of the application as shown in Figure 12.22. Even though I’ve built only a simple application that doesn’t even use any of the PhoneGap APIs, since I didn’t tell the Build service what to enable or disable, it simply enables all features by default. This is related to the settings on the Permissions tab of ConfiGAP shown in Figure 12.16 and the corresponding config.xml settings shown in Listing 12.3.
The user will need to step through the pages here before being able to install the application.
Wrap-Up
In this chapter, I showed you how you can use the PhoneGap Build service to package and deploy your web applications into the PhoneGap container. You should look at leveraging this service if you don’t want to worry about managing multiple SDK installations or if you need an easy way to build and share your applications with a distributed audience of testers.