December | 2013 | rob.alarcon

PhoneGap (Apache Cordova) is great. If you’re already familiar with web technologies (HTML, CSS and JavaScript) you can easily start coding web apps that will be embeded on a mobile native app that can be installed in a mobile device (iOS, android, windows phone, blackberry, etc).

But one thing that is a little confusing at first is deploying for iOS devices when you’re a windows developer. In the following tutorial we’re going to follow a series of steps to deploy our app to a iOS device using PhoneGap Build.

Note: this tutorial is targeted for PhoneGap developers using windows or linux, testing primarily in Android. But this tuturial should work for PhoneGap developers using mac too, actually for this tutorial we’re going to need a mac to borrow at least.

Requirements

[ ] a Mac to borrow (should be e an Intel-based Mac)
[ ] an iOS Device for testing (could be an iPod Touch, iPad or iPhone)
[ ] an Apple ID
[ ] Subscription to the App Developer program
[ ] A mac software called “Keychain Access” if the mac that you took borrowed don’t have it, you can install “XCode” and it will install it automatically.
[ ] A phonegap App running in windows with android, to make the initial set-up you can follow Charles Chen post: Step by Step Android Development with Cordova and IntelliJ, I highly recommend you this tutorial, it’s easy to follow, and it does not have a lot of text like this one.
[ ] A phonegap account (to have access to the remote build app).

Get an Apple ID

Create an apple ID (this is free, and you need one to enroll to the iOS Developer program):
You can get one at: https://appleid.apple.com/cgi-bin/WebObjects/MyAppleId.woa/wa/createAppleId

Get an Apple Developer program account (iOS Dev Enrollment)

You are going to be asked to enroll as an individual or as a company, choose whatever accommodate to you:

https://developer.apple.com/programs/start/standard/

Activate your Apple Developer Program

Once you have both your apple ID and iOS Dev Enrollment, you have to activate your apple developer account, bellow are summarized the necessary steps:

Once you have both your apple ID and iOS Dev Enrollment, you will need to sign in for Apple IOS Dev program enrollment.
You will need to fill a form (divided in five steps) to Activate your program.
Submit your billing information
Select a program
Review
You must agree to the TOS License.
And finally you can activate your Developer program.

Download & Install XCode in the Mac

There are some options to install xCode, the easiest way to install it is by downloading it from the app store.

Alternatively you can download it from:
https://developer.apple.com/downloads/index.action

Building the iOS Package on PhoneGap Build

PhoneGap build is very easy to use, once you have the code for your app, you just need to zip your “www” folder, and upload it to PhoneGap, then the app will build the app for all the selected devices, it’s really straightforward, except for iOS; In order to build an iOS package, phonegap needs a “phonegap iOS key” (I can’t find an official name for this key).

What is a PhoneGap iOS key?
Is a key that PhoneGap Build need to create a package for an iOS device (apk file).

Creating a PhoneGap iOS key

To create this key, phonegap needs two things:
a) an iOS Developer certificate (p12) file
b) an iOS Device Provisioning Profile

a) Getting the iOS Developer certificate (p12) file:
1- Login into the iOS Developer Center
Go to https://daw.apple.com/cgi-bin/WebObjects/DSAuthWeb.woa/wa/login?&appIdKey=891bd3417a7776362562d2197f89480a8547b108fd934911bcbea0110d07f757&path=%2F%2Fdevcenter%2Fios%2Findex.action

the login should look like this:

2- Go to the “Certificates, Identifiers & Profiles Section”
The link for this section is bellow the upper right corner of the iOS Dev Center Home page.

3- Click the “Certificates”Folder:

4- Click on the “+” (plus) sign button bellow the righ top corner:

5- Set your certificate as “iOS App Development”under the Development Section and click on the continue button at the bottom

6- Create a CSR file

Open the “Keychain Access” program (for not mac users, you can open almost any mac programs by writing the program name in spotlight, to open spotlight just press the “command” key and the spacebar).
Request a Certificate from a Certificate Authority, Within the Keychain Access drop down menu, select Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority, (be sure to select “Request a…”); It should prompt the following screen:

You should set your Email, a common name for your certificate, left the “CA Email Addresss”and set the “Request is” field as “Saved to disk”, and press the “Continue” button.

Now back to the Apple Dev Center press the continue button:

7- Upload the CSR file (the certificate) that we created in step 6, and press Generate

You should see an screen like the following, click on the “Download your Certificate”, and press “Done”

Then locate your certificate (it should be in the Downloads folder by default), the name of my file for this tutorial is “ios_development-2.cer”, double click that file and you will open the “Keychain Access” program again;

To locate the certificate after open the “Keychain Access”: filter by “login”under “keychain”and, “My Certificates” under “Categories”, you should see your certificate with the alert “this certificate is not yet valid”.

We are going to export this certificate right clicking the certificate and selecting the “Export: ‘iPhone Developer’ ” option

