Jump to content

How to Prepare an iPhone App for Ad Hoc Distribution

  adfm's Photo
Posted May 04 2010 02:04 PM

Got an iPhone or iPad app that you'd like to test? Perhaps you'd like to distribute a one-off app to a few friends? This excerpt from Alasdair Allan's Learning iPhone Programming will explain how to set up your app for ad hoc distribution.

Ad hoc builds of your application are used to distribute your application outside your own development environment, and are intended to allow you to distribute your application to beta testers. In the same way you registered your iPhone or iPod touch for development, you must register all of the devices onto which you intend to distribute your application using an ad hoc build. You can register up to 100 devices per year in the iPhone Program Portal. This is a firm limit; deleting already registered devices will not allow you to add further devices.


Normally when you distribute applications via the ad hoc method, no application artwork is displayed when the user looks at your application inside the iTunes interface. However, if you place a copy of the 512×512-pixel PNG of your icon in your application bundle and name it iTunesArtwork without any file extension, this will be used by iTunes.

To deploy your application to your users via the ad hoc method, you need to create a distribution certificate, register any devices you plan to use, and create an ad hoc provisioning profile in the iPhone Developer Program Portal.

Obtaining a distribution certificate

Just as in Chapter 2, Becoming a Developer when we dealt with development, the first thing you need is a distribution certificate, and to obtain that you need to generate a certificate-signing request (CSR) using the Keychain Access application:

  1. As you did for the CSR you generated for the development certificate (see the section called “Creating a Development Certificate” in Chapter 2, Becoming a Developer), launch the Keychain Access application.

  2. Select Keychain AccessPreferences from the menu. Go to the Certificates preference pane to confirm that the Online Certificate Status Protocol (OCSP) and Certificate Revocation List (CRL) options are turned off.

  3. Select Keychain AccessCertificate AssistantRequest a Certificate from a Certificate Authority from the Keychain Access menu, and enter the email address you selected as your Apple ID during the sign-up process and your name. Click the “Saved to disk” radio button, check the “Let me specify key pair information” checkbox, and click Continue. You’ll be prompted for a filename for your certificate request.

  4. Accept the defaults (a key size of 2,048 bits using the RSA algorithm) and click Continue.

The application will proceed to generate a CSR file and save it to disk.

