Creating an Ad Hoc Distribution

In iPhone in Action we only briefly touch upon distribution methodology (see pages 429-431), mainly because Apple maintains extensive documents on their whole "Program Portal". However in today's post I'm going to supplement our distribution information a bit by highlighting how you create an Ad Hoc Distribution.

Why Ad Hoc?

If you're distributing through the Apple iPhone Store, you might think that you'll never need to release via the ad hoc mehcanism ... and that's probably not correct. There are a number of good reasons to create an ad hoc distribution:

• It lets you easily send a program to other team members, without them having to compile the program.
• It allows you to send pre-release copies of a program to a licensor, for their approval.
• It offers a way to get your App to reviewers prior to release.

The last point is particularly important if you're trying to get on the top-100-program escalator to success--though I personally have grave concerns over the economics of advertising costs versus top 100 returns. But if you decide to go that route you want to get copies of your program out to reviewers so that they can release reviews on the day of your release (or very close thereafter).

The Ad Hoc Process

The ad hoc process is described thoroughly in the "Program Portal User Guide" which can be found in your "iPhone Developer Program Portal" at developer.apple.com. What follows is largely a summary of the material contained in pages 50, 56-58, and 65 of that book.

Here's what all you need to do:

1. Prepare for a Provisioning Profile. This generally means that you need to follow the steps from Appendix C of iPhone in Action. You must have already created a distribution certificate, which you'll use to sign the profile; you must have chosen an AppID for your program; and you must have entered UUIDs for any devices that you want your program to run on. You should already be familiar with these items, and have them in hand, from the work you did to either create a developmental provisional profile or an app store distribution provisional profile. The only notable difference here is that you'll probably need to enter some new UUIDs, since you need to enter the data for every device that you want your program to run on--which means the devices of reviewers, licensors, co-workers, and whoever else you're working with.
2. Create a Distribution Provisioning Profile. Click the "Provisioning" option in the Program Portal, then the "Distribution" tab. Choose "ad hoc" as your distribution method, then enter data on your certificate, app id, and devices, as appropriate.
3. Create a new Ad Hoc Distribution Profile in Your Project. This relatively simple process is described at length on pages 51-56 of the Portal Guide. In essence, you duplicate the "Release" profile, then set it to use your new ad hoc profile as its code signing identity. You've probably already done the other work of this section, such as setting up your project to use your app id.
4. Create an Entitlements File. This is the major new element required to prepare an app for ad hoc distribution, and it's described on pages 56-58 of the Portal Guide, which you should read at length. In essence: you create a new "Code Signing" file of type "entitlements." Then you uncheck the "get-task-allow" property of your new file. Finally you go to the Build tab of your target and enter your new file into the "Code Signing Entitlements" section of the "Code Signing" setting.
5. Build Your Project. Now you can build. You'll of course want to make sure that you've set Xcode to compile for a device of the correct OS version, using your ad hoc distribution profile.

That should produce an ad hoc version of your project that's ready to go ...

Distributing Your Ad Hoc Program

If all of your potential ad hoc users have their iPhones or iPod Touches hooked up to Macs, you can just send the compiled product (program.app) and the provisioning profile. Your users can drag the two files to the iTunes icon on their doc, and the program will automatically copy into iTunes, then download onto their device as soon as they sync.

However, if a user has an iPod Touch hooked up to a Windows machine, the above will probably fail. The .app file will simply refuse to drop on iTunes. At the time of this writing, you need to create a special .ipa file as a replacement for the .app file for Windows users. This turns out to be just a .zip file with a specific structure.

To create an .ipa file, you need to go to the directory containing your ad-hoc-compiled app. You can find that by clicking on the app in Xcode, then right-clicking to choose "Reveal in Finder". Alternatively, it should be easily accessible in a special "ad hoc" subdirectory of your project directory's "build" directory.

In either case, once you're there run the following commands, substituting your app's name for "program":

mkdir Payload
mv program.app Payload
zip -r ~/Desktop/program.ipa Payload

(Thanks to the folks on the iphonesdk list for solving this problem, and in particularly to David Morris, who offered the above script.)

This should create a .ipa file on your desktop, which you can send out. A windows user will then be able to install your program by dragging the provisioning profile and the .ipa file to their iTunes icon.

As it happens, Mac users can use the .ipa file fine too, so if you ever need to create one because some user has a Windows machine, you might as well just send the .ipa file and the provisioning file to everyone, rather than sending the .app file out to any one.

Last step: sit back and wait for the comments to come in.

Comments

[opensoul.org]

I've been trying to figure out the best way to give clients regular updates of our progress. Besides having them install the iPhone SDK, do you think this is the best approach?

[Shannon Appelcline]

I think so. It's really easy to do. You just do a compile with different options, zip up the results, and email them, and then they drag to iTunes and everything works. All you need to do is have them get their UUID out of their iTunes.

[Daniel Hepper]

If you have to collect UDIDs from customers, tell them to install UDID Helper. It reads the UDID and sends it by email. Probably less error prone than typing it from iTunes.

[sg]

I tried the steps mentioned for packaging to windows users. It does not work for me.

I followed the 3 lines as mentioned above.

mkdir Payload
mv program.app Payload
zip -r ~/Desktop/program.ipa Payload

Any clue why it wouldn't work? I can see the App on iTunes. But it won't show up on my device/iPod. With mac, i have no issue. It works & syncs up good.

I would appreciate any help.