Tuesday, October 18, 2011

iOS Development on Windows w/ PhoneGap Build

I have wanted to write apps for the iOS platform for a long time. I am a windows developer and did not really have any ideas for apps to constitute buying a Mac. Regardless, I still wanted to write apps. On this journey to develop apps for iOS, I have been hopeful, discouraged, and then hopeful again. Finally, I have finally been able to successfully write an app and get it installed (and ready to submit to the app store) all using only my Windows 7 box and an amazing tool called PhoneGap Build.

Using PhoneGap Build, I am able to build an app in HTML5, package it up, and send it to their servers to have it compiled and ready to install onto my iOS device.

Overview of Process

  1. Sign up for the iOS Developer Program (cost $99/year)
  2. Setup Apple Certificats for your app
  3. Sign up with PhoneGap Build
  4. Upload certificates to PhoneGap
  5. Upload HTML5 App to PhoneGap Build
  6. Install App Through iTunes.

Register with the Apple Developer Program

Visit http://developer.apple.com/programs/ios/ and sign up for an account.  The process is a little drawn out, but after 5 or 6 steps, you will finally be able to pay for the program and become a member.  It can take up to 24 hours for your account to be created.  I thought that might a lot faster than that, but it still took about 16 hours before I received my account.

Setup Apple Certificates for your app

This step took me a while to figure out.  After I finally got it working, the process seemed to make sense, but it only after a few hours.  If you are not familiar with openssl, hopefully this will save you a lot of time. All the instructions I saw said to install openssl, which I tried, but I kept getting an error when trying to generate keys.  I finally resorted to installing cygwin and adding openssl to that installation and that worked like a charm. I won't go into the details of how to do that. You can check their site for that. Here is a link to download the cygwin setup.

*NOTE* The batch file below should work regardless of whether you install openssl or use cygwin.

The first step is to generate a CSR to send to apple to obtain your developer certificate.  I have created a bat file with the following contents:

Download: create_certs.bat

REM --------------------------------------------------------------
REM START
@ECHO off
SET NAME=My Name 

SET EMAIL=my@email.com
SET COUNTRY=US

ECHO Generate Private Key
openssl genrsa -out private.key 2048

ECHO Generate CSR
openssl req -new -key private.key -out CertificateSigningRequest.certSigningRequest  -subj "/emailAddress=%EMAIL$, CN=%NAME%, C=%COUNTRY%"

ECHO Download Developer Cert from Apple
pause

ECHO Generate Distribution CSR 

openssl req -new -key private.key -out DistCertificateSigningRequest.certSigningRequest  -subj "/emailAddress=%EMAIL$, CN=%NAME%, C=%COUNTRY%"

ECHO Convert developer_identity.cer to developer_identity.pem
openssl x509 -in developer_identity.cer -inform DER -out developer_identity.pem -outform PEM

ECHO convert developer_identity.pem to developer_identity.p12 

openssl pkcs12 -export -inkey private.key -in developer_identity.pem -out developer_identity.p12 
DEL developer_identity.pem
REM END
REM --------------------------------------------------------------

Steps for Using this Bat File

  • Create a bat file from the contents above or download it.
  • Change the NAME, EMAIL, and COUNTRY variables in the bat file to your personal info.
  • Open cygwin command shell
  • cd to a directory where you want to store your certificates. Store the bat file in this directory.
  • Run the bat file. This will generate a private key and then use that key to create the CSR. At this point it will pause. Do not press any keys.
  • Navigate to the iOS portal: https://developer.apple.com/ios
  • Click the "iOS Provisioning Portal" link on the top right of the page
  • Click the "Certificates" link on the left
  • Click the "Request Certificate" button on that page.
  • Select "Choose File" and navigate to the directory you created and select the file named"CertificateSigningRequest.certSigningRequest" and click "Submit".
  • Download the certificate and save it to the folder you created earlier.
  • Go back to your cygwin shell and press the spacebar.
  • Enter a password to use to generate the developer_identity.p12 file.
  • At this point, the script should generate 2 files:
    • DistCertificateSigningRequest.certSigningRequest
    • developer_identity.p12
  • For now, we will only need the "DistCertificateSigningRequest.certSigningRequest" file. Go back to the portal and select the "Distribution" tab on the Certificates page.
  • Follow the same steps to create a distribution certificate using the "DistCertificateSigningRequest.certSigningRequest" file
*NOTE* - You will want to save the private.key file and back it up. It will be required should you need to create any new distribution certificates. We are done with the batch file at this point. Now we need add our devices to the portal.
  1. Return to the iOS Provisioning Portal
  2. Click the "Devices" link on the left.
  3. Click the "Add Devices" button.
  4. Add all your devices you wish to test your app on. I believe you will need at least one device registered. You will need the UDID of your device which can be found in iTunes.
  5. Click submit after you have added all your devices.
Now we need to add our app to the portal.
  1. Click the "App IDs" link on the left
  2. Follow the instructions on the page and click "Submit" when you are done.
  3. After you have configured your App ID, click the configure link next to it.
  4. Follow the instructions on the page to configure your app.
At this point, we need to create a provision profile. A provisioning profile will allow us to specify specific devices that can run our app without having to download it from the app store.
  1. Click "New Profile".
  2. Fill out the form and hit "Submit"
  3. Click the "Download" button next to your profile and save it to the directory you created earlier.

Sign Up With PhoneGap Build

You can sign up with PhoneGap Build at https://build.phonegap.com/. The account requires very little information and is free.

Upload certificates to PhoneGap

Now that you have an account with PhoneGap, you should be able to upload all the certificates we have created to be used with a build on PhoneGap.
  1. Log into http://build.phonegap.com
  2. Click your email address in the top right of the page.
  3. Click the "Signing" link on the left of the page.
  4. Under the "iOS" section, click the "add a key" link
  5. In the Title, just give the certificate a name
  6. In the "certificate" box, select the "developer_identity.p12" file you downloaded from Apple earlier.
  7. In the "provisioning profile" box, select the "APPNAME.mobileprovision" file you downloaded earlier.
  8. For the "certificate password", enter the password entered into the batch file earlier.
  9. Click the "Create" button.

Upload HTML5 App to PhoneGap Build

At this point, you should have a functioning certificate registered with PhoneGap Build. To test this, you should create a simple web app to upload and build. The web app just contains HTML files, images, javascript files, etc. The app will look for index.html to start. If you are interested in writing more complex apps with PhoneGap, check out http://www.phonegap.com/start.

  1. Zip your HTML5 app into APPNAME.zip
  2. Log into https://build.phonegap.com
  3. Click the "New App" button at the top of the page
  4. Enter the name of your app
  5. Select "upload an archive or index.html file".
  6. Select the zip you created earlier
  7. Click "Create"
After you upload your app, PhoneGap will start a build.  You will see there is a exlamation for the iOS build.  We still need to assign the certificate to the app.

  1. Click "ADMIN" next to your app's name.
  2. Click "Edit" at the top of the page
  3. Click "Signing" on the left
  4. Next to iOS, select the certificate we uploaded earlier.
  5. Click "Update Code"

At this point, PhoneGap Build will start building all versions of your app, eventually providing you will an ipa file to install into iTunes.

PhoneGap itself can be integrated into XCode and built without the use of their Build service.  But this is the only Macless way I have found so far.

Install App Through iTunes

Once you have all this working, you should be able to download the .ipa file from PhoneGap Build.  Here are the instructions for installing onto your phone.
  1. Save the file to the directory created earlier
  2. Open iTunes
  3. Drop both the APPNAME.ipa and the APPNAME.mobileprovision files onto iTunes
  4. Plug in your iPhone/iPad 
  5. Select your device
  6. Select the Apps tab. 
  7. In the list of apps, you should see APPNAME as an option to check.  Check the checkbox next to it.
  8. Hit the Apply button.
At this point, you should see the icon in your device.  You have successfully built an app and installed it on an iOS device without ever touching a Mac.

If I have left out a step, or if you run into problems, let me know.  Hopefully this saves someone all the time I spent fumbling through this process.