Configuring Your Xcode Project for Distribution

You can edit your project settings anytime, but some settings are necessary during development. Others are recommended when you distribute your app for beta testing and required when you submit your app to the App Store or Mac App Store.

During development, your app must be provisioned and code signed to use certain app services and run on an iOS device (iPad, iPhone, or iPod touch). If you assign a bundle ID and team to your project, Xcode can create the necessary certificates, identifiers, and profiles for you in Member Center. You can enter this information now using the project editor or as needed when you add app services and launch your app.

Before you distribute your app for testing or to the store, provide all the required information about your app. For example, set app icons to pass iTunes Connect validation tests.

Before you upload your app to the store, verify your build settings and set the copyright key for Mac apps.

Setting Properties When Creating Your Xcode Project

An assistant guides you through the process of creating an Xcode project. First, you select a template for your project. Starting with the right template helps speed the development process. The assistant also prompts you to enter information about your app that’s used to determine your app’s capabilities and distribute it to customers. If you don’t have this information when you create the project, you can set these properties later. If you are a member of the Apple Developer Program, some of the data in the Xcode project is similar to the data you enter in iTunes Connect, but only the bundle ID needs to match the bundle ID you enter in iTunes Connect before you can upload your app to the store.

For iOS apps, a dialog similar to this appears when you create an Xcode project from a template:

../Art/3_xcodeassistant_2x.png

The product name is the name of your app as it will appear to customers in the store and should be similar to the app name you enter later in iTunes Connect. Most importantly, a customer should instantly associate the app name and icon in the App Store with the product name and app icon that installs on their devices. The product name is also the name that will appear in Springboard when the app is installed. The product name can’t be longer than 255 bytes and can be no fewer than 2 characters. (Read Best Practices in iTunes Connect Developer Guide for guidelines on choosing an app name.)

The organization name is an attribute of the Xcode project and is used in boilerplate text throughout your project folder. For example, the organization name is used in the source and header file copyright strings. The organization name in your Xcode project isn’t the same as the company name that you enter later in iTunes Connect.

The product name and company identifier you enter are concatenated to create the default bundle ID using reverse domain name service (reverse DNS) notation. The bundle ID needs to be unique to your app, so it’s important to set the company identifier to a unique string as well.

For iOS apps, you can choose the types of devices you support from the Devices pop-up menu. For Mac apps, you can choose the Mac App Store categories from a pop-up menu.

The other values used by the Xcode template are sufficient for building and running your app locally, but later you’ll need to finalize properties, such as the bundle ID. Also, the assistant doesn’t set all required properties for the store. You complete the basic store configuration before you submit. Ideally, you’ll complete this configuration before you distribute your app for testing too.

After your app is released, you can’t change some of this metadata, so it’s important to choose your settings carefully. To learn which app states cause some properties to be locked in iTunes Connect, refer to iTunes Connect App Properties in iTunes Connect Developer Guide.

Before You Begin Configuring Your Project

All of the options discussed in this chapter are located in the General pane in the project editor for your target. To open the project navigator, choose View > Navigators > Show Project Navigator. Choose the target from the Project/Targets pop-up menu or in the Targets section of the second sidebar if it appears. Click General to view settings discussed in this chapter.

The screenshot below shows the General pane for an iOS app.

../Art/3_project_navigator_2x.png

Configuring Identity and Team Settings

For Xcode to create the team provisioning profile, the app’s bundle ID needs to be unique and the project assigned to a team. Later, you provide other information that identifies this version of your app. The identity settings appear in the Identity section of the target’s General pane. For iOS apps, the Identity section appears as shown here:

../Art/3_ios_app_target_pane_2x.png

About Bundle IDs

A bundle ID precisely identifies a single app. A bundle ID is used during the development process to provision devices and by the operating system when the app is distributed to customers. For example, Game Center and In-App Purchase use a bundle ID to identify your app when using these app services. The preferences system uses this string to identify the app for which a given preference applies. Similarly, Launch Services uses the bundle ID to locate an app capable of opening a particular file, using the first app it finds with the given identifier. The bundle ID is also used to validate an app’s signature.

