Article

Preparing Your App for Distribution

Configure the information property list and add icons before you distribute your app.

Overview

Prepare your Xcode project for distribution before you upload a build to App Store Connect or export a build to distribute it outside of the App Store. Provide all the required information about your app—such as a unique bundle ID, build string, app icon, and launch screen. Choose the settings carefully because most of the information is not editable after you distribute a build through TestFlight or the App Store.

For additional information to enter in App Store Connect, see Required, localizable, and editable properties and App information (which contains more details) in App Store Connect Help.

Set the Bundle ID

When you create your Xcode project from a template, the bundle ID (CFBundleIdentifier), which uniquely identifies your app throughout the system, defaults to the organization ID appended to the app name that you enter in reverse-DNS format—for example, the bundle ID becomes com.example.mycompany.HelloWorld.

If your organization ID is unique across all developers and your app name is unique within your organization, your default bundle ID should also be unique. For example, use your organization's domain name as the organization ID to ensure that the bundle ID is unique.

To distribute your app through TestFlight and the App Store, you create an app record in App Store Connect and enter a bundle ID that matches the one in your project. After you upload your first build to App Store Connect, you can't change the bundle ID, so carefully choose the organization ID when you create the project, or edit the bundle ID afterward. You can edit the name of the app until you submit the app to App Review.

Set the bundle ID for an app target on the General tab of the project editor, in the Identity section.

Screenshot showing the bundle ID field on the General pane. The image shows where you choose a target, click General, and reveal the Identity settings.

Set the Version Number and Build String

The version number (CFBundleShortVersionString) and build string (CFBundleVersion) uniquely identify the build of your app throughout the system. For apps distributed through TestFlight or the App Store, the report service generates crash, energy, and metrics reports for each build of an app version. The version number also appears in the App Store, and for macOS apps the version number and build string appear in the About window.

The version number and build string are expected to be in the format [Major].[Minor].[Patch] where Patch is a maintenance release, as in 10.14.1. Both keys are required by the App Store. Set the version number and build string after you create the project. Increment the build string before you archive a build that you want to distribute. Then increment the version number when you create a new version of your app—for example, create a new app version in App Store Connect.

For macOS apps, you must increment the build string before you distribute a new build.

Set the version number and build string under the bundle ID on the General pane of the project editor.

Set the App Category

Categories help users discover your app on the App Store. You set the primary and secondary categories, under which your app is listed on the App Store, in App Store Connect. For macOS apps, you also set the app's primary category in the project, and it must match the primary category you set in App Store Connect.

Choose a category from the App Category pop-up menu in the Identity section on the General pane of the project editor. For guidance with choosing the most accurate and effective categories, see Choosing a Category.

Screenshot showing the location of the App Category pop-up menu in the Identity section of the General pane.

Assign the Project to a Team

If you haven't already done so, assign the project to a team. For example, if you want to distribute your app using TestFlight or through the App Store, assign all the targets in a project to a team that belongs to the Apple Developer Program. When you upload or export your build, Xcode creates the necessary signing assets in the associated developer account.

Choose a team from the Team pop-up menu on the Signing & Capabilities pane of the project editor.

Screenshot showing Signing controls you use to assign the target to a team. The image shows where you select the project, choose a target, click Signing & Capabilities, and choose a team.

Edit Deployment Info Settings

Edit deployment info settings because some settings—such as the operating system and devices your app supports—are used by the App Store later.

Choose the earliest operating-system version that can run your app, from the Target pop-up menu under the Deployment Info settings on the General pane of the project editor.

Screenshot showing the Deployment Info settings for an iOS app, where you set the deployment target and OS versions, on the General pane of the project editor.

For iOS and watchOS apps, also select the supported devices under the Device column. To create a Mac version of an iPad app, check both the iPad and Mac boxes under Device (see Creating a Mac Version of Your iPad App).

To enable multiple windows for an iPad app, select the "Supports multiple windows" checkbox at the bottom of the Deployment Info settings, and then click the Configure arrow to edit more settings. For details, see Specifying the Scenes Your App Supports, and for sample code, see Supporting Multiple Windows on iPad.

Add an App Icon and App Store Icon

Add an icon to represent your app in various locations on a device and on the App Store.

If you want to distribute the app through the App Store, also add an icon specific to the App Store.

A project created from a template already contains the image set for app icons. In the App Icons and Launch Images section of the General pane, click the arrow next to the AppIcon image set to open the asset catalog. Then drag variations of the app icon to the wells in the detail area of the asset catalog.

Screenshot showing the AppIcon image set for an iOS app where you drag variations of the app icon to wells.

The location of the App Store icon wells in the asset catalog depends on the platform. For iOS apps, drag a resolution for the App Store to the App Store iOS well and for macOS apps, drag it to the App Store - 2x well. For other platforms and earlier Xcode releases, see Add an App Store icon.

For icon metrics, see Human Interface Guidelines.

Provide a Launch Screen (iOS)

A launch screen is a user interface file that appears immediately when your app launches, then is quickly replaced with your app's first screen. The launch screen simply enhances the user experience by providing something for the user to view while your app is launching.

Edit the launch screen file, called LaunchScreen.storyboard, that is in the project when you create it from a template. Otherwise, you can add a launch screen file to an existing project.

For information about designing a launch screen, read Launch Screen in Human Interface Guidelines.

Provide Usage Descriptions to Access Protected Resources

The first time your app attempts to access a protected resource, the system prompts the user for permission. It then generates a dialog that includes the name of your app and a usage description that you provide. For example, the usage description for accessing the user's location data might be "Your location is used to provide turn-by-turn directions to your destination." If the user grants permission, the system remembers and doesn't prompt again for that resource. If the user denies permission, the access to that resource and any further attempts fail.

You must provide usage descriptions in the Information Property List for all protected resources your app accesses, such as the user's location, calendar, reminders, and contacts. Also provide usage descriptions for accessories, such as the camera and microphone.

To learn more, see Requesting Access to Protected Resources.

Configure App Sandbox and Hardened Runtime (macOS)

If you distribute your macOS app through the App Store, you must enable App Sandbox. If you notarize your macOS app to distribute it outside of the App Store, you must enable hardened runtime and, optionally, can also enable App Sandbox.

To learn more about hardened runtime, see Hardened Runtime. For information about notarization, see Notarizing macOS Software Before Distribution.

Set the Copyright Key (macOS)

For macOS apps, set the copyright key (NSHumanReadableCopyright) in the information property list before you upload your app to App Store Connect.

In macOS, if you don't pass a copyright string explicitly to the orderFrontStandardAboutPanel(_:) method that displays the About window, a localized version of the copyright key is displayed in the About window instead. For example, if you set the copyright key to @2002-2019 My Company, it appears at the bottom of the About window. You can localize the information property list for each language that you support.

Add Export Compliance Information

If you distribute your app outside the United States or Canada, your app is subject to U.S. export laws. If your app uses encryption, it is subject to U.S. export compliance requirements. You can bypass the questions that App Store Connect asks you every time you submit your app for review by providing export compliance information in the Information Property List.

To learn more, see Complying with Encryption Export Regulations.

See Also

Distribution

Notarizing macOS Software Before Distribution

Give users even more confidence in your macOS software by submitting it to Apple for notarization.

Distributing Your App for Beta Testing and Releases

Release your app to beta testers and users.