Deploying a PhoneGap application to iTunes (App Store) [updated]

This article deals about deploying PhoneGap application to Apple App Store. Question: Is it possible without having a real Mac computer or using Mac-lease-like service? The quick an straight answer is: you can’t do this. It was possible around two years ago, but things has changed and s for now (2015) you must have any of above to submit your application to App Store.

This article was initially written on 18 June 2015 and generally updated 15 months later so you’ll find information and examples as they were available in mid-August 2016.

You don’t need to touch Xcode, SDKs or any other dev tools, but you must be in possession of any real Mac hardware (either your own, leased or in-cloud) to finish the submission process using Application Loader (using OS X system installed on not-Apple hardware, for example any PC, is illegal and not recommended, so won’t be dealt too much in this article). This is for the general picture. Now, let’s get into details.

This article is a companion text to Deploying a PhoneGap app to Google Play and Deploying a PhoneGap app to Windows Marketplace articles. It provides you with necessary information on how to successfully submit your .ipa file (compiled locally or in PhoneGap Bulid) to App Store.

This blog post is based on Windows and focuses to creating all the necessary files under Windows. The entire, long, process is much, much easier on Mac (as you can expect) and is briefly explained in this YouTube video.

Before you start

There are certain things you must be aware of before you even start reading further.

Legal rights!

To publish iOS application in App Store you need a serie of certificates. To create them you need to use SSL. SSL is legally prohibited in certain countries. That’s why on many pages like this one you’ll see notices like:

Note that this is a default build of OpenSSL and is subject to local and state laws.
Use of PuTTY, PSCP, PSFTP and Plink is illegal in countries where encryption is outlawed.

It is not a joke. It is your responsibility, that country, in which you’re living, using SSL and developing your Apple apps finds using SSL legitimate. Visit Crypto Law Survey for more information.

Do I really need a Mac?

Since my information turned out to be outdated, I asked this Stack Overflow question and very similar at PhoneGap Build support forum to update my knowledge and summarize current status. I have received many inspiring answers, which are summarized below.

You CAN’T submit an iOS application to App Store using only PhoneGap Build, without any kind of Mac hardware or without paid service like MacinCloud! Amen.

Submitting an iOS app to App Store, with just PhoneGap Build, was possible two years ago (as per Amir’s answer cited in the question), but it is no longer possible, as per this PhoneGap Build support answer:

Two years is long time in the land of technology. Yes, Apple introduced a new method of uploading applications, forcing the use of an actual Mac. As apps grew, the upload via a browser became problematic, so a custom app was built to manage that portion of the submission process.

I can add, that it also seems obvious for Apple’s business model, to force people to purchase even tiny, even old Macs just for the purpose of submitting app to app store.

Any alternatives?

You can compile your application (after enrolling to Apple developer Program — see below — getting all the required certificates and signing keys and uploading them to PhoneGap Build) up to getting final .ipa file, but you will still need something “Mac-related” to run ApplicationUploader and upload your app to store.

“Mac-related” means:

  • purchasing your own or lending someone else hardware Macintosh, nearly any kind,
  • installing OS X system on any of your PCs (Hackintosh),
  • running cracked version of OS X in VirtualBox (more),
  • making use of paid service like MacinCloud or AppStore Uploader.

First option seems best, as it is giving you maximum flexibility. If you’re not touching even a bit of Xcode (in the context of this question — i.e. building an app through PhoneGap Build) and other dev tools, then even used Mac mini would be good and you can purchase such for around 200-300 USD.

Second and third options are both illegal (Running OS X, even virtualized, on non-Apple hardware is a violation of the EULA for the software) and not recommended (any update of any app, OS minor update, etc, could break your HackIntosh), so should be considered as last option. Unless you don’t care about law.

Last option should be considered by developers, who submit a number of iOS apps (and an updates to them) low enough, so monthly or yearly MacinCloud paid plan become more reasonable than one-time investment in old Mac. And even for those, who have even lower requirements, a 1 USD / hour plan (30 USD / 30 hours pre-charge) sound as fair option. And for sure is legal and less time-consuming.

Or, if you have .ipa, you can pay 5 USD to AppStore Uploader and have your app uploaded for you.