The bundle ID string must be a uniform type identifier (UTI) that contains only alphanumeric characters (A-Z,a-z,0-9), hyphen (-), and period (.). The string should be in reverse-DNS format. For example, if your company’s domain is Acme.com and you create an app named Hello, you could assign the string com.Acme.Hello as your app’s bundle ID.

During the development process, you use an app’s bundle ID in many different places to identify the app.

../Art/BundleID.png

Specifically, the bundle ID is located and used as follows:

  • In the Xcode project, the bundle ID is stored in the information property list file (Info.plist). This file is later copied into your app’s bundle when you build the project.

  • In Member Center, you create an App ID that matches the app’s bundle ID. If the App ID is an explicit App ID, it exactly matches the bundle ID. However, unlike domain names, bundle IDs are case sensitive. If the App ID is lowercase, your bundle ID needs to be lowercase, too.

  • In iCloud, the container IDs you specify in your Xcode project are based on the bundle IDs of one or more apps.

  • In iTunes Connect, you enter the bundle ID to identify your app. After your first version is available on the store, you can’t change your bundle ID or delete the associated explicit App ID.

Setting the Bundle ID

The default bundle ID in your Xcode project is a string formatted as a reverse-domain—for example, com.MyCompany.MyProductName. To create the default bundle ID, Xcode concatenates the company identifier with the product name you entered when creating the project from a template, as described in Setting Properties When Creating Your Xcode Project. (Xcode replaces spaces in the product name to create the default bundle ID.) It may be sufficient to replace the company identifier prefix in the bundle ID, or you can replace the entire bundle ID. For example, change the company identifier prefix to match your company domain name, or replace the entire bundle ID to match an explicit App ID.

For Mac apps, ensure that every bundle ID is unique within your app bundle. For example, if your app bundle includes a helper app, make sure that its bundle ID is different from your app’s bundle ID.

Follow these steps to change the bundle ID prefix in the General pane in the project editor.

To set the bundle ID prefix

  1. In the project navigator, select the project and your target to display the project editor.

  2. Click General and, if necessary, click the disclosure triangle next to Identity to reveal the settings.

    ../Art/3_ios_app_target_pane_2x.png
  3. Enter the bundle ID prefix in the Bundle Identifier field.

Alternatively, follow these steps to change the entire bundle ID in the Info pane in the project editor.

To set the bundle ID

  1. In the project navigator, select the project and your target to display the project editor.

  2. Click Info.

  3. Enter the bundle ID in the Value column of the “Bundle identifier” row.

    ../Art/3_ios_info_bundle_id_2x.png

Choosing a Signing Identity (Mac Only)

You have the choice of submitting your Mac app to the store, signing it with a Developer ID certificate to distribute it outside of the store, or not code signing it at all. If you select Mac App Store, you assign your Xcode project to a team and can enable app services, as described in Adding Capabilities. If you select Developer ID, you assign your Xcode project to a team but can’t use any app services in your application (read Distributing Applications Outside the Mac App Store for how to create a Developer ID-signed application). If you select None, the Team pop-up menu is disabled and you don’t need to read this guide.

To select a signing identity

  1. In the project navigator, select the project and your target to display the project editor.

  2. Click General and, if necessary, click the disclosure triangle next to Identity to reveal the settings.

  3. Select the type of signing identity you want to use.

    • If you want to submit your app to the store, select Mac App Store.

    • If you want to distribute your Mac application outside of the store and not use app services, select Developer ID.

    • If you don’t want to sign your application or use app services, select None.

    ../Art/3_selectdistributionmethod_2x.png

Assigning the Xcode Project to a Team

Each Xcode project is associated with a single team. If you enroll as an individual, you’re considered a one-person team. The team account is used to store the certificates, identifiers, and profiles needed to provision your app. All iOS apps and some Mac apps need to be code signed and provisioned to run on a device and use certain app services. Xcode creates these assets for you when needed, but you can avoid warnings and dialogs later if you set the team now.

