This document provides an overview of using PhoneGap to build mobile apps. It discusses setting up PhoneGap, building an app called PPL Tutor, customizing apps for different platforms, available features like cameras and geolocation, installing plugins, testing apps, common issues, and submitting apps to app stores. The document is written by Karl Bunyan from his experience building mobile apps and focuses on wrapping existing web apps and developing cross-platform with PhoneGap.

1. Wrapping with PhoneGap
Learning from my
barely-competent fumbling
Karl Bunyan, Wedu Games

2. Overview
• Building the app
• Setting up PhoneGap
• Customising
• Available Features
• Testing
• Gotchas
• Submitting

3. About PhoneGap
Allows you to package HTML apps for the App
Store and Google Play
• PhoneGap: generates files locally
• PhoneGap Build: upload your files, download
store-ready packages
• Apache Cordova: the root of PhoneGap

4. About me
• Long-time web developer since late 90s
• Ad-hoc game developer since late 80s
• Involved in social* apps and games since 2007
• Worked for GSN making games for Facebook
• Currently doing my own thing
* and anti-social

5. The App: PPL Tutor

6. Building the App
• Regular HTML, JavaScript, CSS, images
• Develop and test in a desktop browser
alongside devices
• Use responsive CSS (media queries) for
different screen sizes and aspect ratios:
– Tablet landscape; tablet portrait; phone portrait

7. Things you’ll need
• A computer
• A Mac, if you’re building for iOS
– With Xcode installed. It comes with emulators.
• The Android SDK
– The Eclipse package is pretty good
• Accounts and certificates:
– iTunes Connect, Certificates, Provisioning Profiles,
Google Wallet, Google Developer

8. Setting up PhoneGap
• Install NodeJS, Git, JDK and Ant. Set PATHs.
• Download files with Git
• Use NodeJS Package Manager to install
• Create the app on the command line
• Add platforms
• Run a build command
• Sit back and admire your files

9. The File Structure: Pre-build
Root
merges
platforms
plugins
www
Platform-specific files (never worked this out)
Where files end up after build
Extra features go here
Your HTML source files live here

10. The File Structure: Post-build
assets: where your HTML ends up
platform-specific source files
platform_www: platform-specific HTML/JS
platforms
android
ios
assets
PhoneGap
folders
platform_www
Config
files
config files (depending on the platform)

11. The Build/Test Cycle
• Add platform(s)
• Run build command
– Generates platform-specific folder + source code
– Copies from root/www to
root/platforms/[platform]/assets/www
• Changes made to assets/www are overwritten
• Open the project in Xcode
• Run it on the device or emulator

12. Customising 1: Config Files
• Limit screen orientation
• Specify splash screen
• Specify file to load: index.html
• App icons
Config files are different for each platform,
although (in theory) generated from a single
source

13. Customising 2: Source Code
E.g. Preventing the iOS 7 battery meter from
overlapping your application
• Open XCode
• Tweak the Objective-C
except
• Next time you run build your changes will be
overwritten

14. Available Features
Includes:
• Camera
• Accelerometer
• Geolocation
• Network connectivity
• In-app purchases
• Local storage

15. Plug-ins
Plugins are a mixture of Objective-C or Java
source code and JavaScript. E.g.:
• Network connectivity:
– Cross-platform plug-in
• In-app Purchases
– Different plug-in for iOS and Android

16. Plug-ins
Installing a plug-in:
• Use Git to download
• Command line to install
• Re-run build
– Which may lose your customisation changes
Or install by hand:
• Installing a plug-in by hand is not fun

17. Aside: My Code Management
• Run build only once, and then customise
• Set launch to
index.html?platform=[platform]
• platforms/[platform]/platform_www
symlinked to a single app file source
• Detect “platform=“ on the query string to
include the correct JS plug-in config file
• Include object detection in JavaScript to
determine how to deliver a feature

18. In-app purchases
• Make sure they’re set-up correctly in iTunes
Connect/Google Play
• Make sure test accounts are set up
• Download and install the plug-ins:
– iOS: cc.fovea.plugins.inapppurchase
– Android: com.smartmobilesoftware.inappbilling
• Follow the documentation religiously

19. Testing your code
• Install the plug-in for console logging
• Use simulators in Xcode
• Android emulators via device manager:
– GUI started from command line or from Eclipse
• Test directly on plugged-in devices
• Android: build and e-mail APKs
• iOS: archive in Xcode, build for Ad-hoc
distribution, use TestFlight

20. Testing in-app purchases
• Black-box systems: reports success or failure
• iOS test accounts
– Do not add credit card details
– Test on emulators or device
• Android test accounts
– do not use the e-mail address on your device for
developer or Wallet accounts
– Have to test on live devices: no emulators

21. Other gotchas
• Never skim the docs
• Android failed to load some folders that
started with underscores
• Do not try to download JavaScript in-app
• For first-time setup, use test namespaces in
iTunes Connect: you will mess it up
• Never ever skim the docs

22. Submitting
Google Play
• Remove debug settings
• Increment version number
• Build and upload
• Wait 15 minutes or so

23. Submitting
iOS App Store
• Set up certificates and provisioning
• Log into iTunes Connect:
– Add a new version of the app
– Add any in-app purchases for this version
– Mark as “Waiting for upload”
• Archive in Xcode and distribute
• Submit, wait and hope

24. £££ Profit £££!

25. Questions
PPL Tutor is free on
iTunes and Google Play
karl@wedugames.com
twitter.com/karlbunyan