This theory is confirmed by this PhoneGap Build support answer:

That statement is still valid. In fact, I have two new apps to be published today, and I’m going to use my Windows machine for everything except for the .ipa-upload part (which is one step within the process of using iTunes Connect in my browser on the Windows machine). The file upload takes place on my old Mac with Application Loader.

In the recent past, we have seen reports of developers, here in the forum, who had difficulties uploading through Application Loader. Turned out that everything worked fine again when they updated their installation of Xcode, although they never used Xcode for anything. Perhaps Application Loader uses Xcode modules under the hood on the same Mac…

Using VirtualBox seems like the fastest and the easiest of above mentioned. However, there are some glitches to be considered, which are discussed in following chapter.

A word about VirtualBox

You may want to give a VirtualBox a try, install Hackintosh into it, along with Xcode and try to upload your .ipa file from it. In this case consider following things:

  1. MacOS users are quite very sensitive when talking about Hackintosh issues and usually they don’t want to talk about this at all. Frankly saying, I’m not surprised at all. Be careful, what and when you’re asking and don’t be surprised, if you don’t get answer at all.

  2. You cannot install Virtual Box guest additions into MacOS. And since they’re needed to use shared folders feature of VirtualBox, you need to find another way of delivering .ipa file to guest MacOS (FTP, USB, file download etc.)

That would be all. Now, let’s deal with building process and everything else, you need to know, to get your first OS application published in App Store.

Enroll to Apple Developer Program

You have to options: to enroll as a single developer (valid and required also for single-person businesses) or as a company. Note, that this only settles things, like taxes etc., between you and Apple and has nothing to do with publisher name, under which your applications will be listed! In other words, you can enroll to Apple Developer Program as a single developer and still use a screen name suggesting, that you’re actually a company or developers group. You are not forced to list your applications under your real name, even if you enroll to the program as single developer or single-person business). Here is a cite from one of Apple Support emails, that I have received, to confirm above:

An iTunes Connect company name, also known as an artist name, is listed at the top of each app page in the iTunes App Store. The iTunes Connect company name may not always be the same as the seller name. The seller name is your company’s legal name as contracted with the Apple Developer Program.

Therefore, you will be able to choose an artist name, when you will add your first app (creation of the first app record). Please be aware that, once this artist name is set you won’t be able to modify it later.

To enroll as a company you need a D-U-N-S Number. If you don’t have one, you have to request one (free of charge), by providing necessary data to D&B (verification company used by Apple) and waiting few days.

Start enrollment process with going to your account settings and verifying, that everything there is correctly set and reflects actual, legal information. Especially, applicant name and birth date must correspond to your real name and actual birth date. Do not try to provide your company name on company found date instead. However, you’re free to use your company email address, if you wish to.

Next, visit Apple Developer Program enrollment page and fill out all fields in this quite short form. Once everything is initially verified with Apple, you should receive a confirmation, that your enrollment is being processed along your enrollment ID.

Now you have to give Apple some time to validate everything on the legal side of the case.

Create necessary files

To publish your application in App Store you must first sign it.

To sign your application you need:

  • a private SSL key for your base computer,
  • a Certificate Signing Request,
  • an iPhone Developer Certificate and
  • a Provisioning file.

Last two are essential ones, but you need first two to get third.

In other words, to get an iPhone Developer Certificate you need to create Certificate Signing Request at first. And to be able to create Certificate Signing Request you need your private SSL key for the computer, on which you’re going to perform all further operations.

Before you start reading this chapter, consider following:

  1. There’s a step-by-step guide in “Add iOS Certificate” section at Apple Developer portal, but it requires you to use a Mac machine and Xcode program. Here we try to achieve the same using just a Windows machine.
  2. There’s a great YouTube movie about creating iPhone Developer Certificate from Windows. Take it as a short check-list, if you don’t want to read entire section. Note, that it is over five years since publication of this movie, so some things changed and you’ll be forced to adjust reality to programs and web pages presented in this movie.

Yes, this is the long story, but it makes App Store the least shitful (i.e. most secure) application store in the world as not many shit-app makers are willing to go through that long path.

Private SSL key