To assign the project to a team

  1. In the project navigator, select the project and your target to display the project editor.

  2. Click General and, if necessary, click the disclosure triangle next to Identity to reveal the settings.

  3. Choose your team from the Team pop-up menu.

    • If you’re an individual, choose your name from the pop-up menu.

    • If you’re a company, choose your company name from the pop-up menu.

    ../Art/3_assignteam_ios_2x.png

    Xcode may attempt to create a team provisioning profile. For iOS apps, Xcode creates a team provisioning profile if you have an iOS device connected or have previously registered an iOS device. To resolve issues related to the team provisioning profile, read Creating the Team Provisioning Profile.

  4. If a team doesn’t appear in the Team pop-up menu, choose “Add an Account” and follow the steps described in Adding Your Apple ID Account in Xcode.

Creating the Team Provisioning Profile

After you select a team, Xcode attempts to create your code signing identity and a development provisioning profile. Xcode creates a specialized development provisioning profile called a team provisioning profile that it manages for you. A team provisioning profile allows an app to be signed and run by all team members on all their devices. If Xcode fails to create the team provisioning profile, a warning and Fix Issue button appear below the Team pop-up menu.

../Art/3_tb_noprovisioningprofile_2x.png

To create the team provisioning profile, Xcode performs these steps:

  1. Requests your development certificate

  2. Registers the iOS device chosen in the Scheme toolbar menu or your Mac

  3. Creates an App ID that matches your app’s bundle ID and enables app services

  4. Creates a team provisioning profile containing these assets

  5. Sets your project’s code signing build settings accordingly

You can assist Xcode and avoid common problems by creating the team provisioning profile now.

To create a team provisioning profile

  1. In the project navigator, select the project and your target to display the project editor.

  2. Click General and, if necessary, click the disclosure triangle next to Identity to reveal the settings.

  3. Verify that your bundle ID is unique by using a unique prefix.

    Depending on your project’s configuration, Xcode may create either a wildcard App ID or an explicit App ID. Because Xcode uses the bundle ID to register an explicit App ID, the bundle ID also needs to be unique during development. To avoid an App ID registration error, enter a unique bundle ID now, as described in Setting the Bundle ID.

  4. For iOS apps, connect an iOS device you want to use for development and choose the device from the Scheme toolbar menu.

    Xcode requires one or more registered devices in your account before it can create a team provisioning profile. (For Mac apps, Xcode automatically registers the Mac that’s running Xcode.) If you connect an iOS device to your Mac that matches the deployment target, Xcode registers the device for you. If the iOS device isn’t eligible because it doesn’t match the deployment target, upgrade the iOS on the device or change the deployment target, as described in Setting Deployment Info.

  5. If necessary, choose your team from the Team pop-up menu.

    For Mac apps, Mac App Store must be selected as the type of signing identity before you can choose a team.

  6. If a Fix Issue button appears below the Team pop-up menu, click it.

    ../Art/3_tb_noprovisioningprofile_2x.png

    Xcode starts performing all the steps needed to create a team provisioning profile for your app. If no warning message appears below the Team pop-up menu, Xcode already created your team provisioning profile.

  7. If dialogs or warnings appear, use the information to correct the problem and click Fix Issue again.

    After Xcode creates the team provisioning profile, the warning message under the Team pop-up menu disappears.

    ../Art/3_tb_team_profile_created_2x.png

Setting the Application Category (Mac Only)

Set the category under which your Mac app will be listed on the Mac App Store. The category you select should match the category you later select in your iTunes Connect app record.

To set the application category

  1. In the project navigator, select the project and your target to display the project editor.

  2. Click General and, if necessary, click the disclosure triangle next to Identity to reveal the settings.

  3. Choose the category from the Application Category pop-up menu.

    ../Art/3_selectdistributionmethod_2x.png

iOS app categories are set in iTunes Connect only. For more details on app categories, read Best Practices in iTunes Connect Developer Guide.

