Launching Your App on Devices

All iOS apps and most Mac apps must be code signed and provisioned to launch on a device. Provisioning is the process of preparing and configuring an app to launch on devices and use certain services. Xcode uses information you provide to create a team provisioning profile for you when you assign your Xcode project to a team or the first time you add capabilities to your app. For example, Xcode offers to create your development certificate and automatically registers a connected iOS device or your Mac. Xcode uses this information to create a team provisioning profile that’s ultimately installed on the device. For iOS apps, Xcode runs an app on a device (an iPad, iPhone, or iPod touch) if that device is in the provisioning profile. Similarly, a Mac app that uses certain Apple services launches only if the Mac is in the provisioning profile.

To avoid issues later when you distribute your app, test your app on a device using the debug navigator, as described in Debug Navigator Help, test navigator, as described in Test Navigator Help, and Instruments app, as described in Instruments User Guide.

Launching Your iOS App on a Device

It takes just a few steps to launch your app on a device if you previously created your code signing identity and team provisioning profile, as described in “Creating the Team Provisioning Profile.” Otherwise, a series of dialogs and warnings may appear as Xcode resolves the code signing issues in the process of launching your app.

To launch an iOS app on a device
  1. Connect a device that’s enabled for development to your Mac.

  2. In the project navigator, choose your device from the destination Scheme pop-up menu.

    Xcode assumes you intend to use the selected device for development and automatically registers it for you. If the device doesn’t appear in the Scheme pop-up menu, enable it for development, as described in “Registering Devices Using Xcode.”

  3. Click the Run button.

    Xcode installs the app on the device before launching the app.

  4. If a prompt appears asking whether codesign can sign the app using a key in your keychain, click Always Allow.

While developing your app, run and test it on all of the iOS devices and iOS versions that you intend to support. Because different instruments are available in iOS Simulator, also test your app in iOS Simulator using Instruments and other tools before distributing your app. For details on how to use iOS Simulator to test your app, read iOS Simulator User Guide.

Launching Your Mac App

To launch your Mac app, click the Run button in the project navigator. Xcode automatically registers your Mac and adds it to the team provisioning profile.

Verifying Your Steps

To learn more about how Xcode provisions your app, examine the team provisioning profile in Member Center. You can verify that the device was registered and added to the team provisioning profile.

To verify that your device is registered
  1. Under Devices, select All.

    The device you registered should appear enabled in the list. Enabled devices appear in black text and disabled devices appear in gray text.

To verify that your device is added to the team provisioning profile
  1. In Certificates, Identifiers & Profiles, select Provisioning Profiles.

  2. Under the Provisioning Profiles section, select All.

    The team provisioning profile, starting with the text “iOS Team Provisioning Profile” or “Mac Team Provisioning Profile,” should appear under iOS Provisioning Profiles or Mac Provisioning Profiles.


    You may have multiple team provisioning profiles depending on the capabilities you add and the number of apps.

  3. Click the team provisioning profile to view its details.

    The team provisioning profile contains an App ID—either for iOS apps (Xcode iOS Wildcard App ID) or for Mac apps (Xcode Mac Wildcard App ID). The screenshot below shows an iOS Provisioning Profile.


    Listed beneath the App ID is the number of development certificates and devices contained in the provisioning profile. The values should equal the total number of iOS Development or Mac Development certificates and enabled devices contained in your account. If you’re an individual, you should have only one development certificate.


There are several reasons why your app may not run on a device.

Assuming that you followed and verified the steps in this chapter, check the Xcode project settings. The configuration of your project may not match the configuration of your device.

Team Provisioning Profiles in Depth

A team provisioning profile is a development provisioning profile that Xcode manages for you. A development provisioning profile allows your app to launch on devices and use certain technologies during development. For an individual, a team provisioning profile allows all apps signed by you to run on all of your registered devices. For a company, a team provisioning allows any app developed by a team to be signed by any team member and installed on any team device.

The team provisioning profile contains:

Xcode creates App IDs and team provisioning profiles as needed depending on the configuration and capabilities of your app. Xcode adds all of the devices and development certificates from all team members to the team provisioning profile. Thereafter, Xcode updates the team provisioning profile whenever you register a device, create a development certificate, or modify the App ID. (Changes you make to your team assets using Member Center don’t automatically update team provisioning profiles.)

If your app can use a wildcard App ID during development, Xcode creates a team provisioning profile named iOS Team Provisioning Profile: * or Mac Team Provisioning Profile: * using a wildcard App ID it also creates. You can use a wildcard App ID with iCloud and some other iOS-specific technologies. However, if you add a capability that requires an explicit App ID—for example, Game Center or In-App Purchase—, Xcode creates an explicit App ID and a corresponding team provisioning profile called iOS Team Provisioning Profile: or Mac Team Provisioning Profile: followed by the bundle ID. Because an explicit App ID exactly matches the project’s bundle ID, you can register only one explicit App ID per bundle ID. Therefore, if one already exists in Member Center, Xcode uses it in the team provisioning profile instead of creating one for you.

This diagram shows an iOS Team Provisioning Profile using a wildcard App ID for a company with three team members.


This diagram shows a Mac Team Provisioning Profile using an explicit App ID for a Mac company.


Team agents need to approve team member development certificates and devices before they’re added to the team provisioning profile. If you enrolled as a company, read “Managing Your Team” to learn more about your responsibilities.


In this chapter, you learned how to use the team provisioning profile, which Xcode creates and manages for you, to launch your app on devices. You learned what information Xcode needs to create the team provisioning profile, how to verify that Xcode registered your devices, and how to troubleshoot if Xcode displays errors or warnings.