If you have read any of my “Setting up password-less…“-serie articles (i.e. on how to configure password-less connection in either TortoiseGit, Netbeans or command-line) you should already have your private SSL key (actually: private-public key pair) and you may skip this section.

First of all, get a copy of OpenSSL for Windows. I suggest using Win32 OpenSSL from Shining Light Productions website. If you select different package (for example OpenSSL for Windows from GnuWin32 package) you may face additional problems, like missing openssl.cfg configuration files or similar.

As for Win32 OpenSSL, choose first (Win32 OpenSSL v1.0.1e Light; version number may change) package. If you’re on Windows 7 or newer, you’ll most likely also need Visual C++ 2008 Redistributables as these are not shipping with default installation of newest versions of Windows. Win32 OpenSSL installer is able to detect, that these files are missing on your system and warn you about that.

I strongly advice you to either use default C:\OpenSSL directory for installation or any other folder, that does not contains spaces. Windows ports of Linux command-line tools are known to have problems when Windows-like paths containing spaces are used as parameters. You may leave other settings in default values. Especially, since you’re going to use Windows command line, it is wise to order installer to install OpenSSL DLLs to the Windows system folder.

Run cmd. First, we need to create a private key. To achieve this, execute these (correct paths, if necessary):

cd C:\OpenSSL\bin
set OPENSSL_CONF=C:\OpenSSL\bin\openssl.cfg
openssl genrsa -out mykey.key 2048

As a result, file mykey.key should be generated in C:\OpenSSL\bin folder.

If you’re using OpenSSL to build an iOS application that will ever bring you any profit then you should strongly consider donating some bucks to OpenSSL creator. Consider the fact that without it you wouldn’t be able to go through this guide.

Certificate Signing Request

Next, we need a Certificate Signing Request. To do this, execute:

openssl req -new -key mykey.key -out CertificateSigningRequest.certSigningRequest -subj 
"/emailAddress=yourAddress@example.com, CN=John Doe, C=US"

Make sure, that you provide details (especially email), that matches exactly your Apple Developer account. As a result, you should have file named CertificateSigningRequest.certSigningRequest in the directory, where you executed above command (i.e. in C:\OpenSSL\bin).

If you need more info on using OpenSSL, then this article with some additional links may help.

iPhone Developer Certificate

Now, go to “iOS Certificates” in Apple Developer portal, select type of certificate (either development or production — see below), go through all steps and upload your CSR, that you have just generated.

As a result your certificate (iOS Development or iOS Distribution type) will be created and you should be able to download it (at once or from iOS Certificates).

Here is, when you can download your certificate:

  • if you’re an individual developer — you must click Approve and then you can download your certificate,
  • if you’re enrolled as a company or part of the team and you’re team / company leader — your key is ready at once,
  • if you’re regular member of a team or company — you must wait until responsible person approve your key for you.

If you need to create another certificate then either click Add another button in certificate generation confirmation screen or hit + button in iOS Certificates section of you Apple Developer account.

If you’re enrolled to Apple Developer Program as a company then:

  • iOS Development certificate will be signed with your name and
  • iOS Distribution certificate — with your legal name given during enrollment.

Legal name is obtained from D&B (see previous chapters) and usually it is your company name.

If you have enrolled as individual developer then both keys will be signed with your own name.

Now, we’re going to create .p12 file.

  1. Open command line and navigate to bin folder in OpenSSL’s installation folder.
  2. Copy your .cer file (downloaded from developer portal) and .key file (generated in previous step) to bin folder
  3. Name them with some short names (to type their names easily in console commands), i.e. ios_dev.cer etc.
  4. Execute openssl x509 -in ios_dev.cer -inform DER -out ios_dev.pem -outform PEM command.
  5. Verify, that .pem file with name corresponding to your .cer file has been correctly created in bin folder.
  6. Optionally repeat these steps for other certificate (i.e. for distribution one).
  7. Execute openssl pkcs12 -export -inkey mykey.key -in ios_dev.pem -out ios_dev.p12.

When asked to provide a password, provide any twice and hit Enter to confirm. Remember the password, as you will be asked for it in any program or service, in which you’re going to use generated .p12 file.

