Installing an iPhone Application Using Ad-Hoc Distribution

by Damon Allison

Ad-Hoc Distribution is a distribution mechanism iPhone developers use to send apps to their customers without going through iTunes. This post explains how ad-hoc distribution works and how to install an iPhone application using ad-hoc distribution.

Before you start : Get your Device ID!

Each iPhone developer has up to 100 devices to which they can install applications using ad-hoc distribution. So before a developer can send you an application, you must send them your device ID. Instructions for finding your device ID can be found here.

Step 1: Install the mobile provision file

A mobile provision file is a file that says which devices can run an application. In order for you to run an application, the developer needs to send you this file along with the application binary.

To install the file, open the “Applications” window in the iTunes library and drag the file into the large gray window where the applications appear. (You could also drag the file into the LIBRARY node in the tree view on the left of the iTunes window). In the following screenshot, the Applications window is opened. When you drag in the the file, the window will have an outer blue border as shown here:

Unfortunately here is no feedback or message that tells you the file was installed successfully. To verify the file was installed, drag it into iTunes again and you’ll be prompted with a message box that looks like the following. You can either replace or cancel, it doesn’t matter. If you see this message, the mobile provision file was installed correctly.

Step 2: Install the Application.

Along with the .mobileprovision file, the developer will send you the application, typically in a .zip file. Extract the zip. On the mac, you will have a .app bundle. On windows, you will have a .app folder. The name of the bundle/folder will typically be the same name as the application. Drag that bundle or folder into the iTunes Applications window. You should now see the application in iTunes.

The following is an example of dragging the application’s .app folder into the Applications iTunes window in XP.

NOTE: Using the default “Extract” operation in Windows Vista does not seem to work correctly. With Vista, the application will appear to unzip correctly, install into iTunes, but show a warning stating “this application could not be verified” when trying to sync. The only workaround I’ve seen work is to extract the zip on a mac or XP, copy the .app folder to the Vista machine, then copy into iTunes. Sorry, we’re working on finding a better solution (other than just buying a mac :-). See “troubleshooting” below for more information.

Step 3: Ensure the application is set to sync

Click on your device within iTunes. Click on the “Applications” tab on the top. Ensure Sync applications is checked and either All applications or Selected applications and the application you just installed are checked.

Step 4: Sync your phone

Hit sync. If all goes well, the application was installed on your device!

Troubleshooting

Oh boy, where to start.
Unfortunately there are many links in the iPhone application distribution process chain. And with every chain link, there is an opportunity for issues to creep in. Every iPhone developer I know has been tripped up by the distribution process and many could tell you a story regarding lost hours or days for one simple checkbox that was not checked, throwing off the entire process.

I’ll attempt to highlight a few of the common user facing error messages that we have ran into from time to time. Trying to highlight all of the developer errors/problems that we have ran into with the distribution process would fill a long, boring, and frustrating book by itself. If you are a developer still reading this, hoping to find an answer to your ad-hoc distribution issues, you have my sympathy. We’ve been in your shoes. Email us and we’ll help.

1. Vista. As noted above, Vista is problematic when dealing with ad-hoc builds. It appears, however we have not confirmed exactly why, that the default zip extraction does not unzip correctly. We believe it is related to a file naming conflict or a symlink in the zip that Vista (or win32?) cannot handle properly. While we are speculating at the root of the problem, we know with certainty that users experience The application “your app here” could not be verified errors when attempting to sync their devices. The workaround is to unzip this folder on XP or a Mac, transfer it to the vista machine via usb key or network file system, and drop the application into iTunes.

2. The Mobile Provision File is Invalid We’ve seen this error occur when dropping the .mobileprovision file into iTunes. The problem is the .mobileprovision file is corrupt. The corruption typically happens when sending the .mobileprovision file through email. Developers should never edit the .mobileprovision file, so there is very little chance the developer could “invalidate” the file just by accident. If you run into this error, have the developer .zip and send the .mobileprovision file.

Posted in: Mobile Applications,Technology