IPA Support

This article covers how to create an IPA file that can be used to deploy an application using Ad Hoc distribution, either for testing, or for In-House distribution of internal applications.

Contents

This article covers the following topics in detail:

Overview

In addition to releasing an application for sale through the iTunes App Store, it can be deployed for the following uses:

  • Ad Hoc 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, and the Ad-Hoc guide, for more information on how to distribute in this way.
  • 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 requires membership of Apple's Developer Enterprise program.

In either case, an IPA package (a special type of zip file) must be created and digitally signed with the correct Distribution Provisioning Profile. This article covers the steps required to build the IPA package and install the package on an iOS device using iTunes on a Mac or Windows PC.

The iTunesMetadata.plist File

When an iOS application is created in iTunes 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.

iOS applications that are delivered either via Ad Hoc or In-House distribution, need to have some way to support this information so that it can be visible on iTunes and the user's device. By default, a small iTunesMetadata.plist file is created every time you build your project and is stored in the project directory.

A custom iTunesMetadata.plist can also be created to supply the additional information to a distribution. 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

When delivering your app through non-App Store means, 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

Using the IDE

Creating an IPA is now built into the new publishing workflow. 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

To build an IPA, we first need to create an archive of a release build of our application. This Archive contains our app and identifying information about it.

  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 In-House deployments) be kept, so that any debug information that is generated can be symbolized at a later date.

Note that for non-App Store builds the 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(In-House) 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:

Building via the Command Line (On Mac)

In certain cases, such as in a CI environment, it may be necessary to build you IPA via the command line. Follow the steps below to achieve this:

  1. Ensure "Project Options > iOS IPA Options > Include iTunesArtwork images" is checked and "Build ad-hoc/enterprise package (IPA)" is checked:

    If you prefer, you can instead edit the .csproj file in a text editor and manually add the two corresponding properties to the PropertyGroup for the configuration that will be used to build the app:
    <BuildIpa>true</BuildIpa>
            <IpaIncludeArtwork>false</IpaIncludeArtwork>
  2. If you are including an option iTunesMetadata.plist file, click the ... button, select it from the list and click the OK button:
  3. Call xbuild (or mdtool for Classic API) directly 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 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 covered the setup required to prepare a Xamarin.iOS application for a non-App Store build. It showed how to create an IPA Package and has how to install the resulting iOS application on the end user's iOS device for testing or In-House Distribution.