Setting the Version Number and Build String

The version number is a two-period-separated list of positive integers, as in 4.5.2. The first integer represents a major revision, the second a minor revision, and the third a maintenance release. The version number is shown in the store and that version should match the version number you enter later in iTunes Connect. For details on possible values, see CFBundleShortVersionString in Information Property List Key Reference.

The build string represents an iteration (released or unreleased) of the bundle and is also a two-period-separated list of positive integers, as in 1.2.3. For Mac apps, the user can click the version number in the About window to toggle between the version number and the build string. For details on possible values, see CFBundleVersion in Information Property List Key Reference.

For iOS apps, update the build string whenever you distribute a new build of your app for testing. iTunes will recognize that the build string changed and properly sync the new iOS app to the device. For how to configure your app for testing, read Beta Testing iOS Apps.

Set the version number and build string in the General pane in the project editor.

To set the version number and build string

  1. In the project navigator, select the project and your target to display the project editor.

  2. Click General and, if necessary, click the disclosure triangle next to Identity to reveal the settings.

  3. Enter the version number in the Version field, and enter the build string in the Build field.

    ../Art/3_tb_team_profile_created_2x.png

Setting Deployment Info

The default deployment settings are sufficient for development, but it’s best to review these settings before you distribute your app. Some settings must match values you enter in iTunes Connect later. For iOS apps, the deployment settings appear as shown here:

../Art/3_deployment_info_2x.png

Setting the Deployment Target

The deployment target setting specifies the lowest operating system version that your app can run on. For example, the lowest available setting for iPad apps is iOS 4.3.

There are several strategies for choosing the deployment target when developing your app. Each version of iOS or OS X includes features and capabilities not present in earlier versions. As new versions are published, some users may upgrade immediately, while other users may wait before moving to the latest version. You can target the latest version, taking full advantage of all the new features but limiting the app to only users running the latest version. Or you can target an earlier version, making your app available to more users but limiting the features you can use in the app. Another approach is to target an earlier version but use weak linking to determine at runtime whether later version features are available before using them.

For details on weak linking, read Weak Linking and Apple Frameworks in SDK Compatibility Guide.

To set the target version

  1. In the project navigator, select the project and your target to display the project editor.

  2. Click General and, if necessary, click the disclosure triangle next to Deployment Info to reveal the settings.

  3. Choose the version you want to target from the Deployment Target pop-up menu.

    ../Art/3_deployment_target_2x.png

Xcode sets the Minimum System Version key in the app’s information property list to the deployment target you choose. When you publish your app to the store, it uses this property value to indicate which versions your app supports.

Setting the Target Devices (iOS Only)

The Devices setting identifies the type of devices you want an iOS app to run on. There are two device types: iPhone and iPad. The iPhone type includes iPhone and iPod touch devices. The iPad type includes all iPad and iPad mini devices.

To set the target devices

  1. In the project navigator, select the project and your target to display the project editor.

  2. Click General and, if necessary, click the disclosure triangle next to Deployment Info to reveal the settings.

  3. From the Devices pop-up menu, choose iPhone, iPad, or Universal (to target both families).

    ../Art/3_target_devices_setting_2x.png

For more information on configuring your app for iPhone, iPad, or both device families, see Advanced App Tricks in iOS App Programming Guide.

Adding App Icons and a Launch Screen File

App icons and the launch screen file are stored in the app bundle, not uploaded as separate assets to iTunes Connect. The operating system uses these images and the launch screen file (a .xib file) in various locations on a device to represent your app. In general, artwork displayed by the operating system resides in the bundle, and artwork displayed by iTunes is uploaded to iTunes Connect. Your app needs an app icon to represent it and pass validation tests.

You use an asset catalog that manages the app icons for you or maintain individual image files yourself. If you create a new project, asset catalogs are used by default to store app icons and a launch screen file is used as a splash screen. For iOS 7 deployment targets, you can supply both a launch screen file and launch images. In iOS 8, the launch screen file is used, and in iOS 7, the launch images are used. If you have an older project, you can migrate from managing individual icon image files to an asset catalog. You can also add a launch screen file to an older Xcode project.

