There are many ways to waste a decent Sunday. Today I’ve decided to figure how to make and use ad-hoc distributions.

Overview

If your testers are local enough, borrowing their devices overnight and loading your app on their phone yourself is a good option. If your testers aren’t local, you won’t be there to help them, and they won’t be using XCode. Instead, we create a special provisioning profile for your testers’ devices and email this along with a copy of our app built against that profile.

Creating an ad-hoc distro for testers is pretty much the same as creating a developer build. Here are the differences:

  • You need a distribution provisioning profile, NOT a developer provisioning profile.
  • Like devs, testers need to install the provisioning profile onto their device before the device can run. This step is not entirely intuitive (well… release builds don’t require this, right?), however many articles explaining how to make ad-hoc distros skip on this.
  • Like devs, testers need to install a build matching the provisioning profile the app was built with.
  • Unlike devs, testers use iTunes, not XCode. Steps to install provisioning profiles and apps from iTunes aren’t quite the same on OS-X and windows (see ‘installation’ below).

Creating a provisioning profile for testing.

I am assuming you have already completed the steps required to make a build work on your own device(s) and are moderately familiar with the provisioning portal.

  1. First off, you need your beta testers to provide their device IDs. A simple way to collect device IDs is to get your testers to download one of the many free iPhone apps that ease this process, such as UDID+. Simply put, the tester runs the app, then they press ‘send email’ and their device ID appears in the body of the email they’re sending you.
  2. Log into the iphone dev connection website and navigate to the provisioning portal.
  3. Go the ‘Devices‘ tab and add your tester(s) devices.
  4. You need to create a provisioning profile for ad-hoc distribution. This profile will include the devices that the test build can run with.
    (a) select the ‘provisioning’ tab.
    (b) select the ‘Distribution’ sub-tab and select ‘new’ to make a new profile.
    (c) In ‘distribution method’ check ‘Ad hoc’. Choose a name (e.g “MyApp Beta”) and pick your app ID from the list.
    (d) check the box(es) to include your tester(s) device(s) and press submit.
  5. After a couple of minutes, refresh the page (profiles aren’t immediately made available for download). Then download the new provisioning profile and drop it in a folder named ‘beta’. Later you need to email the provisioning profile to your testers so they can add it to iTunes.
  6. Don’t forget to add the new provisioning profile to XCode as well.

Creating a test build

  1. In XCode, switch to a device build. Debug or Release is OK. If you choose debug, it makes it easier to interpret crash logs later.
  2. In the XCode project browser, right click on Targets > YourGameName and select ‘get info’.
  3. Go to the build tab and have a look at the ‘Code signing’ section. If you didn’t forget to add the new provisioning profile to xcode, you can select it in the drop down menu near ‘Code Signing Identity’ and ‘Any iPhone OS Device’. (I just set both fields to the testing profile, but I think the idea is that we can associate profiles on a per device type basis)
  4. Select Build & and Archive in the build menu.
  5. You can find archived apps (and profiles previously added to XCode) in the XCode organizer. To find your build, right click/shift-click the date associated with the archived version you want and select ‘reveal in finder’.

Sending your app to testers – installing an ad-hoc distribution.

Testers need the following:

  1. Copy of the provisioning profile (the *.mobileprovision file we have created)
  2. Your ‘archived app’. I enclose this in quotes because although this is an ‘archive’ on a windows machine it would really look just like a folder with the *.app extension,
  3. A computer (Mac or PC OK)
  4. iTunes should be installed on their computer.

Installation – PC

  1. Open iTunes
  2. Go to ‘add file to library’ and add the *.mobileprovision file. Alternatively, drag and drop this file into the iTunes window (in iTunes 10, seems to work better if we drag into LIBRARY section on the top left).
  3. Drag and drop the *.app folder into iTunes. We can’t use ‘add file to library’ because windows doesn’t recognize *.app folders as ‘files’.
  4. Sync the device (you may need to include the app into the list of apps added to this device first)

IMPORTANT – If the app is added first, the above may not work until iTunes is restarted.

Installation – OSX

  1. Open iTunes
  2. Drag and drop the *.mobileprovision file onto the iTunes icon (or use ‘add file to library’)
  3. Drag and drop the *.app file onto the iTunes icons (or use ‘add file to library’)
  4. Sync the device (you may need to include the app into the list of apps added to this device first)

IMPORTANT – If the app is added first, the above may not work until iTunes is restarted.

References

I’ve been poking around to get this information; then I tested everything step by step until I got it to work.
You could check the original document about ad-hoc distributions for testers (from the Apple site).