MonoTouch Ad Hoc Distribution Tutorial

There are 4 use-cases for deploying an app to an iOS device:

  1. Development
  2. Ad Hoc
  3. Enterprise
  4. Retail / App Store

This tutorial is going to concentrate on the 2nd use-case: “Ad Hoc Distribution.”

Although you might think of “ad hoc” as meaning something done casually or off the cuff, ad hoc distribution actually involves several steps and is constrained to 100 devices per year. So the truth is, “Ad Hoc” is really about beta testing.

So let’s walk through the ducks you’ll need to line up to do an ad hoc distribution:

  1. A Distribution Certificate
  2. An App ID.
  3. The Device ID of every iOS device to which you wish to deploy

With those three things, you can create the required:

  • Provisioning Profile

With the Provisioning Profile and the App ID, you can compile your awesome app (did I mention that you have to write an awesome app?) so that it is capable of being run on those devices whose Device IDs you collected earlier.

Once you have your compiled app, your beta testers can install it just by dragging-and-dropping it into iTunes.

So, let’s walk through it:

Distribution Certificate

Just like an SSL certificate, an Apple certificate associates their credibility as a signing authority with your company’s identity. Just as an SSL certificate assures “The IP address of this server is known to Verisign (or whoever) to belong to the legal entity Faster Programmers LLC” a distribution certificate assures “This binary is known to Apple to have originated from the legal entity Faster Programmers LLC.”

If you’ve begun developing for the iPhone, you’ve already created a development certificate. While I’m not sure if it’s strictly necessary, you’re supposed to use a  distribution certificate for every deployment use-case other than “Development.”

To create your distro certificate, follow the instructions at https://developer.apple.com/iphone/manage/certificates/team/howto.action to generate a Certificate Signing Request.

Go to the iPhone Provisioning Portal (https://developer.apple.com/iphone/manage/overview/index.action) and click on the “Certificates” item along the left. (Do not use the “Development Provisioning Assistant” that is available on the front page. You’re not interested in a Development Certificate.) Click on the “Distribution” tab and upload your Certificate Signing Request. Click “Approve,” go get a cup of coffee while Apple signs the request, and download the .cer file.

screen-shot-2010-07-08-at-114707-am

On the Mac, double-click the .cer file and add it to your keychain. (I’m not sure what to do if you’re building in Windows.)

You’re all set.

App ID

Go to the Provisioning Portal, click “App IDs” and the “New App ID” button.

Fill out the app ID as directed.

You’re all set.

Device(s) ID

On your machine, the easiest way to get the Device ID of an iOS device is to plug it in, open XCode and open the “Organizer” window.

screen-shot-2010-07-08-at-121554-pm

For others, the easiest thing is for them to install “Ad Hoc Helper” from the App Store (http://itunes.apple.com/us/app/ad-hoc-helper/id285691333?mt=8). When run, it creates an email that they can send to you with the Device ID of their machine.

The slightly-more-error-prone (but perhaps less intimidating) way is to have your users connect their devices, open iTunes, go to the “Summary” page for their device, and click on the “Serial Number” text field (there’s no button visible) to switch it from “Serial Number” to “Identifier (UDID)”. Then, they must press Command+C to copy the value to the clipboard (they do not highlight it before copying). They can email or IM you the value (please don’t have them read it to you over the phone. It won’t come out well for anyone.)

screen-shot-2010-07-08-at-121603-pm

Once you have the Device IDs for all the devices to which you want to deploy, go to the Provisioning Portal, click on “Devices” and “Add Device.” (If you more than a couple handfuls of devices, you can bulk upload a file of device names and  IDs. See the Portal for instructions.)

You’re all set.

Provisioning Profile

Now that you have all your ducks in a row, it’s time to create the “Provisioning Profile” that ties together:

  • Your company identity (embodied in the Deployment Certificate)
  • Your application identity (embodied in the App ID), and
  • Your beta tester’s devices (embodied in the Device IDs)

Once again to the Provisioning Portal and, surprise, click on the “Provisioning” item in the left-hand menu.

Click on the “Distribution” tab. There is no “Ad Hoc” tab.

Click “New Profile.”

screen-shot-2010-07-08-at-123257-pm

Your Deployment Certificate will be pre-filled.

Enter a name for the Profile (perhaps “Beta1AdHoc”)

Enter your App ID

Choose “Ad Hoc” distribution and then select the devices to which you wish to deploy.

Click “Submit” and go get a cup of coffee.

When you return, download the generated file (Beta1AdHoc.mobileprovision).

Open XCode and it’s Organizer Window.

Drag the Beta1AdHoc.mobileprovision file onto the Organizer Window’s “Provisioning Files” section.

You’re all set.

Building in MonoDevelop

Open the solution for the awesome app that you’ve developed in MonoDevelop.

Open “Project Options” and the “iPhone Bundle Signing” page.

Set the “Configuration” and “Platform” values appropriately.

Set “Identity” to your Distribution Certificate (if you leave it on “Automatic” it may pick up your Developer Certificate)

Set “Provisioning Profile” to your recently installed Provisioning Profile.

Click “OK”

screen-shot-2010-07-08-at-124738-pm

Open the “iPhone Application” page of “Project Options”

Set “Bundle Identifier” to your App ID

screen-shot-2010-07-08-at-124751-pm

Click “OK”

Build that bad boy.

Deploying

MonoDevelop / MonoTouch will have generated several files during compilation. You only need to distribute the “App Bundle” (the one that’s called MyAwesomeApp.app or what-have-you).

One thing that MT’s done for you is generate the correct embedded.mobileprovision document inside the App Bundle (right-click on the App Bundle and select “Show Package Contents” if you want to double-check). So if you see discussion about that in Apple docs, you ought not to have to worry about it.

At this point, you can compress the App bundle and send it to your beta testers. They can drag it to the Library section of iTunes (Not directly onto the connected device shown in iTunes!) and the next time they sync, they’re all set.

And that’s all there is to it! Can you believe that people say it’s confusing? What could be easier?

Many thanks to Wayne Douglas for his assistance with this post…

Update from Tiago Reis:

Some tips to help the distribution:

* Compress the app bundle before sending it, otherwise most of the times the person that receives it will see an error message stating that the application couldn’t be installed because the “resource was modified”.

* Use finder do compress (right click -> compress), using the command line will result in “resource was modified”.

* Mac OSX – Unzip using finder / Windows – Unzip using the Windows default tool. (other tools often change the bundle and result in “resource was modified”

* If the the person you are sending the application is using windows state to them that they can’t open (double click) the app bundle, otherwise windows will create the “.thumbs” file and this will result in “resource was modified”.

* Some email servers/clients modify the bundle (virus check perhaps??), I’ve been using dropbox public folder and it’s working alright. This with a compress archive otherwise dropbox will also change something in the bundle.

* If sending a new version of the app, ask the person receiving it to remove the old one from the library before installing the new one. Not doing this leads to many times to resource modified.

* Add an icon for ad-hoc distrubution : http://johnnytrops.com/blog/wp/?p=183 (sorry for the external reference :-) ). Do this only it’s really really a requirement, because most of the times it will make the installation fail.

div>