Publishing to the App Store
A guide to distributing Xamarin.iOS applications to the public.
- PDF for offline use
- Related Articles:
- Related SDKs:
Let us know how you feel about this
last updated: 2017-08
This article shows how to configure, build, and publish a Xamarin.iOS application for distribution via the App Store. It includes a step-by-step guide that covers how to prepare your application for distribution, how to use Apple’s tools to submit your application for review, and, finally, how to publish your application to the App Store.
This article covers the following topics in detail:
- Before You Submit an Application
- Configuring your Application in iTunes Connect
- Preparing for App Store Distribution
- Building and Submitting the Distributable
- Customizing the IPA Location
- Submitting Your App to Apple
Explanations are given for Visual Studio on Windows, or you can switch to the Visual Studio for Mac instructions.
Explanations are given for Visual Studio for Mac, or you can switch to the Windows instructions.
In order distribute applications to all iOS devices, Apple requires apps to be published through the App Store, making the App Store the one-stop shopping location for iOS applications. With over 500,000 applications in the store, developers of many types of applications capitalized on the massive success of this single point of distribution. The App Store is a turnkey solution, offering app developers both distribution and payment systems.
The process of submitting an application to the App Store involves:
- Creating an App ID and selecting Entitlements.
- Creating a Distribution Provisioning Profile.
- Using this profile to build your application.
- Submitting your application through iTunes Connect.
This article covers all the steps needed to provision, build, and submit an application for App Store distribution.
Before You Submit an Application
After you submit an app for publication to the App Store, it goes through a review process by Apple to insure that it meets Apple’s guidelines for quality and content. If your application fails to meet these guidelines, Apple will reject it, at which time you will need to address the non-conformance cited by Apple, and then resubmit. Therefore, you stand the best chance of making it through Apple review by familiarizing yourself with these guidelines and trying to adapt your application to them. Apple’s guidelines are available at: App Store Review Guidelines.
A couple of things to watch out for when submitting an app are:
- Make sure the application’s description matches the functionality included in the app.
- Test that the application doesn’t crash under normal usage. This includes usage on every iOS device you support.
Apple also maintains a list of App Store submission tips. You can read these at Distributing on the App Store.
Configuring your Application in iTunes Connect
iTunes Connect is a suite of web based tools for, among other things, managing your iOS applications on the App Store. Your Xamarin.iOS application will need to be properly setup and configured in iTunes Connect before it can be submitted to Apple for review and ultimately, be released for sale or as a free app in the App Store.
Do the following:
- Verify that the proper agreements are in place and up to date in the Agreements, Tax, and Banking section of iTunes Connect to release an iOS application for free or for sale.
- Create a new iTunes Connect Record for the application and specify its Display Name (as seen in the App Store).
- Select a Sale Price or specify that the application will be released for free.
- Provide a clear, succinct Description of the application including its features and benefit to the end user.
- Provide Categories, Sub Categories, and Keywords to help the user find your app in the App Store.
- Provide Contact and Support URLs to your website required by Apple.
- Set your application's Rating, which is used by parental controls on the App Store.
- Configure optional App Store technologies, such as Game Center and In-App Purchase.
For more details, please see our Configuring an App in iTunes Connect documentation.
Preparing for App Store Distribution
In order to publish an application to the App Store, you first need to build it for distribution, which involves many steps. The following sections covers everything required to prepare a Xamarin.iOS application for publication so that it can be built and submit it to the App Store for review and release.
Provisioning for Application Services
Apple provides a selection of special Application Services, also called entitlements, that can be activated for your iOS application when you create a unique ID for it. Whether you are using custom entitlements or not, you'll still need to create a unique ID for your Xamarin.iOS application before it can be published on the App Store.
Creating an App ID and optionally selecting entitlements involves the following steps using Apple's web-based iOS Provisioning Portal:
- In the Certificates, Identifiers & Profiles section select Identifiers > App ID.
- Click the + button and provide a Name and Bundle ID for the new application.
- Scroll to the bottom of the screen and select any App Services that will be required by your Xamarin.iOS application.
- Click the Continue button and following the on-screen instructions to create the new App ID.
In addition to selecting and configuring the required Application Services when defining your App ID, you also need to configure the App ID and entitlements in your Xamarin.iOS project by editing both the
Do the following:
- In the Solution Explorer, double-click the
Info.plistfile to open it for editing.
- In the iOS Application Target section, fill in a name for your application and enter the Bundle Identifier that you created when you defined the App ID.
- Save the changes to the
- In the Solution Explorer, double-click the
Entitlements.plistfile to open it for editing.
- Select and configure the entitlements required for you Xamarin.iOS application so that they match the setup you performed above when you defined the App ID.
- Save the changes to the
For detailed instructions, please see our Provisioning for Application Services documentation.
Setting the Store Icons
Application Store icons should now be delivered by an asset catalog. To add an App Store icon, first locate the AppIcon image set in the Assets.xcassets file of your project.
The required icon in the Asset Catalog is named App Store and should be 1024 x 1024 in size. Apple have stated that the app store icon in the asset catalog can't be transparent nor contain an alpha channel.
For information on setting the store icon refer to the App Store Icon guide.
Setting the Apps Icons and Launch Screens
For an iOS application to be accepted by Apple for inclusion in the App Store, it requires proper icons and launch screens for all of the iOS devices that it will be running on. App icons are added to your projects in an asset catalog, through an AppIcon image set in the Assets.xcassets file. Launch screens are added through a Storyboard.
Creating and Installing a Distribution Profile
iOS uses provisioning profiles to control how a particular application build can be deployed. These are files that contain information about the certificate used to sign an app, the Application ID, and where the app can be installed. For development and ad-hoc distribution, the provisioning profile also includes the list of allowed devices to which you can deploy the app. However, for App Store distribution, only certificate and app ID information are included, since the only mechanism for public distribution is through the App Store.
Provisioning involves the following steps using Apple's web based iOS Provisioning Portal:
- Select Provisioning > Distribution.
- Click the + button and select the type of Distribution Profile that you want to create as App Store.
- Select App ID from the dropdown list that you want to create a Distribution Profile for.
- Select a valid Production (Distribution) certificate to sign the application.
- Enter a Name for the new Distribution Profile and generate the profile.
- On the Mac, open to Xcode and browse to Preferences > [select your Apple ID]> View Details.... Download All available profiles in Xcode on the Mac .
- Return to the IDE and under the iOS Bundle Signing options select the Distribution Provisioning Profile for the correct Build Configuration (This will either be App Store or Release).
For detailed instructions, please see the Creating a Distribution Profile and Selecting a Distribution Profile in a Xamarin.iOS Project.
Setting the Build Configuration for your ApplicationBy default, when you create a new Xamarin.iOS application in Visual Studio, Build Configurations are automatically created for both Ad Hoc and App Store deployment. Before doing the final build of your application that you will be submitting to Apple, there are a few modification that you will need to make to the base configuration.
Do the following:
- Right-click on the Project Name in the Solution Explorer and selection Properties to open them for editing.
Select iOS Build and AppStore from the Configuration dropdown:
If you have a specific iOS version that you are targeting, you can select it from the SDK version dropdown list, else leave this value at the default setting.
- Linking reduces the overall size of your application's distributable by stripping out unused Methods, Properties, Classes, etc. and in most cases should be left to the default value of Link SDK assemblies only. In some situations, such as when using some specific 3rd party libraries, you may be forced to set this value to Don't link to keep required elements from being removed. For more information, refer to the iOS Build Mechanics guide.
- The Optimize PNG image files for iOS checkbox should be checked as this will help to further decrease your application's deliverable size.
- Debugging should not be enabled as it will make the build unnecessarily large.
Click on the Advanced tab:
If your Xamarin.iOS application is targeting iOS 8 and 64 bit iOS devices, you'll need to select one of the device architectures that supports ARM64. For more information on building for 64 bit iOS devices, please see the Enabling 64 Bit Builds of Xamarin.iOS Apps section of the 32/64 bit Platform Considerations documentation.
- You may wish to optionally use the LLVM compiler which creates smaller and faster code, however it will take longer to compile.
- Based on your application's needs, you may also wish to adjust the type of Garbage Collection being used and setup for Internationalization.
- Save your changes to the build configuration.
Building and Submitting the Distributable
With your Xamarin.iOS application properly configured, you are now ready to do the final distribution build that you will be submitting to Apple for review and release.
Build your Archive
Select the Release | Device configuration in Visual Studio for Mac:
From the Build menu, select Archive for Publishing:
Once the archive has been created, the Archives view will be displayed:
Note: While the old App Store and Ad Hoc configurations have now been removed from all of the Visual Studio for Mac template projects, you may find that older projects still include these configurations. If this is the case, you can continue to use the App Store | Device configuration in step 1 of the list above.
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 App Store or Enterprise deployments) be kept, so that any debug information that is generated can be symbolized at a later date.
To sign your app and prepare it for distribution:
Select Sign and Distribute..., illustrated below:
This will open the publishing wizard. Select the App Store distribution channel to create a package, and open Application Loader:
On the Provisioning Profile screen, select your signing identity and corresponding provisioning profile, or re-sign with another identity:
Verify the details of your package, and click Publish to save your
.ipahas been saved, your App is ready to be uploaded to iTunes Connect via the Application Loader:
Build an IPA
This section describes building an IPA, similar to the workflow when using Ad Hoc or Enterprise Distribution. However, it will be signed using the App Store provisioning profile that was created above.
Do the following:
In the Solution Explorer, right-click the Xamarin.iOS project name and select Properties to open them for editing:
Select iOS Bundle Signing and change the provisioning profile to an App Store provisioning profile:
Select iOS IPA Options and select Ad-Hoc from the Configuration dropdown list (If Ad-Hoc does not appear, select Release instead):
You can optionally specify a Package Name for the IPA, if not specified it will have the same name as the Xamarin.iOS project.
- Save your changes to the Project Properties.
Select Ad Hoc from the Visual Studio for Mac Build Configuration dropdown:
- Build the project to create the IPA package.
The IPA will be built in the
Bin> iOS Device >
Customizing the IPA Location
A new MSBuild property
IpaPackageDir has been added to make it easy to customize the
.ipa file output location. If
IpaPackageDir is set to a custom location, the
.ipa file will be placed in that location instead of the default timestamped subdirectory. This can be useful when creating automated builds that rely on a specific directory path to work correctly, such as those used for Continuous Integration (CI) builds.
There are several possible ways to use the new property:
For example, to output the
.ipa file to the old default directory (as in Xamarin.iOS 9.6 and lower), you can set the
IpaPackageDir property to
$(OutputPath) using one of the following approaches. Both approaches are compatible with all Unified API Xamarin.iOS builds, including IDE builds as well as command line builds that use
- The first option is to set the
IpaPackageDirproperty within a
<PropertyGroup>element in an MSBuild file. For example, you could add the following
<PropertyGroup>to the bottom of the iOS app project
.csprojfile (just before the closing
<PropertyGroup> <IpaPackageDir>$(OutputPath)</IpaPackageDir> </PropertyGroup>
- A better approach is to add a
<IpaPackageDir>element to the bottom of the existing
<PropertyGroup>that corresponds to the configuration used to build the
.ipafile. This is better because it will prepare the project for future compatibility with a planned setting on the iOS IPA Options project properties page. If you currently use the
Release|iPhoneconfiguration to build the
.ipafile, the complete updated property group might look similar to the following:
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|iPhone' ) <Optimize>true</Optimize> <OutputPath>bin\iPhone\Release</OutputPath> <ErrorReport>prompt</ErrorReport> <WarningLevel>4</WarningLevel> <ConsolePause>false</ConsolePause> <CodesignKey>iPhone Developer</CodesignKey> <MtouchUseSGen>true</MtouchUseSGen> <MtouchUseRefCounting>true</MtouchUseRefCounting> <MtouchFloat32>true</MtouchFloat32> <CodesignEntitlements>Entitlements.plist</CodesignEntitlements> <MtouchLink>SdkOnly</MtouchLink> <MtouchArch>;ARMv7, ARM64</MtouchArch> <MtouchHttpClientHandler>HttpClientHandler</MtouchHttpClientHandler> <MtouchTlsProvider>Default</MtouchTlsProvider> <PlatformTarget>x86&</PlatformTarget> <BuildIpa>true</BuildIpa> <IpaPackageDir>$(OutputPath</IpaPackageDir> </PropertyGroup>
An alternate technique for
xbuild command line builds is to add a
/p: command line argument to set the
IpaPackageDir property. In this case note that
msbuild does not expand
$() expressions passed in on the command line, so it is not possible to use the
$(OutputPath) syntax. You must instead provide a full path name. Mono's
xbuild command does expand
$() expressions, but it is still preferable to use a full path name because
xbuild will eventually be deprecated in favor of the cross-platform version of
msbuild in future releases. A complete example that uses this approach might look similar to the following on Windows:
msbuild /p:Configuration="Release" /p:Platform="iPhone" /p:ServerAddress="192.168.1.3" /p:ServerUser="macuser" /p:IpaPackageDir="%USERPROFILE%\Builds" /t:Build SingleViewIphone1.sln
Or the following on Mac:
xbuild /p:Configuration="Release" /p:Platform="iPhone" /p:IpaPackageDir="$HOME/Builds" /t:Build SingleViewIphone1.sln
With your distribution build created and archived, you are now ready to submit your application to iTunes Connect.
Automatically copy .app bundles back to Windows
When building iOS apps in Visual Studio and the Mac Build agent, the .app bundle is not copied back to the Windows machine. Xamarin Tools for Visual Studio 7.4 adds a new
CopyAppBundle property that allows CI builds to copy .app bundles back to Windows.
To use this functionality, add the
CopyAppBundle property to the .csproj under the property group you wish to apply this functionality to. For example, the following example shows how to copy the .app bundle back to the Windows computer for a Debug build targeting the iPhoneSimulator:
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|iPhoneSimulator' "> <CopyAppBundle>true</CopyAppBundle> </PropertyGroup>
Submitting Your App to Apple
Note: Apple has recently changed its verification process for iOS applications, and may reject apps with the
iTunesMetadata.plistincluded in the IPA. If you encounter the error
ERROR: ERROR ITMS-90047: "Disallowed paths ( "iTunesMetadata.plist" ) found at: Payload/iPhoneApp1.app"the workaround described here should resolve the issue.
With the distribution build completed, you are ready to submit your iOS application to Apple for review and release on the App Store.
- Start Xcode.
- From the Window menu select Organizer.
Click on the Archives tab and select the archive that was built above:
- Click on the Validate... button.
Select the account to verify against and click the Choose button:
Click the Validate button:
- If there were any issues with the bundle, they will be displayed.
- Correct any issues and rebuild the archive in Visual Studio for Mac.
- Click on the Submit... button.
Select the account to verify against and click the Choose button:
Click the Submit button:
- Xcode will inform you when it is finished uploading the file to iTunes Connect.
Submitting your application to Apple for review is done by using the Application Loader app. These steps must be done on the Mac build host. You can download a copy of the Application Loader from here.
The archive workflow in Visual Studio for Mac will open Application Loader automatically, once you have saved the .ipa:
Select Deliver Your App and click the Choose button:
Select the zip or IPA file you created above and click the OK button.
The Application Loader will validate the file:
Click the Next button and the application will be validated against the App Store:
- Click the Send button to send the application to Apple for review.
- The Application Loader will inform you when the file has been successfully uploaded.
iTunes Connect Status
If you log back into iTunes Connect and select your application from the list of available apps, the status in iTunes Connect should now show that it is Waiting for Review (it may temporarily read Upload Received while it is processed):
This article presented a step-by-step guide to configuring, building, and submitting an application for App Store publication. First, it covered the steps needed to create and install a distribution provisioning profile. Next, it walked through how to use Visual Studio and Visual Studio for Mac to create a distribution build. Finally, it showed you how to use iTunes Connect and the tool to submit an application to the App Store.