iPhone AdHoc distribution

All the docs at Apple indicate that AdHoc provisioning is as simple as rebuilding your project with new distribution profile. But unfortunately it is not that simple.

I had several problems withAdHoc distributing my Rivals.app. When my tester reported problems installing the app, I searched through internet and came up with several exceptionally good posts that helped me to fix problems (see them at the bottom). To gather info and widen it’s footprint I recite what I did.

Add devices to developer portal

Log in to your developer portal and click Devices section. Add all new devices you are going to distribute to.

Add new Devices
Add new Devices

Note: you can add only up to 100 devices and recycling slots available only after renewal of subscription until you add first new device.

Create AdHoc distribution profile

Now go to Provisioning section and pick Distribution tab where you can create new profile. Click New Profile and fill in the details. Be sure to select Ad Hoc as the distribution method and check each device you want to distribute to.

New Ad Hoc Profile
New Ad Hoc Profile

After you submit, it’ll take a few moments for Apple to create the profile. Wait a bit and then click on Distribution tab again. You should now be able to download the profile. Once downloaded, double click the file, which will open it in XCode and install it to the system.

Set up Xcode

Create .zip file automatically

Before we get to the point, let’s get Xcode to automatically create the distribution .zip file on each build. For this navigate the Xcode Groups & Files tree to Targets and open the current target. Right click it and select Add > New Build Phase > New Run Script Build Phase. Now a new window pops up. Add the following code into that window:

cd $TARGET_BUILD_DIR
rm -f zip -r $PRODUCT_NAME.zip
zip -r $PRODUCT_NAME.zip $PRODUCT_NAME.$WRAPPER_EXTENSION
cd $TARGET_BUILD_DIR
rm -f $PRODUCT_NAME.zip
zip -r $PRODUCT_NAME.zip $PRODUCT_NAME.$WRAPPER_EXTENSION

This script will remove any stale .zip file and recreate it on every build of this target.

Run Script Phase
Run Script Phase

AdHoc Target

Xcode comes with wonderful feature to set up multiple targets within one single project. Each of these targets can have different build phases and scripts. We now take advantage of this feature to set up Xcode to have different configuration for Ad Hoc distribution. First step is to duplicate the main target, so highlight the same target you modified above and duplicate it (rename it to be more informative, e.g MyAppAdHoc etc).

This step creates a copy of Info.plist just in case you want to have e.g. different versioning for this target. As we do not want this, just remove this file and change configuration back to regular Info.plist (done below at Configuration step).

Now open up the Run Script Phase of this target and change the code there to package the app together with logo file that iTuens can use into an .ipa file:

LOGO="MyAppLogo_512.png"
rm -rf $TARGET_BUILD_DIR/Payload
mkdir -p $TARGET_BUILD_DIR/Payload
cp -f $LOGO $TARGET_BUILD_DIR/iTunesArtwork
cd $TARGET_BUILD_DIR
cp -rp $PRODUCT_NAME.$WRAPPER_EXTENSION Payload/
rm -f zip -r $PRODUCT_NAME.ipa
zip -r $PRODUCT_NAME.ipa iTunesArtwork Payload

This scritpt clears up leftovers from previous run and then:

  1. Copies graphics for iTunes use (a 512×512 PNG file, named here MyAppLogo_512.png)
  2. Copies the whole build result into Payload dir
  3. Zips the logo and Payload up to MyApp.ipa file

Dedicated configuration

Now we set up configuration for the new target and do several other things to ease our life. On menubar go to Project > Edit project settings and hit Configuration tab. Now duplicate Release configuration and rename it to AdHoc:

Project configuration

Now in Build tab, select newly created AdHoc as the active configuration and search for “Code Signing Identity” and set it to be your AdHoc provisioning profile certificate:

Code Signing Identity
Code Signing Identity

While you’re at it, change configuration to Release and set the identity to your distribution certificate (if you already have one installed). Don’t forget to change the configuration back for next step.

Next search for Info.plist and change it to the main Info.plist (not the copied one that appeared when you duplicated the target):

Configure Info.plist
Configure Info.plist

Last configuration step is to add Entitlements.plist file. For this select from menu File > New File… and then Code Signing > Entitlements, create a file named Entitlement.plist and add it to both targets. Open this file and uncheck the option there “get-task-allow“:

Entitlement.plist
Entitlements.plist

Build

Now if all went well and I didn’t forget anything to write here, you should have a working setup. Change all options to build AdHoc distribution:

  • Active SDK to Device
  • Active configuration to AdHoc
  • Active Target to MyAppAdHoc

And build.

The resulting MyApp.ipa file resides in directory ‘build/AdHoc-iphoneos‘ and you can send it along with your .mobileprovision file to your testers.

Steps for end users

When all is done, e-mail or otherwise distribute the .mobileprovision profile file and the .ipa file to your end users and instruct them to do the following:

  1. Drag and Drop the .mobileprovision file to iTunes dock icon
  2. sync their iPhone
  3. Verify that the profile appeared on the device Settings > General > Profiles
  4. Drag and Drop the .ipa file to iTunes dock icon
  5. Go to iTunes’s Device manager and to the Applications tab therein
  6. Verify that the app is checked (check it if not)
  7. Sync the device

If all went well, your users should now be happily using your app.

Credits

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s