11. 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.

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 won’t be able to cover it all here. This chapter focuses on the Build service and how to use it, not on the device platform–specific intricacies.

With Build, a developer loads a web application into an Application definition on the Build server, and the service automatically builds a native application for each of the supported mobile device platforms. Figure 11.1 illustrates how the build service works.

Figure 11.1 PhoneGap Build Overview

PhoneGap Build currently supports packaging applications for the following mobile device platforms:

Android

BlackBerry

iOS

Symbian

webOS

Windows Phone

Currently, the service is a little behind on BlackBerry version support, but hopefully, BlackBerry 10 support will be available by the time you read this book. If not, don’t worry—you can still work with BlackBerry 10 using the BlackBerry NDK and the Cordova CLI.

There are numerous features of the service, many of which are described later in the chapter. For developers evaluating using the service, there are a few key ones, which are discussed in the following sections.

Once a concept has been validated, the web application source code can be passed onto 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.

This feature allows you to provide a private, hidden area of Build where you can collaborate with others and give them access to build results so they can easily test your applications as you develop them.

When a developer enables Hydration on a PhoneGap Build application, the Build service creates a version of the application that receives its web content from the build server instead of having its web content packaged within the application. 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 the user opens the application, the application will notify the user 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 Kapsel component 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.

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 11.2.

Figure 11.2 PhoneGap Build Website

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.

Listing 11.1 Sample Single File Web Application

Click here to view code image

<!DOCTYPE HTML>
<html>
  <head>
    <title>Sample Application</title>
  </head>
  <body>
    <h1>Sample Application</h1>
    <p>This is a sample web application.</p>
  </body>
</html>

Next, I signed into the PhoneGap Build website. If you don’t have any applications defined on the system, then 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 11.3; here you can either provide a URI for a Git repository or upload a file. In this case, the upload button label is mislabeled (and I’ve suggested to the Adobe folks that they fix this) because you can upload more than a zip file—you can also upload the .html file 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.

Figure 11.3 PhoneGap Build: Creating a New Application

For this example, I simply clicked Upload a .zip file and pointed to the .html file I created. As soon as I finished that process, the Build service opened the new page shown in Figure 11.4. Since I didn’t provide a configuration file (more on that later), Build set a default application name of PG Build App, as shown in the figure. You should change the application name and provide a brief description for your application so you and others will be able to easily recognize it later.

Figure 11.4 PhoneGap Build: New Application

If you check the Enable debugging checkbox, PhoneGap Build enables weinre debugging in the packaged application; weinre was discussed in Chapter 6, “The Mechanics of Cordova Development.” If you check the Enable hydration checkbox, Build enables the Hydration feature described earlier in the chapter. Figure 11.5 shows the application definition with a more appropriate name and description.

Figure 11.5 PhoneGap Build: New Sample Application

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 11.6. What the service does at this point is spawn off a bunch of tasks to build native Cordova applications for each supported mobile platform using the web application content you have provided.

Figure 11.6 PhoneGap Build: Sample Application Being Built

The page will show the platform icon for each supported mobile device platform; you should be able to easily recognize them. The HP logo is for webOS, and the stylized “i” is for Symbian. Platforms that are being built will be grayed out as the build process progresses. The applications with blue icons have completed, and red icons indicate that the build has failed. I’ll explain why the build failed in a minute.

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 11.6, or on one of the mobile platform icons toward the bottom of Figure 11.6, the Build service will open a page similar to the one shown in Figure 11.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.

Figure 11.7 PhoneGap Build: Application Details

If you click one of the red 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 11.8. In Figure 11.7, both the iOS and BlackBerry builds have failed because of signing key problems.

Figure 11.8 PhoneGap Build: iOS Build Error Details

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 they allow you to build with or without one.

For BlackBerry, Build used to use their own keys to sign a BlackBerry application and allow you to add yours later; in this example, the build is failing because of a password problem with the default keys. Either there is something wrong with the keys, or you can’t build BlackBerry applications anymore without providing your own signing keys.

All you have to do to resolve these build issues is provide the necessary signing keys and rebuild the application. To do this, click the appropriate drop-down menus next to the operating systems that have failed, shown in Figure 11.7, and add your keys to the project. Some keys are global—BlackBerry keys, for example, can be used to sign any application—and some keys are more restrictive, as is the case with iOS application signing.

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.

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 11.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 this. 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 11.9.

Figure 11.9 Enabling Unknown Sources on Android

If you need to make your application available to other users, you can use the Collaborators settings for the application to allow other users to access your packaged applications. You can define collaborators for your application by clicking the Collaborators button, shown in the middle of Figure 11.7, and following the steps that appear, defining an email address for each authorized collaborator. Those users can log in to the PhoneGap Build website using the specified email address and download the applications they’re authorized to access.

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 11.7, you’ll see that there are blue 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 a .xap file for a Windows application, an .apk file for Android, and so on.

You can also click the Install button immediately below the QR code shown in Figure 11.7 to be taken to another page where you can download all of the application files directly, as shown in Figure 11.10.

Figure 11.10 PhoneGap Build: Install Page

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.

When you install the application, you may be prompted to enable features of the application, as shown in Figure 11.11. 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 enables all features by default. I’ll show you in the next section how to configure a PhoneGap Build project so you can leverage a lot more features of the service.

Figure 11.11 Android Application Security Prompt

At this point, you have all of the information you need to get started with PhoneGap Build. In the next section, I show you how to configure an application to make better use of the platform.

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. It doesn’t matter what the complexity of the app is; as long as it is packaged into a standard .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 11.2 shows the config.xml file created by the CLI for the HelloWorld4 application highlighted in Chapter 5, “Anatomy of a Cordova Application.”

Listing 11.2 Default Cordova Project Config.xml File

Click here to view code image

<?xml version='1.0' encoding='utf-8'?>
<widget id="com.cordovaprogramming.HelloWorld4" version="0.0.1"
  xmlns="http://www.w3.org/ns/widgets"
  xmlns:cdv="http://cordova.apache.org/ns/1.0">
  <name>Hello World 4</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>
  <access origin="*" />
  <preference name="fullscreen" value="true" />
  <preference name="webviewbounce" value="true" />
</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.

If you remember from Chapter 8, “BlackBerry 10 Development with Cordova,” I showed how the BlackBerry platform also uses the Widget specification for its applications, and the sample config.xml in Listing 8.1 shows that there’s a whole bunch of additional information provided in the file to help configure security permissions and more for the application. Since the Build service has to accommodate a wider range of mobile platforms and their specific project 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.

Initially, PhoneGap Build supported only a small catalog of plugins. With the release of PhoneGap 3.0, PhoneGap Build added support for a much larger catalog of plugins, along with the ability for developers to publish their plugins to the service so others can use them. This caused a change in the way plugins were identified in the config.xml. Instead of describing all of the config.xml options here, the topic is well covered in the PhoneGap Build documentation at https://build.phonegap.com/docs/config-xml. On that page, you’ll find a detailed description of each of the options for the file plus a pointer to a sample config.xml file you can use for reference or as a starting point for your own applications.