In the iPhone Developer Program Portal (sign in to http://developer.apple.com/iphone and look for the program portal link), click on the Certificates link and in the Distribution tab click Request Certificate (if you already have a certificate, this option will be unavailable as you need only one). Follow the instructions that appear, and upload your CSR to the portal when asked.

If you joined the development program as an individual, you need to approve the signing request (in the Distribution tab of the Certificates section of the portal) before proceeding to download the new certificate. If you are part of a team, the nominated development team administrator needs to do this. After the request is approved, you may need to click on the Distribution tab to refresh the page. When you see a Download button, click it to save the certificate to disk.

Once the certificate file has downloaded, double-click it to install it into your Mac OS X login keychain, as shown in Figure 9.8.

Figure 9.8. The Keychain Access application showing the newly installed distribution certificate needed by Xcode for ad hoc or App Store distribution

Attached Image

Registering devices

Before you create the provisioning profile, you’ll need to register the devices you want the profile to support. To do this you’ll need the unique device identifier (UDID) of all of these devices. Once you have the device identifiers, you need to add your users’ devices in the same way you added your own development device in the section called “Getting the UDID of Your Development Device” in Chapter 2, Becoming a Developer.

In the Program Portal, click Devices, select the Manage tab, and click Add Devices. Enter a device name in the appropriate box and the UDID in the box labeled Device ID, and click the Submit button. (You can click the + button to add more rows so that you can add several devices at once.) You have now registered the device; you need to do this for all of the devices to which you intend to distribute ad hoc builds.

Creating a provisioning profile

Now you’re ready to create a mobile provisioning profile. Go to the Provisioning section of the iPhone Developer Program Portal, select the Distribution tab, and click New Profile.

Enter a profile name; you may be creating a number of ad hoc profiles, so naming your first distribution profile “Ad-hoc Distribution Profile” probably isn’t a great idea. You may want to name it after the application you’re distributing, so perhaps “City Guide Beta Test Profile” would be a good choice for distributing a beta of the City Guide application to testers.

Next, select the App ID you used for the application you’re going to distribute, and then select all of the devices for which this profile will be valid, as shown in Figure 9.9.

Figure 9.9. Creating an ad hoc provisioning profile

Attached Image

Click Submit to generate the new mobile provisioning profile that you’ll use to distribute the application to your beta testers. The status will appear as pending; click the Distribution tab to reload it until it is no longer pending. When the profile is ready, click the Download button and download the provisioning profile to your Mac. Now drag the provisioning file onto the Xcode icon in the dock to make it available to the development environment.

Building your application for ad hoc distribution

Let’s make an ad hoc build of the City Guide application. Double-click the project icon at the top of the Group & Files pane and select the Configurations tab. Select the Release configuration in the main pane, and click the Duplicate button located at the bottom left of the configuration list. Name the duplicate configuration “Ad-hoc”, as shown in Figure 9.10.

Figure 9.10. Creating an ad hoc configuration in the Xcode Project Info window

Attached Image

Return to the main Xcode window and use the Overview drop down to set the active configuration to be the new ad hoc configuration, and the active SDK to be the iPhone device rather than iPhone Simulator.

Now, in the Groups & Files pane of the Xcode interface, right-click on the Resources group and select AddNew File. Choose Code Signing and select an Entitlement (see Figure 9.11). Click Next, and name the file “dist.plist” when prompted. Click Finish.

Figure 9.11. Adding the ad hoc distribution plist file to your project

Attached Image

In the Groups & Files pane, click on the dist.plist file and (very important) uncheck the get-task-allow Boolean property in the editor window, as shown in Figure 9.12. This step is necessary to turn off the ability for other processes (such as the debugger) to attach to your application, as this is disallowed by distribution profiles.

Figure 9.12. Unchecking the get-task-allow flag in the dist.plist file

Attached Image

Now, double-click on the project icon at the top of the Groups & Files pane to reopen the Project Info window. Click the Build tab and scroll down to the Code Signing section. Double-click on the Code Signing Entitlements value field, type dist.plist in the entitlements list, and click OK. Now click on the menu to the right of the Code Signing IdentityAny iPhone OS Device line and select the iPhone Distribution profile. Xcode should match this against the City Guide Beta Test profile we installed earlier, as shown in Figure 9.13.

Figure 9.13. Choosing the iPhone Distribution profile

Attached Image

Close the Project Info window. Before building your application, open the CityGuide-Info.plist file and make sure the Bundle Identifier in your Info.plist file matches the one used to create the ad hoc mobile provisioning profile. See the section called “Putting the Application on Your iPhone” in Chapter 3, Your First iPhone App if you’re unsure about this part. If you’ve been able to deploy your application onto your iPhone or iPod touch and you generated a wildcard app ID earlier, you shouldn’t have to change anything.

Now select BuildBuild from the Xcode menu to build, but not to deploy, your application. You may be prompted to allow Xcode to access your private key by the Keychain application; you must permit the access to build the application.

Distributing an ad hoc build

Once you’ve made your build, go to the Products group in the Groups & Files pane in the Xcode interface and double-click to open the group if it is not already open. Inside you should find a single file called CityGuide.app. Right-click on this file and select Reveal in Finder to open a Finder window in the directory containing the application bundle.

Copy the application bundle file onto your desktop and create a ZIP file containing both it and the ad hoc mobile provisioning profile you created earlier. This ZIP file is your ad hoc build and can be distributed directly to your users.

Users receiving an ad hoc build should follow these steps:

  1. Plug their iPhone or iPod touch into their Mac.

  2. Ensure that iTunes is running and can see their device.

  3. Unzip the distribution archive file.

  4. Drag the provisioning profile onto the iTunes icon in the dock.

  5. Drag the application bundle file onto the iTunes icon in the dock.

If the user checks the Applications section of his iTunes library, he should now be able to see the new ("Ad-hoc”) application, and he can install it onto his iPhone or iPod touch in the normal way by syncing his device with iTunes.

Learning iPhone Programming

Learn more about this topic from Learning iPhone Programming.

Get the hands-on experience you need to program for the iPhone and iPod Touch. With this easy-to-follow guide, you'll build several sample applications by learning how to use Xcode tools, the Objective-C programming language, and the core frameworks. Before you know it, you'll not only have the skills to develop your own apps, you'll know how to sail through the process of submitting apps to the iTunes App Store.

See what you'll learn

0 Replies