The Beast That Is iPhone Ad Hoc Deployment

The Beginning

I just recently completed a demo iPhone application aimed at demonstrating how a user could order food from a restaurant. I developed a multi-tiered application, starting with a SQL Server database back end that stores orders, order items, and menu items. On top of that, I wrote a WCF service with ASP.NET 3.5 extensions that exposed a RESTful interface for my iPhone client application to use.

UI Goodness

While developing the back end to support my cool iPhone front end, I had my bad-to-the-bone graphic designer and partner, Jeff Broderick, create a UI design for the front end.

In a future post, I will go over the exact steps I used to implement this design using XCode and Interface Builder, but sufficed to say, the application turned out great, did what it was supposed to do, and represented a great example of good architecture, combining the front end to back end web services on a different platform.

Now, the pain!

Until now, I had run the application using the development provisioning profile I had downloaded from Apple when I first joined the iPhone Developer Program. This allows me to distribute applications directly from my XCode development environment to my iPhone, directly connected via USB. However, if I want potential clients and customers to be able to test and give feedback about my wonderful application, I must use Ad Hoc deployment, since I am not ready to distribute my application using Apple’s AppStore. Let the pain begin.

First Steps

The first step to utilizing Ad Hoc deployment is to add the device ID’s for all devices you wish to distribute your application to. Apple allows each developer to distribute to up to 100 devices for Ad Hoc deployment, and each device must be listed in the developer’s iPhone Portal as connected to an Ad Hoc distribution profile. This post provides excellent instructions on how to tell users to find their device ID to give you via iTunes.

Next…

Next, the developer should create a distribution target in XCode, associating that target with an Ad Hoc development profile after adding the downloaded Ad Hoc provisioning file from the iPhone Portal. The following steps should have resulted in successful distribution:

1. Compile the application using the Ad Hoc development profile in XCode.
2. Zip up the “.app” directory created in the output directories for the project.
3. Make a copy of the Ad Hoc provisioning file, and send it along with the zipped application files to the intended user.

The user can then simply drag and drop the provisioning file to their iTunes “Applications” section to install a profile that will run any application built and associated with it (an entire suite if designed that way). Then, the zipped file can be dragged and dropped onto the same place and consumed by iTunes to be synced to the phone the next time the user initiates a sync. The application installs, and life is good!

The First Problem–Windows/Vista Users

The first likely failure to encounter is with Windows and Vista users that use the Windows version of iTunes to sync to their iPhones. You see, the set of binary directories that the developer so nicely zips up on the Mac breaks some rules for file and directory names on Windows. On Windows, it is illegal to have a file named the same as a directory. On Mac, this is fine, and there are at least two instances where this is done in the zipped package. As a result, Windows users must manually expand their application zipped files to a new directory, ensuring to leave the zero-length files out of the expansion (and include the directories of the same name). The user an then drag and drop the entire directory to iTunes and consume the application.

The Big Problem

Even after solving this issue, the user may experience errors related to validating the application. This was a maddening problem to solve, which took hours and hours of doing it again and again to no avail. This problem turns out to be connected to the versions of certificates and provisioning profiles used to build the application vs. the current iPhone version.

While nothing I have read or received from Apple confirms what I am about to say, after seeing the problem solved, a few things are starting to make sense:

• Between each iPhone OS release, Apple make tweaks to the provisioning and verification process for installing applications in response to jailbreaking efforts, bugs, and new information gathered though experience. This can result in small changes to files and verification code that could affect how applications are consumed.
• Something big happened sometime between iPhone OS releases 2.1 and 2.2 that dramatically affected Ad Hoc distribution. The threads on the Internet related to this topic show a LOT of people having big problems and even after solving them, they don’t really understand what happened and how. Most end up reinstalling the whole world on both their development environments and resetting devices to get all this to work.
• The combination of certificates, provisioning files, and iPhone OS versions MUST explicitly match–from the email address the developer uses to create certificates (must match the iPhone Development Program email address) to the generation of the profiles themselves to the set of existing profiles that might already be downloaded to target devices.

After wrestling with this for a couple of days at the risk of having my potential clients think I did not know what the heck I was doing, I called Apple to get a solution. I didn’t exactly get someone to talk to me, but the receptionist who answered apparently had fielded many calls about this and sent me an email within 5 minutes containing explicit instructions. Here is the unedited text of what was sent:

Please include the line below in follow-up emails for this request.

Follow-up: 65776312

Re: iPhone Developer Program

Hello Travis,

Thank you for contacting the Apple Developer Connection regarding provisioning your device for development.

We ask that you please try revoking and recreating your Development Certificate and Development Provisioning Profile. Also delete any existing Distribution Provisioning Profiles from your Mac in ~/Library/MobileDevice/Provisions and ~/Library/MobileDevice/Provisioning Profiles and close Xcode and download and install the new Distribution Certificate, WWDR Intermediate Certificate and Development Provisioning Profile.

You will want to ensure that you are running Mac OS X v10.5.5, that you have upgraded your devices to iPhone OS 2.2 via iTunes 8 and that you are using the latest iPhone SDK (build 9M2621).

When creating a certificate, please ensure that the email address entered matches the information that was submitted when you registered as an iPhone Developer. In the Common Name field enter your First and Last name. Please ensure that the name entered matches the information that was submitted when you registered as an iPhone Developer.

When creating your Development Provisioning Profile, please ensure that the UDIDs for all the devices you will be developing on are registered on the Program Portal and selected on the Provisioning Profile. Once you have downloaded the Provisioning Profile drag the file into Organizer in Xcode to install it onto your iPhone or iPod touch. You can confirm that the certificate is installed by navigating to Settings, General and Profiles on your development device.

Ensure in Keychain access that both the Private Key that corresponds to your iPhone Development Certificate AND the public iPhone Development Certificate are located in the Keys category of the Keychain application. The Private Key is housed on the system that originally created the certificate request for the iPhone Development Certificate.

Re-open your project in Xcode, highlight the top-level of your project and select the ‘Info’ icon from the top menu bar and ensure that you have the “Debug” configuration selected under the Build menu. Select the appropriate Certificate and Provisioning Profile from the drop down list in the ’Any iPhone OS Device’ field setting.

In the Properties Pane of the Target Info window, enter the Bundle Identifier portion of your App ID. Detailed instructions can be found in the iPhone Developer Program Portal Guide.

Back in the Project Window, select ‘Device – iPhone OS 2.x’ from the ‘Device | Debug’ drop down menu in the upper-left hand corner and ensure that Active Configuration is set for Debug. Then click ‘Build and Go’ to install the application on your Apple device.

I hope that this information is helpful to you. If you require additional technical assistance with this issue, please refer to the Developer Forums at or submit a NEW email to our Developer Technical Support team .

Best regards,

Hana Rausova
Apple Developer Connection
Worldwide Developer Relations

Problem solved.

Some parting notes…

This note applied to development provisioning, but these steps solved the problem for Ad Hoc as well. One should assume that this should be done each and every time you upgrade the combination of iPhone operating system and update the SDK. Additionally, a developer should instruct the user you wish to deploy TO to upgrade their iPhone operating system to the version you used to build the application. In addition, any existing profile files distributed previously should be explicitly removed.

Conclusion and next time…

Hope this helps all those out there with ad hoc provisioning woes! In a future post, I will go over the patterns, architecture, and code for the demo application, including the use of libxml2 for XML message parsing on the iPhone and NSURLConnection in the iPhone SDK!