Bridging the Phone Gap

How to Deploy Your Breeze Application to Mobile Devices

This document describes how to package, build, and deploy your Breeze application to mobile devices using PhoneGap.

PhoneGap and PhoneGap Build

A PhoneGap application is fundamentally an HTML+CSS+JavaScript application, with a wrapper around it that allows it to be deployed as a native app. The PhoneGap wrapper also provides access to the phone's underlying hardware APIs, via a JavaScript interface. The same application code can be used for iOS, Android, Blackberry, WebOS, and Windows Phone 7 & 8.

PhoneGap Build is a service for building your PhoneGap apps in the cloud. To use it, you import your project files from GitHub to the PhoneGap Build web site. PhoneGap Build compiles your PhoneGap project and creates deployable applications for each platform. You can install the deployment files directly on your device, and test right away. You don't need an IDE at all. Significantly, you can develop iOS apps without a Mac.

 

If you don't have the mobile device, want to debug in an emulator, or want to develop OS-specific plugins, you can develop and build PhoneGap applications using the appropriate IDE. For example: Eclipse/ADT for Android, Xcode for iOS, or Windows Phone 7 SDK / Windows Phone 8 SDK for Windows Phone, etc. The PhoneGap site has Getting Started guides for each of the supported platforms.

 

The PhoneGap Build story is compelling. For the rest of this document, we're going to show you how to develop and deploy your mobile application using GitHub and PhoneGap Build. This walkthrough assumes a PC running Windows 7, but the steps will be similar on OS X or Linux.

Getting Started with Git

If you've already used Git and GitHub before, you can skip to the next section. If not, we'll walk you through the basics.

First, you'll need to create an account on GitHub. Then you'll need to set up git on your computer. I recommend downloading the GitHub app, which does most of the config work for you. The GitHub app includes OpenSSL and MINGW32, which you'll need later to create the certificates for signing your iOS apps.

After you install the GitHub app, you'll get a shortcut to "Git BASH", which is a Unix-like command-line shell that lets you run all the Git commands.

 

Git is a command-line tool, and the commands can be a bit confusing at first. Pro Git or Git Reference can help you get started, and SmartGit can insulate you from the command line syntax. For this demo, I'll take you through the necessary git commands step-by-step.

 

The first thing is to tell Git who you are, since your identity will be added to all your commits. From the Git BASH prompt, tell Git your name and email address:

 

$ git config --global user.name "Joe Example"

$ git config --global user.email joe.example@example.com

Starting with a Template

Once you have Git working, you need a project to work with. PhoneGap Build applications have a particular folder structure, so it's best to start with a template. To get one, we're going to fork (copy) the PhoneGap Start application.

 

  1. Log in to GitHub
     
  2. Go to https://github.com/phonegap/phonegap-start
     
  3. Click the Fork button in the upper left. This creates of copy of phonegap-start in your own GitHub repository. Your copy will have its own url, for example https://github.com/steveschmitt/todo-phonegap
     
  4. Optional: rename your copy. Click on the "Settings" button (upper left, below Fork). On the settings page, type your new repository name and click "Rename". I've renamed mine to "todo-phonegap" since I'm making a PhoneGap version of the Breeze Todo example application.
     
  5. Now you've got your own project on GitHub; you need to clone it to your own computer so you can work on it. Using Git BASH:
$ cd /c/projects

$ git clone https://github.com/steveschmitt/todo-phonegap

Developing Our Application

