June 3rd, 2009
iPhone 101: Understanding Distribution (Pt I of II)
When I first started dabbling with Objective-C and iPhone development I found the entire learning process cumbersome and frustrating. In fact, many days I still do. Often Apples documentation seems dated, complex or difficult to find. The hangover of the NDA from the early era of iPhone development still lingers there is a dizzying amount of information to consume and understand before you can develop for this phone.
Im going to start with an extremely important topic that has a great deal of conflicting information online and doesnt require a lick of code knowledge: Apples certification and distribution procedures. In order to test anything on a phone or submit for review to the App Store, one must follow a very specific set of steps. It’s not as easy as hitting the “Publish” button or uploading a file to some server somewhere.
This two-part tutorial will cover common got-yas and some important notes on 3rd party development, so I highly recommend giving it a gander if you’re green to the whole iPhone app store process. Part I covers generating a valid development or distribution certificate. Part II covers provisioning devices, iTunes connect and pulling everything together.
There are three different kinds of certificates to an iPhone application. The first is the Apple Worldwide Developer Certificate (WWDC). This can typically be downloaded from Apples portal, though I have seen strange 404 errors attempting to do so before. Im not certain if its globally shared (I think it is) and if so will be happy to mirror it on our site to help ensure its at least somewhere on the Internet. This certificate is compiled alongside one of the other two kinds of certificates: Either a Developer certificate or a Distribution certificate. These are used for testing applications and deploying to the Apple Store, respectively.
In order to understand how one uses these certificates, we need to understand the process for generating and administrating them. Creating and utilizing the certificates is a funny song and dance between the iPhone Developer Portal, Keychain Access (an application on your Mac) and XCode.
The iPhone Developer Portal
The iPhone Developer Portal is a web site used to manage all of the various build settings for an application. Before you can even begin to think about testing an application on the phone you need to understand this site. To begin with, let’s discuss the three different permission levels members of your development team can have: Agents, Admins and Developers.
Upon purchase THE ACCOUNT TIED TO THE PURCHASE OF THE LICENSE BECOMES THE TEAMS AGENT. Changing this requires getting in touch with Apple directly, so make sure that your agent is someone accessible or their password can be freely distributed amongst your company. You may need it later.
Agents are sort of like superadmins. They have the ability to create new projects, add devices for ad-hoc provisioning, approve & create development or distribution certificates and control the privileges for other team members. They are also the main administrator of iTunes Connect, the portal for submitting applications to the App Store for review. Well cover that more in a bit.
Admins have all of the access to do everything discussed above except they cannot create distribution certificates. An agent can email an Admin (or a developer, for that matter) a distribution certificate.
Developers have access only to request a developer certificate. Each developer is supposed to have a unique developer certificate, though this too can easily be shared.
Adding members works very similar to a social network: You simply invite a person via a form on the portal to contribute to your team. I haven’t attempted to put the same email address on multiple accounts, but I have a feeling that an email address is uniquely tied to that team. This means that if you have multiple iPhone Developer accounts — and as we’ll soon learn for 3rd party development, this is a must — you will need a new email address each time you kick off a project with a developer on it. This is
So lets pretend youre setting up your first project for ad-hoc distribution and that youre given Admin access. The first thing you need to do is create a new application ID. Like Adobe AIR (or ActionScript class packages), each application ID is required to have its own unique namespace that looks something like com.yourcompany.YourApp. You can set this to whatever you like, though I have seen issues (the app wont compile,etc) with any namespaces more than three levels deep. Also, in order to ensure that there are no conflicts whatsoever, Apple generates a random string before your namespace, so the final output will wind up looking like ABC123.com.yourcompany.YourApp. As a final note, you can use * to denote that youre going to use a global namespace which will allow you to easily construct new unique applications without having to go back to the iPhone Developer Portal each time. We use com.bigspaceship.*, for example. Just seems easier to deal with.
IMPORTANT!: One important thing to understand about application IDs is that because they are given a uniquely generated namespace there are massive implications for 3rd party iPhone development. You cannot (as far as I can tell) transfer this unique ID to another party. If youre building an iPhone application for a client and they own the source code, it is highly recommended they acquire their own license and you build as a member of their team rather than generating an application ID on your space unless you plan on being responsible for their app store submission for all future updates.
Once this application ID is generated, jump into your Info.plist file for your project in XCode. Set your bundle identifier to com.yourcompany.YourApp (if you used a wildcard, you can set it to com.yourcompany.WhateverYouWant). DO NOT ADD THE RANDOM STRING APPLE GENERATES. Apparently in older versions of the SDK you needed this, but it will confuse the compiler now. The application ID in your Info.plist MUST match the namespace on the iPhone Developer Center or youll get weird errors.
Generating a certificate
Now since you know were testing, you need a developer certificate. The first thing you need to do is crack open Keychain Access. If youve never opened it before, it looks sorta like this:
One thing that tripped me up for awhile is that the Keychains header in the top left of the application is actually sort of like a folder. Category underneath it is like a subfolder of that. So selecting System->Certificates is going to show me a different list than login->Certificates. Were going to be dealing entirely with the login folder, so always make sure thats selected. Oh, and well jump in between the Certificates and Keys categories a good deal here, too.
In the upper right corner of your screen next to the Apple Logo, choose Keychain Access->Certificate Assistant->Request a Certificate from a Certificate Authority. The form you fill out needs to EXACTLY MATCH THE INFORMATION on the iPhone Developer Portal. If your name on the portal is spelled all lowercase, spell it all lowercase here. This is an extremely important step.
The CA Authority email address should be the email address for either the Agent or an Admin on your iPhone Developer portal. If youre an agent, go ahead and fill out your own email address. Select the Saved to Disk option and save it on your desktop. You can name the file whatever you want to, well only need it for a few minutes.
To verify that things are going well, jump to the Keys category in KeyChain assistant. You should see a public and private key for your common name.
If for whatever reason you screw up your common name or email address or it just doesnt work, you must destroy these two keys by simply selecting and deleting them. Once you do that you can create a new certificate request by following the steps earlier.
Jump to your iPhone Developer Center and upload your certificate request. If youre an Admin go ahead and approve it right away, if not go yell at your admin to approve you. Within a few moments (admins: refresh the page a few times) youll have a certificate to download. Download it, double click, install it to login and youll see a new pretty certificate in your Certificates category.
IMPORTANT!: You should strive to only keep one developer in your keychain access at a time XCode has been known to get a bit confused when attempting to compile with multiple certificates in the Keychain. But be warned! Deleting a certificate cannot be undone. Dont delete a certificate before youve exported it. To export, simply click on the Certificates category, right click your certificate and select Export. Follow the instructions on screen and save the file wherever you want. To reinstall the certificate simply double click if youre savvy youll notice the Public Key is gone for good in the Keys category, but it doesnt seem to affect anything so dont worry about it. This is also useful to know for 3rd party development. I have a folder with a whole slew of different certificates depending on the client, so I can add and remove as needed.