Generated .p12 file is your own iPhone Developer Certificate.

Note, that all files, you have created so far (.cer, .certSigningRequest and .p12) you should have in two copies (versions) at most (i.e. development and distribution), as you’re single developer or you’re representing a single company. However, for all following files you must create single, separate file for each and every application, you wish to provide to App Store.

Device UUID

Get your device’s UUID:

  1. Plug-in your iPhone or iPad to your PC via USB.
  2. Run iTunes (you need to install it, if you haven’t done so before) on your Windows.
  3. Click a small button next to Music dropdown in top-left corner (below menu).
  4. The Summary page should be displayed by default and you should see Serial Number below Capacity.
  5. Click it to see and read UUID; write it down.

For tests you can use a fake UUID — E0101010D38BDE8E6740011211Af315301010223.

If you still have troubles reading your UUID then this article may help. In general, you can install a software like UDID directly on your mobile device or iPhone Configuration Utility on your PC. Even though some claims, that it is gone, it seems, that you can still install it for Windows from cnet.com (never tested it!).

Note, that installing iTunes on Windows also installs (without your agreement — hello, Apple!) a whole bunch of supporting shit like some mobile device drivers, network protocols etc. I found six new items in Program and Features list after installing iTunes. Thus, you may strongly consider uninstalling iTunes for Windows, if reading UUID of your device was the only reason for installing it.

Provisioning file

First, we need to create an application ID.

  1. Go to Identifier section in Apple Developer account, click on + and Continue.
  2. Provide all the information, that is needed:
    • App ID Description: usually Application Name,
    • App ID Suffix / Explicit App ID: usually com.company_name.application_name,
    • App Services / Enable Services: select, whatever you need (usually default and required Game Center and In-App Purchase are enough).
  3. Click on Continue and Register.
  4. You should see a confirmation, that your new App ID can be used in your provisioning profiles.

The Bundle ID, you define in step 2, will be later used to deploy an .ipa file to App Store.

Next, we need to register a device:

  1. Go to Devices section in your Apple Developer account and click on +.
  2. Provide your device name and UUID, you have just read.
  3. Click on Continue and Register.

Registering a device is essential, because only on registered (and included in provisioning profile — see below) devices you will be able to install a test version of your application.

Without this step, the only other distribution channels is either official (install application from App Store) or unofficial (upload .ipa file to jail-broken device).

You must repeat above steps for every test device, on which you plan to test your apps.

Finally, we can create a .mobileprovisioning file. Uploading it along with .p12 file to PhoneGap Build is an essential step to be able to test and distribute iOS applications.

  1. Go to Provisioning Profiles section and click on +.
  2. Select proper type of provisioning profile:
    • Development / iOS App Development for tests or
    • Distribution / App Store for actual distribution or
    • whatever type of provisioning profile you need (like some Apple TV).
  3. Select App ID. Click on Continue.
  4. Select certificate(s) (the one matching provisioning profile type). Click on Continue.
  5. Select all devices, on which you’re going to install application signed with this provisioning profile. Click on Continue.
  6. Name your provisioning profile and finally click on Continue.

5th step is skipped when creating a provisioning profile for official application distribution. Application submitted to App Store can be installed on any device.

Now (finally!) you have both .p12 and .mobileprovisioning files which allows you to create .ipa file in PhoneGap Build and to submit your application to App Store.

You must repeat above steps for every single application, that you plan to build or submit to App Store.

Build your iOS application in PhoneGap Build

Add your signing files to PhoneGap Build

  1. In PhoneGap Build go to Account > Edit Account > Signing Keys.
  2. Click iOS > add a key ... and name your key.
  3. Select .p12 and .mobileprovisioning files and submit them.
  4. Click on yellow padlock and provide your password set during .p12 file creation.

You must repeat above steps for every single application, that you plan to build or submit to App Store, as each single application uses the same .p12 file, but different .mobileprovisioning file. You also must repeat these steps for every alternative key, i.e if you wish to build your application for development / tests or distribution / App Store upload.

Build your application

  1. Upload your application to PhoneGap Build the usual way, either by using .zip file or GitHub repository.
  2. Go to your application details screen.
  3. Select proper iOS key.
  4. Rebuild process should start automatically.