Finally, we can start developing our app. Let's take a look at the folder structure that phonegap-start gave us to start with:

  • .gitignore (tells Git what files to ignore)
  • LICENSE (the Apache license for PhoneGap)
  • README.md (the file displayed on the GitHub project page, in Markdown format)
  • UPDATING.md (instructions on updating phonegap-start; we can ignore this)
  • www/
    • config.xml (config file for PhoneGap)
    • icon.png (PhoneGap icon)
    • index.html (the main page for the application)
    • spec.html (page for Jasmine unit testing)
    • css/ (css files)
    • img/ (images)
    • js/ (JavaScript files)
    • res/ (resources used by PhoneGap
    • icon/ (OS-specific icon files)
    • screen/ (OS-specific splash screen files)
    • spec/ (libraries used by Jasmine)

Now it's time to customize the application. Since a PhoneGap app is basically a web app, we will be changing index.html, and adding some CSS and JavaScript.

For this example, we're going to make PhoneGap version of the Breeze Todo-Angular application, so we'll copy some of the resources from there. If you don't have the Breeze Todo-Angular sample already, you can download a zip file of all the Breeze code or get it from GitHub like this:

    $ cd /c/projects

    $ git clone https://github.com/IdeaBlade/Breeze.git

Now let's make our PhoneGap app into a Breeze Todo app.

  1. Replace the index.html file in our PhoneGap app with the one from Breeze\Samples\Todo-Angular\Todo-Angular, and rename it to lower case so PhoneGap will find it.

  2. Copy the Content folder and the Scripts folder from Breeze\Samples\Todo-Angular\Todo-Angular into our www folder.
     
  3. Edit the index.html file to add a link to the PhoneGap JavaScript API. Near the bottom of the file, after the other script tags, add the line
     
    <script type="text/javascript" src="phonegap.js"></script>


    Note that we don't actually include the phonegap.js file in our project; PhoneGap Build adds the file for us.
     
  4. Edit www/Scripts/app/dataservice.js to use the remote todos service (since we won't run a local service on our mobile device). Comment out the line that says
    var serviceName = 'api/todos';

    and uncomment the one that says
    var serviceName = 'http://todo.breezejs.com/api/todos';

At this point, you should have a working Breeze Todos app. Open the index.html file with Chrome or Firefox, and you should be able to view, add, and delete Todo items as described on the Breeze Todos Sample page. If it's not working, you should double check that the paths to the CSS and JavaScript files are correct in index.html.

Uploading to GitHub

Now that we've made our changes, we add our changes to git, commit them, and push them up to GitHub. Using Git BASH:

$ cd /c/projects/todo-phonegap

$ git add .

$ git commit -m 'Changed to Breeze Todo demo app'

$ git push origin master

You can now browse your website on GitHub to see that your changes are there.

Deploying via PhoneGap Build

Go to build.phonegap.com. If this is your first time, click Register, choose a plan (free or paid), then click "Sign in with GitHub" to use your GitHub credentials.

Once you're signed in, click the New App button and paste in the URL to your GitHub repository, e.g. https://github.com/steveschmitt/todo-phonegap. PhoneGap build will pull in your project from the GitHub repository, and take you to the build page for the app.

Click on the "Rebuild All" button, and wait for about a minute while PhoneGap build creates deployable apps for each of the supported mobile platforms. You'll notice a red error box for the iOS platform; we'll get to that in a minute.

If the build was successful for your mobile device OS, a button will be displayed that links to the deployable application file (*.apk, *.xap, etc). You can now install the app to try it out. For Android, Blackberry, Symbian, and WebOS, you can install by navigating to the installer URL on your device. For example, on Android go to https://build.phonegap.com/apps/[appid]/download/android. For Windows Phone, you'll need to download the file to your PC, then use Microsoft's deployment tool to install the XAP.

Provisioning for iOS

For iOS, you will need to be a registered developer, because you'll need to sign the app with a provisioning profile in order to install it. Apple has docs about the enrollment process, and CodeOutlaw wrote a bit about using the certificates in PhoneGap. I'll go over the steps here.

  1. Enroll in the Apple Developer Program. After you're approved (it can take a few days), you can log in to the developer center.
     
  2. Go to the iOS Provisioning Portal and download the WWDR intermediate certificate, AppleWWDRCA.cer. Keep in a certs directory on your PC.
     
  3. Start GitBASH and do the following (the lines prefixed with # are comments):

    # Change to certs directory
    cd /c/certs

    # Generate private key.  
    openssl genrsa -out private.key 2048

    # Generate certificate signing request.  Use your own email address
    openssl req -new -key private.key -out CertificateSigningRequest.certSigningRequest  -subj '/emailAddress=joe@example.com, CN=Joe Example, C=US'
     
  4. On the iOS Certificates page, click the Request Certificate button and upload the CertificateSigningRequest.certSigningRequest you created above. After a minute, you'll be able to download your development certificate, ios_development.cer. Save it in your certs directory.
     
  5. In GitBASH, do the following:

    # Generate Distribution certificate signing request.  Use your own email address
    openssl req -new -key private.key -out DistCertificateSigningRequest.certSigningRequest  -subj '/emailAddress=joe@example.com, CN=Joe Example, C=US'

    # Convert ios_development.cer to ios_development.pem
    openssl x509 -in ios_development.cer -inform DER -out ios_development.pem -outform PEM

    # Convert ios_development.pem to ios_development.p12.  Enter a password and remember it for later.
    openssl pkcs12 -export -inkey private.key -in ios_development.pem -out ios_development.p12
     
  6. Back on the iOS Certificates page, go to the Distribution tab. Click the Request Certificate button there, and upload the new DistCertificateSigningRequest.certSigningRequest you created above. After a minute, you'll be able to download your distribution certificate, ios_distribution.cer. Save it in your certs directory.
     
  7. Go to the Devices section and add your iOS device. You'll need the Device ID, which you can get from iTunes or using an app such as Device ID Sender.
     
  8. Go to the App IDs section and click the New App ID button. Follow the directions there to identify your app.
     
  9. Go to the Provisioning section. Here is where you connect your certificate, your device, and your app together to make a Provisioning Profile that allows you to deploy your app to the device. Click the New Profile button, enter the info for the profile, and click submit. Finally, you can download the .mobileprovision file to test your app.

Signing Your App in PhoneGap Build

Log in to PhoneGap build and go to Edit Account. Click on the Signing Keys tab. Under iOS, click "add a key". Give the key a name (remember it's unique to the device and the app). Then upload your ios_development.p12 and myapp.mobileprovision file.

After you've created the key, you'll need to unlock it by entering the password you used when you generated the ios_development.p12 file. PhoneGap Build remembers the password for 30 days, so you don't have to unlock it every time.

Now you can go to the Apps page, click on your app, and choose "Select a key" from the dropdown next to the iOS icon. Select the key you created above, and finally you can build your iOS app.

Once the iOS app is built, you can download and install it directly on your device by using the browser on the device. Navigate to the link (e.g. https://build.phonegap.com/apps/[appid]/download/ios) and the app will install automatically.

Developing for mobile devices

Note that the Breeze Todo Sample saves immediately after every change. You might not notice this on the desktop, but on a mobile device, where the processor is slower and network latency is higher, incurring this latency might not be the best user experience. You'll also want to consider responsive web design using CSS 3 to adapt the layout to the screen size. Details like this can make or break a mobile application.

If you'd like our help with mobile development, please contact our professional services team at breeze@ideablade.com.