Update, November, 21st 2008: Apple has made some significant changes (simplification) with the release of version 2.2 of the iPhone SDK. This post relates to version 2.1. I'm going to update it accordingly to cover both versions later today. Until this note is gone, please do be aware that this post only relates to version 2.1!
Given the wide popularity, the enormous amount of comments and personal feedback I've received so far for my first post about iPhone mobile provisioning and the ongoing discussions in various developer communities related to this topic, I've decided to write a follow-up on how to address mobile provisioning issues that tend to arise time and again.
While Apple has made some enhancements to the documentation available in the iPhone Developer Program Portal – you need to be logged in to access the linked content – there still seem to be many problems out there with respect to setting up and maintaining an iPhone development environment.
I'm trying to provide as much detail as possible for the more subtle parts of the process. I highly recommend to go through all the documentation made available by Apple before consulting my post – specifically you should carefully go through this guide. This post should be considered complimentary.
As always I don't take any warranty for the material provided here. Use at your own risk!
Prerequisites
Here is a brief overview of the environment I'm working with:
- I'm an approved and paying member of the iPhone Developer Program.
- I'm using an Intel iMac with Mac OS X 10.5.5, Xcode 3.1.1 and the final version of iPhone SDK 2.1.
- All my iPhones are running Apple's regular firmware version 2.1 (5F136). I've got legal net-lock and sim-lock free iPhones. No jailbreaks. No hacks.
- I'm not using any methods to circumvent Apple's code signing practices and generally do not endorse those.
The Developer Program Portal
Before you begin to develop applications for the iPhone make sure you log into the iPhone Developer Program Portal. Note: There is a difference between the Developer Center and the Developer Program Portal. Access the Program Portal from within the iPhone Dev Center by clicking the iPhone Developer Program Portal link:
iPhone Developer Program
Let me clarify an aspect which has caused some confusion in the past: To start developing for the iPhone you do not need to be a paying, registered member of the iPhone Developer Program. The SDK is available for free and can be downloaded after a brief registration. Once you've got the SDK you can create applications and test them on the iPhone Simulator that ships with it.
If, however, you want to deploy your application to an actual device – either an iPhone or an iPod Touch – you need to be a paying, registered developer.
While the simulator is good to get up to speed I highly recommend to not underestimate the differences between the real device and the simulated environment. Simulator applications not only run on a different architecture (Intel vs. ARM) but I've also run into situations where stuff perfectly worked in the simulated environment but failed on the device. In addition the layout on the iPhone is sometimes slightly (a few pixels) different than the one on the Simulator. If the UI of your application requires pixel precise positioning, you have to deploy to the device to get things right.
Apple has created a complex security ecosystem to endorse its FairPlay digital rights management and to control digital distribution of iPhone applications.
Certificate Mania and Provisioning Profiles
Let's clarify some terminology:
Development Certificates
Every approved iPhone developer needs a
Development Certificate. The steps required to create your certificate include issuing a certificate signing request using the
Certificate Assistant provided by the Mac OS X
Keychain Access tool. Follow Apple's guide to create your certificate. It's very detailed and appropriate for this part of the process.
Mobile Provisioning Profiles
While the certificates stay on your Mac and are used to digitally sign the applications you've created, Mobile Provisioning Profiles are transferred to your development devices. Currently there are three types of mobile provisioning profiles:
Development Provisioning Profiles are used exhaustively during the development of an application. They allow Xcode to directly deploy an application to a development device and attach the debugger. Development Provisioning Profiles only work reliably on devices that have been connected to Xcode at least once and "switched into development devices". You should in general not use Development Provisioning Profiles to provide your friends with your applications for testing.
Ad Hoc Distribution Profiles are used to deploy your application to devices outside your development environment, primarily for beta testing. You can register up to 200 devices and use an Ad Hoc Distribution Profile to allow their owners to run your application. Ad Hoc Distribution Profiles usually are installed onto the devices via iTunes or the iPhone Configuration Utility.
App Store Distribution Profiles are used to distribute your application via Apple's iTunes App Store. They can only be used for this purpose. You cannot install applications bundled with an App Store Distribution Profile manually to any device. It has to go through the App Store.
In short: Use a Development Provisioning Profile yourself, use an Ad Hoc Distribution Profile for your friends and use the App Store Distribution Profile for Sale!
Getting ready
Installing the certificates
- Go to the Certificates > Development tab.
- Download the WWDR Intermediate Certificate.
- Download your personal Development Certificate by clicking the Download button in the Actions column.
- Install the two downloaded certificates by double-clicking them. This will launch the Keychain Access application. Make sure you install to the login chain which should be selected by default. Validate that your keys have been correctly installed by opening Applications > Utilities > Keychain Access and expanding the iPhone Developer: Your Name section in the login Keychain.
Registering devices
In order to use Development Provisioning and Ad Hoc Distribution Profiles, you need to register the devices with Apple.
- Open iTunes with your device connected.
- Select your iPhone in the Devices pane and choose the Summary tab.
- Click once on the Serial Number: label. Do not click on the serial number, you need to click on the label.
- iTunes will reveal your Device Identifier.
- Press Command-C to copy the Device Identifier to the clip board.
- In the iPhone Developer Program Portal go to Devices > Manage.
- Click Add Devices.
- Enter a speaking name into the Device Name field and paste the Device Identifier into the Device ID field.
In case you want to send your app to your friends to involve them into beta testing, ask them for their Device Identifiers and register their devices, too.
Generating Application IDs
App IDs are an important piece of the overall iPhone developer infrastructure and one, where I found many people struggling with subtle details. Unfortunately neither the iPhone Developer Program Portal's How to section nor Apple's guides are extremely clear on what needs to be done to get things going.
An App ID is a unique digital fingerprint that OS X iPhone uses to grant your application access to a portion of the Keychain and is one part of your provisioning profiles. In the App IDs section of the iPhone Developer Program Portal create an App ID if you have not yet done so. You can give your App ID an arbitrary Name. The name is used for reference purposes only.
The ID itself however must be unique. Therefore most developers use a reversed version of their domain name (or their companies domain name) as it is pretty common for namespaces. In case you don't want to register every single application you're going to build, you can create a single App ID which serves as a namespace for multiple apps. For example, I'm using the following ID:
com.straight2market.*
Important Note: Apple generates a
Bundle Seed ID for every App ID you create and appends it to your App ID as a prefix,
however, the Bundle Seed ID must not be considered as a part of your App ID. So whenever you're prompted for your App ID anywhere in Xcode or elsewhere, you must only use your App ID without the Bundle Seed ID. To make this very clear: In my case in the ID column of the Portal it says
C5LRL9WHCV.com.straight2market.*. The "C5LRL9WHCV" part is the Apple generated Bundle Seed ID and only the
com.straight2market.* part is my App ID namespace!
- Go ahead and create your App ID by going to App IDs > Manage in the iPhone Developer Program Portal
Setting up Mobile Provisioning Profiles
Next set up at least two Mobile Provisioning Profiles, one for Development and one for Ad Hoc Distribution. Provisioning Profiles serve as the glue between certificates, App IDs and devices and link them together.
Set up your Development Mobile Provisioning Profile first:
- In the iPhone Developer Program Portal go to Provisioning > Development.
- Click Add Profile.
- Enter a speaking Profile Name. I highly recommend to put the term "Development Profile" somewhere into your profile's name. This will make it more easy to differentiate the profiles later on when you set them up in Xcode. My profile is called "straight2market Dev Profile".
- Select which certificate should be used for the profile.
- Select the App ID for the profile.
- Check all devices that should become deployable targets for the profile. Note: You might want to register additional devices at a later point of time. This is no problem at all. You can modify an existing profile at any time and include additional devices. Apple will recreate the modified Provisioning Profile instantaneously and you can simply download and use the updated version.
Here's a screenshot of my Development Provisioning Profile with eight registered iPhones:
You are going to use the Development Mobile Provisioning Profile along with Xcode to deploy directly from Xcode to your device.
Next set up an Ad Hoc Distribution Provisioning Profile to allow distribution of your application to friends and others:
- Navigate to Provisioning > Distribution in the iPhone Developer Program Portal.
- Click Add Profile.
- Select Ad Hoc. (I'm not going to cover App Store distribution in this post!)
- The rest of the process equals the one for Development Provisioning Profiles.
- Again, I highly recommend to name your profiles something like "[my company name] Ad Hoc Distribution Profile".
Download the two profiles you've just created and store them in a save location. If you've followed my advice and provided speaking profile names, the files you're going to download will have speaking file names, as well.
Installing Mobile Provisioning Profiles
Once you've downloaded the profiles the next step is to install them. The installation requires two steps: First, let Xcode know about the profiles. Second: Sync them to the device(s).
In order to install the profiles to your system you've got a couple of options:
- Drag the .mobileprovision files downloaded from the iPhone Developer Program Portal to the Xcode dock icon.
- Or: In Xcode select Window > Organizer. In the Devices pane select a connected device. In the Provisioning section of the Summary page click the [+] button. Navigate to your profile file.
- Or: Drag the .mobileprovision files downloaded from the iPhone Developer Program Portal to the iTunes dock icon.
- Or: Download the iPhone Configuration Utility which is available as a free download for Mac OS X and Windows. (If you're managing multiple devices and don't have Xcode, I highly recommend to use the iPhone Configuration Utility instead of iTunes as it gives you more control.)
Once you've installed the profiles verify that they have been copied (and renamed) to ~/Library/MobileDevice/Provisioning Profiles.
The next time you sync your device (or deploy an application to it via Xcode) the profiles will be installed. Verify that your device shows all of the profiles by going to Settings > General > Profiles.
This installation experience is an area, where I've seen people going literally nuts. Especially if you've played around with profiles a lot your system might be in a state where nothing seems to work anymore.
You might have seen 0xe800003a or 0xe8000001 error codes and frequently have read the annoying "Your mobile device has encountered an unexpected error (0xE8000001) during the install phase: Verifying application" error message.
Here are the good news: While others have stated they resolved these issues by reinstalling the iPhone SDK or even restoring their iPhone to factory state I never ever had to go that far in order to fix things. I've got a pretty complex setup comprising multiple provisioning profiles in parallel and multiple iPhones running more than a single profile. I do use more than a single certificate, too. And while I certainly ran into these errors, too, I've always been able to fix everything by just checking all the nitty gritty details and verifying that I've got everything configured right. I never needed a restore or reinstall. And you won't either!
So before you're deciding to delete stuff and to start over again, I'd like to encourage you to read through the Apple guides and take the stuff provided in this post as additional material and I promise you, you will be operational soon! There should be almost no need to reinstall the SDK or restore the device!
Whatever method you've selected to install the profiles, at the end of the day your profiles will be stored in ~/Library/MobileDevice/Provisioning Profiles. During installation your mobile provisioning files get a unique name. If you want to know which file maps to which of your profiles, you can open the files with a text editor (Right-click and Open With... TextEdit) and search for <key>Name</key> . The string immediately following this key maps to the speaking name you've selected during profile creation.
Here is an important tip: In case you're continuously experiencing wired issues, go and empty the ~/Library/MobileDevice/Provisioning Profile folder. Don't worry! You can download your profiles as often as you want through the Portal. Emptying this folder makes 100% sure that no old, outdated or corrupted provisioning profiles are left. In addition you should manually delete installed profiles from your iPhone by selecting Settings > General > Profiles and Remove for each.
Setting up Xcode
If you've made it up to this point, half of your journey is done. Overall the next part – getting Xcode up to speed – is pretty straight forward. There are again some subtle details you should be aware of, but again, it can be done. You don't have to reinstall the SDK. You don't have to restore your device. Just be patient and follow along. :-)
Provisioning Profiles
The first thing you want to make sure is that Xcode knows about your provisioning profiles. Launch Xcode. Go to Window > Organizer. Select your connected iPhone in the Devices pane. Make sure you see both profiles in the Provisioning area of the Summary page and both are checked:
Note: I've got an additional, grayed out profile here which I use for iTunes App Store distribution. You might not find that in your environment.
The next time Xcode talks to your device it'll make sure that the checked profiles will be installed in case they are not there yet. As a reaction to this post ZDNet's Ed Burnette remarked, that in his situation he had to manually delete the profiles and add them again. So in case you already had profiles installed, you might want to remove them here and add them again.
Project Settings in Xcode
Let me say this first: If you found this post, you've been there, you've done this before. You might have gone through this a couple of times. Please, stay tuned and do it again. I promise, at the end you'll have a working environment.
Open your Xcode project. In case you've got none at hand, just create a new one to follow along.
There are a couple of things you have to do before you can compile for device deployment. Unfortunately there also is a difference between deploying for Ad Hoc Distribution and deploying simply to your connected development device. I'll guide you through both.
Deploying to your locally connected development device
You got to tell Xcode about the App ID you're going to use. Remember: You've created a wildcard App ID (com.straight2market.*) in the iPhone Developer Program Portal before.
In the Resources group of the Xcode Project Explorer find the Info.plist property list and select it. The Property List editor will show you the contents of the file. Make sure that the Bundle identifier falls into the namespace you've creates via the wildcard App ID.
By default it is:
If for example you've created the App ID com.straight2market.* and are going to create a calculator app, you might want to change it into com.straight2market.Calculator. As long as the Bundle identifier matches your App ID namespace it's fine. Please note that Bundle identifiers have to be unique on the device. Therefore two apps must not share the same Bundle identifier.
Note: It is perfectly legal to just directly type in the Bundle identifier with the Property List editor. Yet there is a more elegant alternative. As you can see in the above screenshot by default Xcode uses a placeholder named ${PRODUCT_NAME:identifier}. You can set the contents for this placeholder by right-clicking the top most node in the project tree and selecting Get Info (or going to Project > Edit Project Settings), selecting the Build page and typing Product Name into the search field. The value you're assigning here will be taken by Xcode to replace the variable in Info.plist.
So, here is what I usually do:
1. Change the Bundle identifier property in Info.plist:
2. Configure the application name in the Build settings for the project:
Important Note:
One of the aspects I've found not widely known but causing much confusion is that while Xcode lets you edit Build settings and others for the non active configuration, you should not do so! This is so super important, that I'd like to go into more detail.
In various Xcode windows you can see and change the active configuration (highlighted in red below).
When you go to Project > Edit Project Settings (or right-click on the root node in the project tree and select Get Info) you can adjust various settings. The editor allows you to modify everything for each configuration. So if for example your active configuration is Debug you could still make changes to the Release configuration.
Make sure, you're making changes to the active configuration. This might be fixed in future Xcode versions but currently if you edit settings for a non active configuration, Xcode sometimes gets things wrong. As an example Xcode might not offer you the correct Mobile Provisioning Profiles. I've also seen projects where instead of the correct names of the profiles their unique identifier was shown, some 30 digit hexadecimal code. This might lead to all sorts of issues later on and actually can cause code signing to fail.
Again: In case you want to make changes to the Project Settings of a non active configuration, first activate the configuration and then adjust its changes.
Another aspect many people don't understand is why some settings appear in bold and others don't. The answer is easy: Xcode allows to define project settings on various levels. You edit the top most level if you go through Project > Edit Project Settings or right-click on the top project node and select Get Info. You can also adjust settings on a lower level. If you right-click the project node in the Targets group, you can override settings for individual targets.
XCode indicates adjustments made on the current level in bold.
If you made sure that you're editing the active configuration, there are a couple of things you've got to do. Unfortunately things are different depending on whether you configure for development, for Ad Hoc distribution and for App Store distribution. Here is a run down on all three options:
Setting up for development
To be clear: With "setting up for development" I mean you're setting up a configuration which will allow you to directly deploy to the device from within Xcode. You're not planning to hand over built apps to your friends. You're not planning to upload to iTunes Connect!
Go to Project > Edit Project Settings (or right-click the top most node in the project explorer and select Get Info).
Verify you're changing the active configuration. (Sorry if I repeat myself here.)
Scroll down to the Code Signing section. Change the value of the Any iPhone OS Device property in the Code Signing Identity section from whatever it says to exactly:
iPhone Developer: <your name>
Replace <your name> with precisely the name you've used to create your certificate. If you're not sure use the Mac OS X Keychain Access utility to look it up. Also make sure that there is a blank between the colon and the name. Here is how I've set up things:
The name in my certificate:
And the settings in Xcode:
Next in the Code Signing Provisioning Profile section change the value for the Any iPhone OS Device property to reflect your developer mobile provisioning profile:
I once again - I promise it's the last time - I want to repeat that you have to make sure you change settings for the active configuration. I've seen many people stating that their profiles did not show up in the list. There are two main root causes for this:
1. You have a typo in the value you've set for the Code Signing Identity. Xcode compares the name you've entered with the names assigned to the profiles. If there is no case-sensitive match, it'll not offer you to set the profile.
2. If you're not editing settings for the active configuration, Xcode sometimes does not offer anything else than the Default Provisioning Profile for Code Signing Identity.
You're done for the development set up!
Setting up for Ad Hoc distribution
Ad Hoc distribution allows you to hand out your application to friends and allow them to beta test it.
Go to Project > Edit Project Settings and select the Configurations page. If you've started with a clean project you most likely find two configurations, Debug and Release. Select Release and hit Duplicate (it's at the bottom of the Project Info window). Name the duplicated configuration Ad Hoc Distribution. Actually the name is not important and used for reference purposes only but it makes life easier if you stick to clearly speaking names.
Switch to the Device / Ad Hoc Distribution configuration, thus making it active:
Open the project settings again. On the Build page make sure you are editing the active configuration. In the Code Signing section for the Code Signing Entitlements property set the value to dist.plist. In the Code Signing Identity section for the Any iPhone OS Device property set the value to exactly:
iPhone Distribution: <your name>
For the Any iPhone OS Device property in the Code Signing Provisioning Profile select your Ad Hoc distribution profile.
Again: If the Ad Hoc profile you've created does not show up here, chances are, you're not editing the active configuration.
As the final step you've got to add the dist.plist Entitlement file: Right-click on the top most project node and select Add > New File... . Under iPhone OS select the Code Signing category and choose Entitlements.
Name the new file dist.plist. Again the name is not important as long as it matches the settings you've made before for the Code Signing Entitlements property.
Hit Finish. Double-click the newly created file to open it with the Property List Editor. Deselect (!) the get-task-allow property checkbox.
You're done for the Ad Hoc Provisioning Profile!
If you found this article helpful and it might even saved you valuable time, feel free to donate. :-)
I'm going to cover App Store Distribution soon. Stay tuned!