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 app 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 app services launches only if the Mac is in the provisioning profile.

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. If a prompt appears asking whether codesign can sign the app using a key in your keychain, click Always Allow.

Launching Your iOS App on a Connected 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 an iOS device to your Mac.

  2. In the project navigator, choose your device from the Scheme toolbar menu.

    Xcode assumes you intend to use the selected device for development and automatically registers it for you.

    ../Art/5_launchappondevice_2x.png

    If your iOS device is disabled in the Scheme toolbar menu because it is ineligible, fix the issue before continuing. For example, if the device doesn’t match the deployment target, upgrade the version of iOS on the device or choose the version you want to target from the Deployment Target pop-up menu in the Deployment Info section and then select the iOS device from the Scheme toolbar menu.

  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.

Removing an iOS Device from the Scheme Menu

If you want Xcode to ignore a connected iOS device—you don’t want Xcode to add it to the team provisioning profile—remove it from the Scheme menu.

To remove an iOS device from the Scheme menu

  1. Connect the iOS device to your Mac.

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

  3. In the lower-left corner of the Devices window, click the Action button (the gear icon to the right of the Add button).

    ../Art/4_removedevicefrommenu_2x.png
  4. Deselect “Show in Run Destinations Menu” from the pop-up menu.

    In the project editor, the iOS device disappears from the Scheme menu.

Removing an App from an iOS Device

When you launch an app on an iOS device, Xcode installs the app on the device. Later, you can remove the app from the device using the Devices window in Xcode.

To remove an app from an iOS device

  1. Connect the iOS device to your Mac.

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

  3. In the Apps section, select the app from the table and click the Delete button (–) in the lower-left corner of the table.

    ../Art/5_removeappfromdevice_2x.png

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. In Certificates, Identifiers & Profiles, select Devices.

  2. 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.

    ../Art/5_verify_device_ios_2x.png

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.

    ../Art/5_ios_profiles_2x.png

    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.

    ../Art/5_ios_teamprofile_2x.png

    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.

Troubleshooting

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 app services 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 profile 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 a subset of app services. However, if you add a capability that requires an explicit App ID—for example, iCloud, 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.

../Art/team_provisioning_ios_2x.png

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

../Art/team_provisioning_mac_2x.png

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 in Member Center to learn more about your responsibilities.

Recap

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.