If you prefer to manage your assets as individual image files, read Setting Individual App Icon and Launch Image Files. If you want to migrate to an asset catalog, read Migrating Your Images to an Asset Catalog. To learn more about creating and managing asset catalogs, read Asset Catalog Help.

Preparing Your Artwork

For all artwork, keep the file size as small as possible for a positive purchase experience for your users.

For iOS apps, see Icon and Image Sizes in iOS Human Interface Guidelines for the sizes of all required app icons, launch images, and other icons.

In iOS 7, a launch image matching the device resolution appears as soon as the user taps your app icon. Use screenshots to create your app’s launch images. To take advantage of Retina displays, provide high-resolution images for each device you support. For guidance on creating launch images, read Launch Images.

For the required Mac app icons, see Creating Great Icons for Any Resolution in OS X Human Interface Guidelines. This table includes icon sizes that may be used on the Mac App Store. To create your app icon files, read Provide High-Resolution Versions of All App Graphics Resources in High Resolution Guidelines for OS X.

For the specification of screenshots and other artwork that you upload later using iTunes Connect, read iTunes Connect App Properties in iTunes Connect Developer Guide.

Adding App Icons to an Asset Catalog

Versions of your app icons are organized into image sets in an asset catalog. Xcode automatically creates image sets for the app’s target device—for example, both iPhone and iPad image sets appear if your iOS app’s target is universal.

To add an app icon to an asset catalog

  1. In the project navigator, select the project and your target to display the project editor.

  2. In the “App Icons and Launch Images” section of the General pane, click the arrow button to the right of the App Icons Source pop-up menu.

    ../Art/3_app_icon_arrow_2x.png
  3. In the Finder, drag an app icon to the image well that matches its resolution in the project navigator.

    ../Art/3_add_app_icon_to_asset_catalog_2x.png

Creating a Launch Screen File

The launch screen file is displayed as a splash screen while your app is launching. It’s a single, atomic .xib file that uses size classes to support different device resolutions. It contains basic UIKit views, such as UIImageView and UILabel objects, and uses Auto Layout constraints. Xcode adds a default launch screen file, called LaunchScreen.xib, to your project.

Follow these guidelines when creating a launch screen file:

  • Use only UIKit classes.

  • Use a single root view that is a UIView or UIViewController object.

  • Don’t make any connections to your code (don’t add actions or outlets).

  • Don’t add UIWebView objects.

  • Don’t use any custom classes.

  • Don’t use runtime attributes.

You can add a launch screen file to an older Xcode project.

To create a launch screen file for an existing project

  1. Choose File > New > File.

  2. Under iOS, select User Interface.

  3. Click Launch Screen and click Next.

    ../Art/3_create_launch_screen_file_2x.png
  4. Enter a filename in the Save As text field, and click Create.

To set the launch screen file

  1. If necessary, open the “App Icons and Launch Images” section of the General pane.

  2. From the Launch Screen File pop-up menu, choose a launch screen file.

Adding Launch Images and Capturing Screenshots

For iOS 7 deployment targets, add an asset catalog for launch images, described in Migrating Your Images to an Asset Catalog. Capture screenshots to create the launch images and add them to the asset catalog, similar to adding app icons to an asset catalog, described in Adding App Icons to an Asset Catalog.

Follow these steps to capture a screenshot of your iOS app while your device is connected to your Mac. Although the screenshot includes the status bar as it looks when the screenshot is captured, iOS replaces it with the current status bar when your app launches.

To capture a screenshot on your iOS app

  1. Connect the iOS device to your Mac.

  2. Choose Window > Devices, and select the device under Devices.

  3. In the Device Information section, click Take Screenshot.

    ../Art/3_take_screenshot_2x.png

    The screenshot appears on your desktop.

Setting Individual App Icon and Launch Image Files

If you don’t want to use an asset catalog, choose “Don’t use asset catalogs” from either the App Icons Source or Launch Images Source pop-up menu in the “App Icons and Launch Images” section of the General pane. If a Use Asset Catalog button appears, you are not using an asset catalog.

Migrating Your Images to an Asset Catalog

If you have an older project, you can migrate your image files to an asset catalog that manages your app icons and launch images for you. Xcode moves the image files from the tables to the new asset catalog. You create a separate asset catalog for app icons and launch images, but the steps are identical.

To migrate to an asset catalog

  1. In the project navigator, select the project and your target to display the project editor.

  2. Click General and, if necessary, click the disclosure triangle next to “App Icons and Launch Images.”

  3. Click the Use Asset Catalog button next to either App Icons Source or Launch Images Source.

    ../Art/3_use_asset_catalog_2x.png
  4. In the dialog that appears, choose either Images or New Asset Catalog from the pop-up menu, and click Migrate.

    ../Art/3_migrate_to_catalog_2x.png

To view the asset catalog, click the arrow button to the right of the App Icons Source or Launch Images Source pop-up menu.

Setting the Copyright Key (Mac Only)

Make sure that your information property list file contains a valid value for the Copyright key. For details on possible values, see NSHumanReadableCopyright in Information Property List Key Reference.

To edit the copyright key in the information property list

  1. In Xcode, select the project in the project navigator.

  2. Click the disclosure triangle next to the ProjectName folder to reveal its contents.

  3. Click the disclosure triangle next to the Supporting Files subfolder to reveal its contents.

  4. Select the ProjectName-Info.plist file.

    The information property list is displayed to the right in a property list editor.

    ../Art/3_copyright_key_2x.png
  5. Double-click in the Value column and in the row of the Copyright key.

  6. Enter a new value for the key.

For how to edit other cells in a property list, refer to Property List Editor Help.

Verifying Your Build Settings

If you changed the default build settings, verify some of the settings before submitting your app to the store. You do this in the Build Settings pane of the project editor.

To edit a build setting

  1. In the project editor, select the project or target whose build setting you want to edit.

  2. At the top of the project editor, click Build Settings.

    ../Art/3_edit_build_settings_2x.png
  3. Locate the build setting in the left column, or enter the name of the build setting in the search field in the upper-right corner.

  4. If some build settings don’t appear, click All.

  5. Set the value for the build setting in the right column.

Setting Architectures for iOS Apps

The Architectures build setting identifies the architectures for which your app is built. An iOS device uses a set of architectures, which include armv7 and arm64. You have two options for specifying the value of this setting:

  • Standard. Produces an app binary with a common architecture, compatible with all supported iOS devices. This option generates the smallest app, but it may not be optimized to run at the best possible speed for all devices.

  • Other. Produces an app binary for a specified set of architectures.

If you select Other from the Architectures build-setting value list, click the Add button (+) to enter the custom iOS-device architecture names you support.

Setting the Base SDK

The Base SDK version number must be greater than or equal to the software version number on your development device; otherwise, Xcode can’t initiate a debugging session with the device. Set the Base SDK for your project and targets to the latest operating system, which is the default value. The Base SDK property is located in the Architectures area in the Build Settings pane. For iOS apps, set Base SDK to Latest iOS. For Mac apps, set Base SDK to Latest OS X. If you select another value, download and install the latest SDK version that’s greater than or equal to your device software version.

To go to the Architectures area, select the project or target and click Build Settings. The Architectures area appears first in the Build Settings pane.

../Art/3_base_sdk_2x.png

Setting the Debug Information Format

Set the Debug Information Format build setting to “DWARF with dSYM File.” This is required to symbolicate crash reports, as described in Analyzing Crash Reports.

../Art/3_debug_info_format_2x.png

Recap

In this chapter, you learned how to configure your Xcode project from a template, set the app’s identity information, and create a team provisioning profile for development. During development, refer to this chapter as needed. Later, use this chapter as a checklist for the settings that are required by the App Store and Mac App Store.