It will prompt for credentials for this key (be sure to save this password, because phonegap will ask for it once a month if you want to build)

Then the app will prompt for the Mac User Password, set the password, and then go to your File System to locate the generated Personal Information Exchange File (.p12)

Register the Development Device to the Apple Dev Center

Under the Devices Section, click on the “+” (add) button bellow the right top corner

To register a Dev Device you will need to named and the Device UDID:

To get the Device UDID you can connect the device into the computer, open iTunes, go to the iOS Device properties and copy the UDID from there:

Copy that UDID and set it into the Device Registration Form, name your device and click continue, and then click “Register”

Create an App ID

You are going to need you App ID in order to create a Provisioning Profile, you can add this App ID under the “Identifiers” Section, you have to set the “App ID Description”, and then set the “App ID Suffix”, set this suffix as an “Explicit App ID” If you have a plan to incorporate your app with services like In-App Purchase, Data Protection, etc, or want a provisioning profile unique to a single app, you must register an explicit App ID for your app, or you can select a Wildcard App ID, this allows you to use a single App ID to match multiple apps, and then click continue, As a last step for the App ID Generation, just confirm your values.

Getting the The Provisioning profile

The next step is getting the Provisioning profile, go to the “Provisioning Profiles” section, and then click the “+” button at the right top corner (almost the same procedure as the last steps)

Set the device as an “iOS App Development” Profile and press continue

In the next screen select an Apple ID (the one that we created in the last step)

In the next screen select your Certificate and press continue (the one that we created before)

In the Next step you have to select the device for the current Provisioning Profile and then Click on the “Continue” button (the one that we add in the devices section)

In the following screen, name the profile and click on “Generate”

In the following screen you can Download the Profile and then click “Done”

Happy note: take a 5 minutes break, the boring part is done, next steps would be more enjoyable

Remote Build with PhoneGap Build

Login into PhoneGap Build, the first thing that you’re going to see is the following image, press the “upload a zip file” button

Then select and upload the zip file that contains your “www” folder, usually you’re going to submit a file named “www.zip”.

Once the app is uploaded press the “Ready to Build” button.

You’ll noticie something unusual, all the platforms performed the build correctly except for iOS, the reason why is because PhoneGap Build needs the iOS key, we’re going to create that key with the provisioning profile and certificate that we previously created.

Add the PhoneGap Build iOS Key

Under the iOS build section, open the Dropdownlist and select the “add a key” option.

Set a title for this specific Build Key, choose the previously generated Key and Provisioning Profile and click the “submit key” button.

Phonegap will try to generate a new build automatically, but it will fail, that’s because the key is locked by default, you have to press the yellow button with a lock, and insert the CERTIFICATE password.

Submit the password (remember that once a month you will need to resubmit this password),

Rebuild the app and you will have your “ipa” file ready to install in the selected device for the Submitted Provisioning Profile.

Install the “ipa” build in the iOS device

Download the “ipa” file from the phonegap build
Double Click the “ipa” file, itunes should open this file and it will add the app to your itunes, or it will ask to replace the app if it is a new build.
Connect the Development Provisioned iOS Device
On iTunes navigate to your device, it should appear below the search input in the right corner as a button.
Under the device options go to the “Apps” tab, your app should appear there under the “Apps” List, click the “install” button for the selected app to install in this device, and the “install” button should change to “will isntall”

The last step is to just press the “Apply” button in the right bottom corner, and your application will be installed in your development device ready to be tested.

Resources

Step by Step Android Development with Cordova and IntelliJ, by Charles Chen, last retrieved on Dec 18, 2013
Getting everything for building iOS apps with build.phonegap.com, by Martin of Centralway, last retrieved Dec 13, 2013

wow, that was a really long and boring post, the good stuff in PhoneGap is programming, so this time the boring stuff was on me : ), this post was a little difficult, so if you’re following this step by step guide and something fails, please be free to contact me, and I’ll try to edit the post (probably I forgot to add an step)

PhoneGap 3 Hello World in OS X

I have been using PhoneGap 2.x for a couple of months and it’s a good framework that can help you to deliver a cross-browser product quick without knowing all the technologies behind the devices. I wanted to update to the new version because it has support for ios7, and I like the new approach for the modular plugins.

PhoneGap 3.x make an extensive use of the PhoneGap CLI in contrast to a manual installation, in the following tutorial we’re going to make a step-by-step installation of PhoneGap 3.0.2 with a hello world application on a iOS emulator running on OS X.

Prerequisites