After a while You should be able to download your .ipa file.

If you:

  • use an iOS device for testing and,
  • you have registered that device with your Apple Developer account and included it in your provisioning profile,

you can go directly to PhoneGap Build on that test device and install the .ipa file from there — you don’t need to build an .ipa file and provide it to your test device. This won’t, of course, work for distribution version of applications, as they may only be installed directly from App Store.

Deploy an .ipa file to App Store

In short: You need to provide your application details in iTunes Connect and then use Application Loader.

Create application’s record

Go to My Apps section in iTunes Connect, click the + button and then select New App.

If this is the first application, you’re adding, then you’ll be asked for providing your company name. This is extremely important step for you, because you will not be able to change it (for this or any other application). Let me remind you Apple Support email, I cited in the introduction to this article (emphasis mine):

(…) you will be able to choose an artist name, when you will add your first app (creation of the first app record). Please be aware that, once this artist name is set you won’t be able to modify it later (…).

Provide Bundle ID, you have created when creating provisioning profile. If your bundle ID is missing, you can register a new one on the Developer Portal. Note, that you have to log-off iTunes Connect and login again to it, after adding new bundle ID, to actually see it in the New App window.

Once new application is added, remaining steps includes:

  1. Provide basic information in App Information and Pricing and Availability sections.
  2. Provide additional information (i.e. icon, version, description etc.) in 1.0 Prepare for Submission section.
  3. Upload the 1024×1024 pixel icon and your optionally application screenshots.
  4. Save all provided information.

Hit Submit for Review button to double check, that Build section is the only one with error (exclamation point), i.e. that only missing application upload prevents you from submitting your application for a review and all other requires sections, information and files are correctly provided.

Now, submit your build using Xcode 6+ or Application Loader 3+.

Upload app with Application Loader

Before you use Application Loader (you will find it in Xcode > Open Developer Tools > Application Loader) on Mac-like (see introduction) machine to actually upload your .ipa file, you must deliver that .ipa file to device or solution, you’re going to use:

  • for real Mac hardware use any way to deliver file (i.e. USB, direct to disk copy, network share etc.),
  • for Hackintosh use your head, brain and Google as I don’t know and don’t want to know, how to achieve this there,
  • for making use of paid service like MacinCloud or AppStore Uploader, use their instructions for file upload process,
  • for running OS X in VirtualBox (more), go to introduction of this article, where this topic is discussed in details.

Note, that OS X, as a guest system, does not support shared folders in VirtualBox, so you can’t use this functionality to provide .ipa file to your “Mac”. Also, share clipboard feature seems to be not working and thus you must type all URLs manually.

Wherever your MacOS is, open Xcode > Open Developer Tools > Application Loader:

application-loader

and sign-in with your credentials.

Remaining steps includes:

  1. Select Deliver Your App and then Choose.
  2. Pick an .ipa file and click on Open.
  3. Review application’s information correctness and hit Next.
  4. Wait for application upload process’ sub-steps to complete (can take up to few minutes).

If there are no errors (like missing asset, missing or incorrect required file, unsupported devices or system versions etc.), your application should be uploaded to App Store and you should be able to go back to My Apps section in iTunes Connect to submit your application for a review.

Note, that Application Loader uses non-standard ports, other than 80, for communication with App Store.

These are:

  • 443 for DAV/HTTPS transfer protocol,
  • 33001-33100 for Aspera transfer protocol,
  • 44001-44100 for Signiant transfer protocol.

If all of these ports are blocked in your network, you won’t be able to upload your application to App Store and you may receive some errors about invalid application record or incorrect bundle ID.

Some additional details on uploading .ipa file to App Store can be found in here and in here. You’re welcome to read these articles, if something went wrong or if you wish to expand your knowledge.

Conclusion

We’re done! I hope you have succeeded and reading this (one of the longest articles in my entire blog) was worth all the time you spent on it. What are the next steps?

Once your application gets enough audience (or maybe right after you publish it), you may consider monetizing it and earning a few bucks on displaying ads in it. I’m using (and strongly suggesting) AdMob ads with AdMob Plugin Pro for this purpose.

Leave a Reply