How to deploy a PhoneGap .IPA file to the Apple App Store

By SuperUser Account on 4/28/2014

Until today I was posting my blogs here http://alpinetech.wordpress.com until I discovered I could not make any images without gaining another subscription fee.   I don't mind subscription fees, in fact I have dozens of them, perhaps hundreds, I really don't know anymore... Anyway, I'm already paying for this website space and it let's me post images...

I’m in the process of submitting the DATA-EASY Field Data Collector app to the three big app stores belonging to Google, Apple and Microsoft.  Two submissions down and one to go.  I’ll skip the chatter and cut to the matter of this post.  I’m a PC-Guy, who used to be UNIX-Guy who owns an iPad and an Android phone.  I’m not a Mac-Guy.  This is what I learned submitting my PhoneGap App to the Apple Store.  Like so many technical things today, there’s a lot of “lore” out there about doing that.  Getting through the stale, incorrect and half true information is the biggest challen to getting a PhoneGap App built by build.phonegap.com submitted to the Apple App Store.  

First, you’ll need to develop your PhoneGap App.  I highly recommend using build.phonegap.com to “build” the app.  Someday I might write another blog post just about that (or did I already?). Ultimately, you can develop your code, zip it, upload it and get it back down from build.phonegap.com in seconds.   To do this for iOS (Apple), you’ll need to upload a “key” so build.phonegap.com can “sign” the app with your “key”.  That’s a process in itself.  I accomplished it by downloading OpenSSL for windows and running some commands at the DOS prompt to generate a private encryption key and digital certificate request, but recently I ran into issues with the OpenSSL version I downloaded (probably something to do with the Heartbleed thing).  So, if you go that route, try to find something compiled for Windows very recently, so it will have the fix for Heartbleed in it.   In short, here’s my commands to gen the key and the request:

openssl genrsa -out private.key 2048

openssl req -new -key private.key -out  certificate-request.csr  –subj "/emailAddress=brianj@alpinetechsolutions.com, CN=brian johnston, C=US"

Next, if you don’t have one yet you need an Apple Developer account for iOS from developer.apple.com for $99 per year.  Once you have that you can login and go to the “Member Center”, “Certificates, Identifiers & Profiles”, “iOS Apps”, “Certificates”.  In that interface you can click the “+” in the upper right and be led through submitting your certificate request .CSR file.  Name it something like “iOS Development” because you will want to generate another one named “iOS Distribution”.  You might as well do both at the same time if this is the first time through the process.   In my case, they each have different keys and certificate request files, but I imagine you could use one for both (not certain on that).  Next, you will need to make an App ID in reverse domain naming notation E.G. “com.alpinetechsolutions.fdc”.  Next, click on the “Devices” section and add the UDID of any devices you intend to test upon.  There’s lots of instructions out on the net about getting your UDID like this one.  Finally, you’ll create the “Provisioning Profiles”, one for development and one for the App Store.  Once completed, you’ll need to click on the Provisioning Profiles and the Certificates and then download them to your computer.  You will use those files to generate a .PK12 file, which is required  by build.phonegap.com to create a “key”.  Run these commands to do that: .  (Note, the last time I tried to generate the .P12 file on Windows with OpenSSL for Windows, it failed.  I had to login to a Mac and do it there (found a UNIX prompt there).  However, this might be an isolated issue because months ago on another PC I accomplished it with no issues.  There are several interfaces to OpenSSL so somehow you can do it.)

openssl x509 -in ios_distribution.cer -inform DER -out the.pem -outform PEM

openssl pkcs12 -export -inkey private.key -in the.pem -out the.p12

You’ll have to do it twice again, once for a Development Key and another for the Distribution / App Store Key.   Now you have everything in place to upload your PhoneGap code to build.phonegap.com and have them build an iOS install package (.IPA file) for you.   Build.phonegap.com  is very easy to use.  You’ll create an application entry on the website, upload your PhoneGap App code (just the www directory) in a .ZIP file (or pull it from a GitHub repository).

If you are new here, you might ask where does the PhoneGap App come from?  If you go the PhoneGap.com website it provides all you need to download and install the PhoneGap framework and create the App on your drive.  However, you don’t have to do that (it get’s pretty complicated).  I found out, after going through all that, that there’s no reason you need to install PhoneGap if you use build.phonegap.com.  All you need is a set of directories (essentially a website) which has the bare minimum PhoneGap files and directories in it.  I’ll write another blog post later and provide a link to a .ZIP file with the bare minimum files (I’m sure someone else has already done that).   The most important file in PhoneGap source code directories is the config.xml file.  In that file you specify which platforms you want build.phonegap.com to "build” install packages for.  As of the latest 3.0+ version of PhoneGap that can only be Google (.APK), Apple (.IPA) and Microsoft (.XAP).  Pre version 3.0 you can specify several additional platforms including Blackberry and Palm (or whatever it is called now).  I’d be asking why use PhoneGap 3.0+ if you lose the other platforms? Good question.  That’s because you can NOT deploy to the Apple App Store with pre-3.0 PhoneGap any more, it is NOT supported.  However, if that’s not an issue for you then have at it.  Also, be aware some of the plugins, such as the file system plugin, (which are taken from the Apache Cordova Open Source project) were changed considerably at version 3.0.  Anyway, this road is filled with side streets…  At some point in this process you will be prompted by build.phonegap.com to create a key for the iOS build package which will require the provisioning file you downloaded from Apple and the .P12 you generated with OpenSSL.  Upload those files, provide the password to your key and presto, build.phonegap.com takes ordinary HTML and Javascript files and builds a iOS native application on it.  Now if you have an iOS device with it’s UDID setup in the developer.apple.com iOS member site, you simply use a QR code scanner to install the .IPA file they built for you.  Ultimately, the upload, the build and the download process can occur in less than a minute.   Also, if you have other testers and developers, simply register their iOS UDID numbers and send them to your build page where they can instantly scan, install and run the app built there.  Very cool stuff.

If you follow the steps above, you should be developing and testing your build.phonegap.com App on iOS, but you have a ways to go to get it submitted to the Apple App Store, and trust me the “lore” in that area is thick.  The challenge is at this point you have an .IPA file that runs on the devices you register in your Apple Developers Account (I think the max is 100) but on no other devices until it gets into the Apple Store (or you deploy a company version of the app).   If you take that .IPA file and submit it to the App Store, you’ll need to do the following.

First, I understand it is better to use a separate provisioning profile to do that.  Since the provisioning profile is tied to a certificate which gets bundled into a .P12 file required by build.phonegap.com to sign the app with the certificate belonging to that provisioning profile, you end up with two of all the files described so far.  That’s why I suggested you generate both provisioning profiles earlier, one for development / testing and another for the app store / distribution.  Now you’ll need to add another key, based on the distribution provision certificate .P12 file and distribution provisioning file created earlier, to your app entry in build.phonegap.com for the App Store distribution version of your App.   This is the same process as the one described above for the development / test version and at the end you'll download the .IPA file and submit it to the Apple App Store.

First, you need to setup an App Store profile / account for yourself and your App.   This is done with “iTunes Connect” and you don’t need a Mac to do that since it is a web interface.   There you will be led through the process of defining the App Store face of your application and how it will hook into the “monetization” opportunities offered there.  Technically it is not too hard.  Be prepared with some good marketing mumbo-jumbo and be prepared to build / resize screenshots in specific sizes (one set for each possible iOS device). I found out they will give you a confusing  "Missing Screenshot" error message hours after you submit your app if you don't provide screenshots for all the sets.   In the end, your app is set to a “waiting for upload” state.   Second,   decide how to submit /upload your .IPA file. You have two choices, sorta, 1)  with X-Code or 2) the Apple Store Application Loader.  Both of these are Apple applications that  run on a Mac (surprised?).   I don’t own a Mac and I just want to get my software in the hands of customers without spending a lifetime (and some cash) setting up another computer and learning another development environment to do it.   That’s why I signed up with macincloud.com.  For about $1 an hour, you rent a Mac and remote into it.  Brilliant!  (Actually I found out I do like Macs after all, I might switch.).    Macincloud.com is awesome.  Everything is already on there for you, OpenSSL, the Application Loader, X-Code, etc. 

If you were to choose X-Code this is what  I found down that road.  Apparently, like all things Apple, if you were to develop your entire App in X-Code then you will have some nifty App Store integrated tools to automate the deployment end of the process and will avoid most of the “lore” as a result.  I briefly looked into finding a good way to get my PhoneGap App in on the X-Code App deployment production line, but it appears that you can’t wedge a nearly finished Volkswagen into the Porsche factory production line and expect a Porche built Volkwagen at the other end.  In other words I saw no practical way to use X-Code  to deploy a PhoneGap built .IPA  file.  Consequently, I went the other route and deployed the .IPA file to the Apple Store with the Apple Store “Application Loader”.   It was simple.
1.build the app with the App Store Distribution key you have created on build.phonegap.com.
2.login into the Mac at macincloud.com, open Safari and download the .IPA file from build.phonegap.com
3.start the Application Loader and “send” the .IPA file to the Apple App Store. Done, almost….

Now the fun begins again and if you’re still reading this, all the time you thought you lost doing so will be made up for in these paragraphs below.   First, I got the error message below with several others and warnings as well.   This seemed to be the main one that stopped the App submission.  At the end of the message you are referred to some Apple guides to help you.  I’ll save you the trouble, they don’t.  Perhaps I did not read enough, but I skipped around looking for what I have to read to fix this error and ended up going out to Google for more “lore”.

 

You'll probably see some warning messages like this too:

 

Well the error message referrers to a couple of tables (see below) buried in a document which provide these names, which are actually guidelines for names, not the specific names required, oh but some of the names are specifically required.  Confused?  I'll provide the exact list below and prevent you the hassle I had un-raveling this spaghetti.

 

 

Somewhere in the technical spaghetti you’ll end up in another document which gives you these tables, which are clues to another piece of the error message puzzle Apple gives you.

 

 

So the error message basically said a required launch image file was missing from my .IPA file.  Apple requires a specific file which is not listed or described in anyway in the two tables above, and that file is just the beginning….  (Help us out and post a correction reply if I ended up in the wrong docs.)  I finally found some lore out there that solved the riddle. Apple requires a file, not listed in the documents error message refers to, named “Default-568h@2x.png”.  Further lore surfing revealed that file must contain an image which is exactly 640X1136 pixels.   Actually, several other files are required as well, but in my case that’s the first one Apple found that the build.phonegap.com .IPA file did not have.  I discovered in subsequent submissions that there  must also be files named “icon.png”, “icon@2.png”, “default.png” etc. etc.   And they have to be certain sizes, which was very hard to figure out since I only found the incomplete guidelines for the names of the files in one document and the incomplete list of sizes in another, with no x-ref between them.  

To get these files into your .ipa you have place them into the "res" folder of you PhoneGap source code project and then put reference settings to them in the config.xml file.  Here's mine:

  res/icon/ios/Icon@2x.png" height="72" gap:platform="ios">
   
   
   
    res/icon/ios/Icon_Settings@2x.png" height="58" gap:platform="ios">
   
   
   
    res/icon/ios/Icon-Small@2x.png" height="80" gap:platform="ios">
   
   
    res/screen/ios/Default@2x.png" height="960" gap:platform="ios">
    res/screen/ios/Default-568h@2x.png" height="1136" gap:platform="ios">
   
   
    res/screen/ios/Ipad-Landscape@2x.png" height="1536" gap:platform="ios">
   

A complete list of the image files required in your .IPA with x-ref to the sizes they must be.  TA-DA!

Launch Image Files

Icon Image Files

Yes I know I just added to the “lore” out there, and the information probably has a shelf life of -1 days, but here it is.   Hope this saves you some time.  Good seeing you, have your people call my people :-)