Install Xcode (you can install it from the AppStore)
Install PhoneGap command-line tool
1. Install Node.js (download the mac package from http://nodejs.org/download/)
2. Install PhoneGap framework: open a mac terminal and type
  sudo npm install -g phonegap

Create the App

Now that our mac have installed the framework lets create the application

In the terminal, go to the folder where you will create your project
Type the following to create your project:
phonegap create TabletPrototype com.robalarcon.tabletprototype TabletPrototype

note: in the line above we are calling the “create” method of the “phonegap” command, and we’re sending three parameters, first the name of the app directory, secondly the reverse domain-style identifier, and at last the application display text (the last two arguments are optional and you can set them later in the app config.xml file)

What phonegap does when we call the “create command”? Well it will create a sample project for us, this sample project will contain all the necessary files to run a hello world project that is attached to the “device ready” PhoneGap event, all of this in the “www” folder that is where we have our web assets that represent our application.

I’m listening “Say Hello” by the Whings, good song

Build the App

Change to the directory that we created on the last step
cd TabletPrototype
Install ios-sim app (this is to be able to invoke the ios emulator in the console without using xcode)
sudo npm install -g ios-sim
Install phonegap ios
phonegap install ios

The last step will install our app in the ios emulator (emulating an iphone retina)

O.K. more than that is happening, and knowing this is helpful if you need to open your project on Xcode for any reason (like the one bellow in this post), remember when we used the “create” function of phonegap? When we did that, we create a folder structure for our code base inside of our app main folder we have four folders:

merges
platforms
plugins
www

We already know that ‘www’ is our work space, but the other three folders are empty after the ‘create’ call, well what happen after we call “phonegap install ios” is interesting, that command did some stuff for us:

It created a folder called ios, inside of that folder there’s a lot of folders and files, for this tutorial we’re interested in two of them (the www folder and the .xcodeproj file), but all of those documents are important, they are the phonegap app, all the dependencies that the app need to run are there (ios classes to run the webview and that specifies that the app start with the ‘index..html’ archive).
It copied our “development” www folder into the ios folder, it’s an exact copy, and it is not linked with our dev www folder, so if you change something in your www dev folder, you have to run the ‘phonegap install ios again.

Changing the ios Emulator Device in Xcode

As the time of this writing I cannot find a way to change the “emulator target” device for ios, so We will do that on Xcode, to open the project in Xcode, you have to navigate to the root folder and open the “platforms” folder, find and open the “ios” folder, finally open the “.xcodeproj” file (in my case TabletPrototype.xcodeproj), once that the project has been opened, just press the play button and the emulator should start:

Important: The code that the emulator is running is the code inside the ‘www folder’ in the ios folder inside the ‘platforms’ folder. Where I am going with this? The code that you will see in Xcode source three is not your development code, is the code that is copied by the ‘phonegap install ios’ command to the ‘/platforms/ios/www’ folder. So be aware of this, try to just code in your ‘www’ development folder.

Voilà, we can start building our app.

Beginning the Real development

If you want to continue your development with the template provided by the PhoneGap Download, you can do it, the only thing you need to do is to delete the following folders and files:

“res folder”,
“spec folder”,
“icon.png file”,
“spect.html file”,

all the content inside the css folder, all the content inside img folder, and, all the content inside the js folder.

now go to your index.html file and replace all its content to the following basic hello world code:

<html>
 <head>
 <meta charset="utf-8" />
 <meta name="format-detection" content="telephone=no" />
 <meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width, height=device-height, target-densitydpi=device-dpi" />

<title></title>
 </head>
 <body>
 <h1>PhoneGap 3.x Hello World</h1>
 <!-- load phonegap script (the phonegap "server" will generate this file in the root) -->
 <script type="text/javascript" src="phonegap.js"></script>
 <script type="text/javascript">

 var __onDeviceReady = function() {
 alert('Device is Ready: application can start.');
 };

document.addEventListener('deviceready', __onDeviceReady, false);

</script>
 </body>
</html>

this is just a header tag that you can remove, we are loading the phongegap.js library in a script tag, and we are attaching an alert to the “deviceready” event of phonegap.js, when you run this example you should see a message like this:

That’s a good point of start so you can beginning coding your PhoneGap Application.

Resources:

ios-sim: http://outof.me/phonegap-2-0-getting-started/
PhoneGap CLI guide: http://docs.phonegap.com/en/3.2.0/guide_cli_index.md.html
Deploying PhoneGap to ipad: http://stackoverflow.com/questions/18455661/how-do-you-deploy-phonegap-app-to-ipad

rob.alarcon

Articles about JavaScript, CSS, HTML and general programming.

Month: December 2013

iOS Development for PhoneGap Windows Developers using PhoneGap Build

Requirements

Get an Apple ID

Get an Apple Developer program account (iOS Dev Enrollment)

Activate your Apple Developer Program

Download & Install XCode in the Mac

Building the iOS Package on PhoneGap Build

Creating a PhoneGap iOS key

Register the Development Device to the Apple Dev Center

Create an App ID

Getting the The Provisioning profile

Remote Build with PhoneGap Build

Install the “ipa” build in the iOS device

Resources

PhoneGap 3 Hello World in OS X

PhoneGap 3 Hello World in OS X

Prerequisites

Create the App

Build the App

Changing the ios Emulator Device in Xcode

Beginning the Real development

Resources: