IPA Support for Ad Hoc and Enterprise Deployment
Contents
This article covers the following topics in detail:
Ad Hoc Distribution Provisioning
The iTunesMetadata.plist File
iTunes Artwork
Creating an IPA
Installing an IPA using iTunes
Overview
In addition to releasing an application for sale through the iTunes App Store, it can be released through Ad Hoc
deployment for the following uses:
Testing - An iOS application can be deployed to up to 100 users (identified by specific iOS device UUIDs)
for Alpha and Beta testing purposes. See our Provisioning an iOS Device for Development documentation
for detailed information on adding test iOS devices to your Apple developer account.
Enterprise Deployment - An iOS application can be deployed internally, within a company, which requires
either a Business or Enterprise tier license of Xamarin.iOS from Xamarin, and an Enterprise license from
Apple.
In either case, an IPA package (a special type of zip file) must be created and digitally signed with an Ad Hoc
Distribution Provisioning Profile. This article covers the steps required to create the required provisioning profile,
build the IPA package and install the package on an iOS device using iTunes on a Mac or Windows PC.
Ad Hoc Distribution Provisioning
Whether you plan to release your Xamarin.iOS application for Enterprise Deployment or testing purposes, you'll
need to build a Ad Hoc Distribution Provisioning Profile specific to it. This profile allows you to digitally sign the
application for release so it can be installed on an iOS device.
Provisioning involves the following steps using Apple's web based iOS Provisioning Portal:
1. Select Provisioning > Distribution.
2. Click the + button and select the type of Distribution Profile that you want to create as Ad Hoc.
3. Select App ID from the dropdown list that you want to create a Distribution Profile for.
4. Select certificate required to sign the application.
5. Select the iOS devices that the Xamarin.iOS application will be allowed to run on.
6. Enter a Name for the new Distribution Profile and generating the profile.
7. Refreshing the list of available profiles in Xcode on the Xamarin Build Host's Mac.
8. Selecting the Distribution Provisioning Profile in Xamarin StudioVisual Studio for the desired Build
Configuration.
For detailed instructions, please see our Creating a Distribution Profile and Selecting a Distribution Profile in a
Xamarin.iOS Project documentation.
The iTunesMetadata.plist File
When an iOS application is created in iTune Connect (either for sale or free release from the iTunes App Store),
the developer can specify information such as the application's genre, sub genre, copyright notice, supported iOS
devices and required device capabilities. For iOS applications that are delivered either to testers or Enterprise
user via ad hoc distribution, this information is missing.
To supply the missing information to an Ad Hoc distribution, an optional iTunesMetadata.plist file can be
created and included in the applications IPA file. To find out more about the content of this file and how to create
it, please see our The iTunesMetadata.plist Contents and Creating an iTunesMetadata.plist File documentation.
iTunes Artwork
If you are going to use the Ad-Hoc method of delivering your application (either for corporate users or for beta
testing on real devices), you also need to include a 512x512 and a 1024x1024 image that will be used to
represent your application in iTunes.
To specify the iTunes Artwork, do the following:
1. Double-click the Info.plist file in the Solution Explorer to open it for editing.
2. Scroll to the iTunes Artwork section of the editor.
3. For any missing image, click on the thumbnail in the editor, select the image file for the desired iTunes
artwork from the Open File dialog box and click the OKOpen button.
4. Repeat this step until all needed images have been specified for your application.
Please see our iTunes Artwork documentation for more details.
Creating an IPA
Creating an IPA is now built into the new publishing workflow as of Xamarin Studio 5.9. To do this, follow the
instructions below to archive your app, sign it, and save your IPA.
Before starting to create an IPA for a cross-platform solution, ensure that you have selected the iOS project as
your startup project:
Build your Archive
1. Select the Release | Device configuration in Xamarin Studio:
2. From the Build menu, select Archive for Publishing
3. Once the archive has been created, the Archives view will be displayed:
Sign and Distribute your App
Each time you build your application for Archive, it will automatically open the Archives View, displaying all
archived projects; grouped by solution. By default this view only shows the current, open solution. To see all
solutions that have archives, click on the Show all archives option.
It is recommended that archives deployed to customers (either Ad-Hoc or Enterprise deployments) are kept, so
that any debug information that is generated can be symbolicated at a later date.
Note that the optional iTunesMetadata.plist file, and iTunes artwork set will automatically be included in
your IPA if they are found in the archive.
To sign your app and prepare it for distribution:
1. Select the Sign and Distribute... button, illustrated below:
2. This will open the publishing wizard. Select the Ad-Hoc or Enterprise distribution channel to create a
package:
3. On the Provisioning Profile screen, select your signing identity and corresponding provisioning profile, or
re-sign with another identity:
4. Verify the details of your package, and click Publish:
5. Finally, save your IPA to your machine:
Note: In certain cases, such as in a CI environment, it may be necessary to build you IPA manually. To do this,
add the following to your .csproj file:
<BuildIpa>true</BuildIpa>
Once this has been set select Ad Hoc from the Xamarin Studio Build Configuration dropdown, and build your
project to create the IPA package. The IPA will be built in the Bin > iOS Device > Ad Hoc folder.
Alternatively, it is possible to call xbuild directly (on a Unified API project) and pass this property on the command
line:
xbuild YourSolution.sln /p:Configuration=Ad-Hoc /p:Platform=iPhone /p:BuildIpa=true
Once the provisioning profile has been created and selected, the optional iTunesMetadata.plist file has
been created and the iTunes Artwork set in Visual Studio, you can build an IPA for Ad Hoc distribution. Next,
you'll need to configure your project for an Ad Hoc build.
Do the following:
1. In the Solution Explorer, right-click the Xamarin.iOS project name and select Properties to open them for
editing:
2. Select iOS IPA Options and select Ad-Hoc from the Configuration dropdown list:
3. If you are including an option iTunesMetadata.plist file, click the ... button, select it from the list and
click the Open button:
4. You can optionally specify a Package Name for the IPA, if not specified it will have the same name as the
Xamarin.iOS project.
5. Save your changes to the Project Properties.
6. Select Ad Hoc from the Xamarin Studio Build Configuration dropdown:
7. Build the project to create the IPA package.
8. The IPA will be build in the Bin > iOS Device > Ad Hoc folder:
Installing an IPA using iTunes
The resulting IPA Package can be delivered to your test users for installing on their iOS devices or shipped for
Enterprise deployment. No matter which method is chosen, the end user will install the package in their iTunes
application on their Mac or Windows PC by double-clicking the IPA file (or dragging it onto the open iTunes
window).
The new iOS application will be shown in the My Apps section, where you can right click on it and get
information about the application:
The user can now sync iTunes with their device to install the new iOS application.
Summary
This article has covered the setup that is required to prepare a Xamarin.iOS application for an Ad Hoc build, has
showed how to create an Ad Hoc IPA Package and has showed how to install the resulting iOS application on the
end user's iOS device for testing or Enterprise Distribution.