Packaging and Compiling with PhoneGap Build
With HTML5, it’s possible to easily distribute your games over the Web, which can help you reach a wide range of browsers and devices. You’ve seen how adding web applications to the iOS home screen can mimic a native, installed application. An alternative to these web and browser distribution approaches is to use tools such as PhoneGap to package and compile your applications to be installed on devices. They can then be distributed to mobile application stores, such as Apple App Store and Google Play.
In this chapter, you will learn how to use PhoneGap Build to compile and install your applications to a variety of devices. The techniques learned in this chapter will help you develop and prepare your applications for app store distribution, and a few gotchas will be introduced that you’ll run into when using CreateJS applications with PhoneGap.
Introducing PhoneGap Build
PhoneGap is a tool that is used to wrap web applications, built with web standards, into applications that can be installed on devices. There are a few ways to use PhoneGap, and it is loaded with features and compiling options. For the purposes of this book, we will be focusing on one approach, PhoneGap Build. To get started, visit http://build.phonegap.com (see Figure 13-1).
Figure 13-1. The PhoneGap Build web site
If you currently are a member of the Adobe Creative Cloud service, you can have up to 25 active applications free with your account. Each application can be compiled as many times as you like. If you are not currently a member, you can have 1 free application. In any case, you should have no trouble setting up an application to follow along in this chapter.
The benefit in using PhoneGap Build is that it is extremely easy to use. You only need to send up a ZIP file of your application, and PhoneGap Build will take care of the rest. PhoneGap Build supports several platforms, including iOS, Android, and Windows Phone. For the purposes of this chapter, we will be focusing on deploying to iOS and Android.
Acquiring Developer Accounts For iOS and Android
The process of packaging your application and installing on your device for development will be covered in this chapter. Everything from configuring your application files, uploading to PhoneGap Build, and installing on your devices will be reviewed. However, the necessary steps needed to sign up for the various vendor developer accounts will not be covered. Help on acquiring an iOS developer account, as well as obtaining the necessary certificate files needed to package your app, can be found at https://developer.apple.com/ (see Figure 13-2).
Figure 13-2. The iOS Developer web site
When it comes Android development, there are far less restrictions. You can instantly start testing on Android devices built by PhoneGap Build. You can then begin sharing with testers and even start self-distributing. As previously mentioned, application submissions to app stores won’t be covered in this book, but you will need similar developer credentials if you plan on packaging and distributing in Google’s Play Store. For more information, visit https://play.google.com/apps/publish. Figure 13-3 shows the dashboard after logging in with your Google account.
Figure 13-3. The Google Play Developer Console
Updating the Fakezee Game For Packaging
A few things need to be done to the current Fakezee game to prepare it for packaging as an application. First, it will be reformatted visually to better suit portrait orientations on devices. The same assets are used, but various positioning values are updated to lay out the sprites and containers into new positions. We won’t be covering the code for this layout, but you can review it in the source code provided for this chapter. The second adjustment needed for the game to properly be compiled with PhoneGap is the refactoring of asset-loading code. Because PhoneGap uses JSONP to load in data, some code updates will be needed for preloading assets. This code will be covered later in this section.
Adjusting the Visual Layout for Fakezee
The scaling code built in the Chapter 12 will still be used in this application. Because of the various screen sizes on devices between iOS and Android, you’ll still want the game to utilize this logic so it will adjust accordingly. The game will be packaged and configured to stay locked on portrait mode, so some slight adjustments will be made to fill up the screen (see Figure 13-4).
Figure 13-4. Fakzee game elements, adjusted for mobile applications
The background image and canvas sizes were changed accordingly to fit the height of device screens in portrait mode. Some code was also altered to move the game elements to better fit in the new screen format. The game logic and application code has remained the same.
Preloading JSONP for PhoneGap
As mentioned earlier, there are currently some show-stopping conflicts between PhoneGap and PreloadJS. This can cause issues in your application, primarily when it comes to loading data text files. In the case of Fakezee, PreloadJS is being used to load and parse a JSON data file so it can be used in the application. This will not properly work in the PhoneGap environment because the two use different approaches to loading data.
PhoneGap requires JSONP to be used when loading JSON data. In order to get JSONP to properly work with PreloadJS, you must define a callback in the object you are building for the manifest.
{id:"sheetData", src:"js/fakezee.json", callback: setupSpritesheet}
With JSONP, the file is loaded in as JavaScript and auto exectutes. In your fakezee.json file, simply wrap a function call around your sprite sheet JSON data. Now this function will fire, which is the same method declared in the manifest object, and will pass along the JSON as it’s first parameter. Listing 13-1 demonstrates this function call in fakezee.json.
Listing 13-1. Updated fakezee.json File Passes Sprite Sheet JSON Data to a Global Function
setupSpritesheet ({
"images":["img/fakezee.png"],
"frames":[
[702, 1806, 113, 50],
[817, 1787, 113, 50],
...
],
"animations":{
"diceHold":[63],
"diceTray":{
"frames":[64]
},
"die":{
"frames":[65, 66, 67, 68, 69, 70]
},
...
}
});
This JSON data is now passed into the setupSpritesheet function back in the game. In this function, you can safely use the passed-in data parameter to create your sprite sheet. Listing 13-2 shows the updated preload and setupSpritesheet functions for Fakezee.
Listing 13-2. Updated fakezee.json File Passes Sprite Sheet JSON Data to a Global Function
function preload() {
queue = new createjs.LoadQueue();
queue.loadManifest([
{id:"sheetData", src:"js/fakezee.json",callback: setupSpritesheet}
]);
}
function setupSpritesheet (data){
spritesheet = new createjs.SpriteSheet(data);
initGame();
}
You’ll also notice that you are not declaring the sprite sheet image in the load manifest. This is because the sprite sheet data object contains this reference and will handle the preload for you. This is the case whether you are using JSON or JSONP.
You can continue to use PreloadJS to load your other assets for PhoneGap applications, such as images and sounds as you normally would. However, be sure to include a separate listener for the completion of all files to init your application. The callbacks declared for JSONP should only be used for setting up sprite sheets if other assets are being preloaded in the queue.
Note When using PhoneGap, you may need to reference assets by using their full location path, as opposed to using the id that you assigned it in the load manifest. The asset will be successfully loaded and available, but might not be available via the preload queue object’s getResult method. I’ve found this to be the case in iOS, but not in Android.
Preparing Assets for PhoneGap
Similar to the iOS home screen app that was built in Chapter 12, icons and splash screens are needed for packaging your apps. These assets will be referenced in the config.xml file that is needed for PhoneGap to properly build your application.
These graphics are built similarly to how they were prepared for the Fakezee web app, and the icons can be reused for this project. The main difference is in the splash images: in the PhoneGap app they need to be a bit bigger. This is because you no longer need to compensate for the status bar, like you are forced to in a web app environment. Another key difference is that the landscape images should actually be landscape in ratio, as opposed to rotated, like is needed with web apps.
The icons and splash images for Android are prepared similarly, but will need their own set of properties to work across devices. Using the same design files for iOS, these assets can be prepared accordingly to match the required sizes. Using the configuration file for a reference, you will find the list of necessary assets and sizes. Let’s get into this configuration file now.
Preparing the PhoneGap Configuration File
The configuration file holds many configuration properties for your PhoneGap application. It holds version numbers, asset locations, permissions, plug-ins, and more. For the purposes of this project, you don’t need to configure much more than the locations to the graphical assets and a few platform settings and preferences.
The configuration file for PhoneGap is written in XML, and must be included at the root of your application when packaging for PhoneGap Build. The configuration file is used to apply settings and features to your application that would otherwise be set within files or the IDEs used to build native apps.
Listing 13-3 shows the beginning of the config.xml file. You will be adding more nodes to this file throughout this chapter.
Listing 13-3. config.xml – The Outline XML Structure
<?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.games.fakezee"
version="1.0.0">
<name>Fakezee</name>
<description>
Fakezee is a dice game that is fun for everyone!
</description>
<author href="" email="">
Fun Times Games
</author>
</widget>
A unique id is needed for your application and is set to the id attribute in the main widget node. This unique id is crucial when it comes time to package your application for distribution. It is less important during the development phase, which this chapter will cover, but just remember that this id must match certain provisioning files when publishing to app stores.
The current application version can also be set in this main node. This can be useful, especially when collaborating with other developers. This version number will be displayed within the application listing on the PhoneGap Build web site (see Figure 13-5).
Figure 13-5. Application build properties, seen in the application page
The name of your application is also declared here in the configuration file within the element name. The description and author elements specify metadata and contact information that may appear within app store listings.
Next, the platforms that you want PhoneGap to build for are listed (see Listing 13-4).
Listing 13-4. config.xml – Specifying Target Platforms
<gap:platform name="ios"/>
<gap:platform name="android"/>
In recent past, PhoneGap Build would automatically begin a build for all available platforms when uploading your content. This welcomed feature allows you to specify only the platforms you are currently developing for. Next is a set of preference and access elements (see Listing 13-5).
Listing 13-5. config.xml – Preference and Access Elements
<preference name="orientation" value="portrait"/>
<preference name="fullscreen" value="true"/>
<access origin="*" />
Here you can specify the preferred orientation for your application. Unlike web apps, you can lock the orientation here if you prefer to do so. In the Fakezee game, it will be locked in portrait orientation. It will also launch in full screen, which is also listed here.
You can use access elements to create a whitelist of domains that your application is allowed to load data and assets from. In this project, a wildcard is used to indicate that the application is fine to load from anywhere.
The icon and splash image elements, as prepared for iOS, are listed in Listing 13-6.
Listing 13-6. config.xml – Icon and Splash Screen Assets for iOS
<icon src="icons/apple-touch-icon-57x57.png" gap:platform="ios"
width="57" height="57" />
<icon src="icons/apple-touch-icon-72x72.png" gap:platform="ios"
width="72" height="72" />
<icon src="icons/apple-touch-icon-114x114.png" gap:platform="ios"
width="114" height="114" />
<icon src="icons/apple-touch-icon-144x144.png" gap:platform="ios"
width="144" height="144" />
<gap:splash src="splash/apple-touch-startup-image-320x480.png"
gap:platform="ios" width="320" height="480" />
<gap:splash src="splash/apple-touch-startup-image-640x960.png"
gap:platform="ios" width="640" height="960" />
<gap:splash src="splash/apple-touch-startup-image-640x1136.png"
gap:platform="ios" width="640" height="1136" />
<gap:splash src="splash/apple-touch-startup-image-1024x748.png"
gap:platform="ios" width="1024" height="748" />
<gap:splash src="splash/apple-touch-startup-image-768x1004.png"
gap:platform="ios" width="768" height="1004" />
<!-- retina iPad support: PhoneGap 2.5.0+ only -->
<gap:splash src="splash/apple-touch-startup-image-2048x1496.png"
gap:platform="ios" width="2048" height="1496" />
<gap:splash src="splash/apple-touch-startup-image-1536x2008.png"
gap:platform="ios" width="1536" height="2008" />
As you can see, the icons prepped for the Fakezee web app can be used here as well. As mentioned earlier, the splash images are slightly different and should be prepped accordingly for use in your PhoneGap application.
Listing 13-7 lists these same assets and how they should be prepared for Android.
Listing 13-7. config.xml – Icon and Splash Screen Assets for Android
<icon src="icons/android/ldpi.png" gap:platform="android"
gap:density="ldpi" width="36" height="36"/>
<icon src="icons/android/mdpi.png" gap:platform="android"
gap:density="mdpi" width="48" height="48"/>
<icon src="icons/android/hdpi.png" gap:platform="android"
gap:density="hdpi" width="72" height="72"/>
<icon src="icons/android/xdpi.png" gap:platform="android"
gap:density="xhdpi" width="96" height="96"/>
<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" />
<gap:splash src="splash/android/xhdpi.png" gap:platform="android"
gap:density="xhdpi" />
With all assets prepped and placed in the directories that the configuration elements dictate, the config.xml file is ready.
The Complete Configuration File for Fakezee
We have only scratched the surface of the features available within PhoneGap, and the available elements for your configuration files extend much further than what is needed for the Fakezee game. As your games and applications progress in size and complexity, you’ll need more elements so that your PhoneGap application properly builds and runs.
Listing 13-8 shows the entire config.xml file.
Listing 13-8. config.xml – The Complete Configuration XML File
<?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.games.fakezee"
version="1.0.0">
<name>Fakezee</name>
<description>
Fakezee is a dice game that is fun for everyone!
</description>
<author href="{insert your url here}" email="{insert your support email
here}">
Fun Times Games
</author>
<gap:platform name="ios"/>
<gap:platform name="android"/>
<!--IOS-->
<icon src="icons/apple-touch-icon-57x57.png" gap:platform="ios"
width="57" height="57" />
<icon src="icons/apple-touch-icon-72x72.png" gap:platform="ios"
width="72" height="72" />
<icon src="icons/apple-touch-icon-114x114.png" gap:platform="ios"
width="114" height="114" />
<icon src="icons/apple-touch-icon-144x144.png" gap:platform="ios"
width="144" height="144" />
<gap:splash src="splash/apple-touch-startup-image-320x480.png"
gap:platform="ios" width="320" height="480" />
<gap:splash src="splash/apple-touch-startup-image-640x960.png"
gap:platform="ios" width="640" height="960" />
<gap:splash src="splash/apple-touch-startup-image-640x1136.png"
gap:platform="ios" width="640" height="1136" />
<gap:splash src="splash/apple-touch-startup-image-1024x748.png"
gap:platform="ios" width="1024" height="748" />
<gap:splash src="splash/apple-touch-startup-image-768x1004.png"
gap:platform="ios" width="768" height="1004" />
<!-- retina iPad support: PhoneGap 2.5.0+ only -->
<gap:splash src="splash/apple-touch-startup-image-2048x1496.png"
gap:platform="ios" width="2048" height="1496" />
<gap:splash src="splash/apple-touch-startup-image-1536x2008.png"
gap:platform="ios" width="1536" height="2008" />
<!--ANDROID-->
<icon src="icons/android/ldpi.png" gap:platform="android"
gap:density="ldpi" width="36" height="36"/>
<icon src="icons/android/mdpi.png" gap:platform="android"
gap:density="mdpi" width="48" height="48"/>
<icon src="icons/android/hdpi.png" gap:platform="android"
gap:density="hdpi" width="72" height="72"/>
<icon src="icons/android/xdpi.png" gap:platform="android"
gap:density="xhdpi" width="96" height="96"/>
<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" />
<gap:splash src="splash/android/xhdpi.png" gap:platform="android"
gap:density="xhdpi" />
<preference name="orientation" value="portrait"/>
<preference name="fullscreen" value="true"/>
<access origin="*" />
</widget>
Submitting your Application to PhoneGap Build
With your configuration file complete, zip up your application directory. This ZIP file is what is uploaded to PhoneGap Build. Be sure that your index.html and config.xml file are at the root of the zipped directory. Head back over to the PhoneGap Build site so you can submit your application. Under the Apps tab, press the +new app button. Figure 13-6 shows the new app page.
Figure 13-6. New app screen on the PhoneGap Build web site
As you can see in Figure 13-6, you can browse for the ZIP file to upload. If you are Git-savvy, you can alternatively point to a Git repository, which will be used to build your application.
Once your new project is successfully uploaded, your application will be ready to build. With iOS, you need to supply a certificate and provisioning file, which can be acquired with an Apple developer account. You need to provide these files before PhoneGap will build your application, even if it’s just for development. Figure 13-7 shows the message you will receive when attempting to build for iOS without your Apple certificate files entered into the system.
Figure 13-7. iOS error message indicates that an action is required to build
When your applications successfully compile, the app screen will provide links for the install files to download. In this case of Fakezee, you will be offered both an .ipa file and an .apk file. These links can also be shared for installation on other devices. When accessed from a device, the installation process with begin immediately when the link is vistited.
You can alternatively use the QR code by using a QR reader app on your device. This will allow you to download and install the application without having to connect or sync your device to a computer. Figure 13-8 shows the application screen in PhoneGap Build with an application that has been built and ready to install.
Figure 13-8. Application screen for the Fakezee game in PhoneGap Build
For iOS applications, the device that is installing your application needs to be included in the provisioning file that you uploaded to PhoneGap Build and used to compile the app. With Android, no special signing is needed for simply testing your application across all devices.
As previously mentioned, we’ve only scratched the surface of what can be done with PhoneGap. Using PhoneGap Build, you can quickly get your web application compiled into multiple platforms by simply uploading a zip file of your web files. You can alternatively install PhoneGap via the command line and compile locally. This option gives you template projects that can be opened in applications such as XCode, where you can fine tune your iOS application from within its native environment before deploying.
For more information on what you can do with this powerful tool and how you can use it, visit the online documentation at http://docs.phonegap.com/en/edge/index.html.
Summary
In this chapter, you used PhoneGap Build to compile a game, built with CreateJS, into an application that can ultimately be distributed through app stores and installed onto devices. A few caveats were introduced that can prevent your sprite sheet data from loading appropriately within your application when compiled with PhoneGap.
The configuration file and the XML elements needed to compile your applications with PhoneGap Build were reviewed, and the necessary graphical assets for both iOS and Android were covered.
In the next and final chapter, you will use all of the skills learned in this book to create an RPG battle game. The next chapter also contains an introduction to local storage for saving the player’s progress. The state machine code, asset manager class, and scaling techniques will be used to prepare the game to be easily distributed over the Web.