Adding Capabilities

Certain technologies and services—such as iCloud and push notifications—are available only to apps distributed through the store and require additional configuration in your Xcode project, Member Center, and sometimes iTunes Connect. Some technologies and services are for certain types of apps, such as games and Newsstand apps, and provide additional sources of revenue, such as In-App Purchase and iAd Network.

Apple implements an underlying security model to protect both user data and your app from being modified and distributed without your knowledge. Hence, your app is code signed and provisioned to use only the key Apple technologies and services that you specify. When you add capabilities to your app using Xcode, Xcode automatically configures your project to use them. Xcode edits the entitlements and information property list files for you and adds technology-specific frameworks as needed. For entitlements to take effect, Xcode creates code signing and provisioning assets for your team and sets your code signing build settings for you. Xcode creates a wildcard App ID and explicit App ID, if needed, to enable the technologies you choose. Some technologies—such as Game Center and In-App Purchase—may require additional setup in Member Center and iTunes Connect.

This chapter describes all the steps that you perform to access Apple services from your app.

About Entitlements

An entitlement is a single right granted to a particular app, tool, or other executable that gives it additional permissions above and beyond what it would ordinarily have. The term entitlement is most commonly used in the context of a sandbox, and to a lesser degree for an App ID. Regardless of the location, an entitlement is a piece of configuration information included in your app’s code signature—telling the system to allow your app to access certain resources or perform certain operations. In effect, an entitlement extends the sandbox and capabilities of your app to allow a particular operation to occur.

You set some entitlements for an App ID in Member Center—for example, by enabling certain technologies and services—and others in the Xcode project. The technologies enabled for an App ID serve as a white list of the technologies one or more apps may use. Some technologies are enabled by default for an explicit App ID. The Xcode project configuration specifies which technologies the app actually uses.

Before You Begin

All of the options discussed in this chapter are located in the Capabilities pane in the project editor for your target.

The screenshot below shows the Capabilities for an iOS app.

../Art/4_capabilitieseditor_2x.png
bullet
To open the Capabilities pane
  1. Choose View > Navigators > Show Project Navigator.

  2. Choose the target from the Project/Targets pop-up menu or in the Targets section of the second sidebar if it appears.

    ../Art/4_choose_target_2x.png
  3. Click Capabilities to view key technologies and services you can add to your app.

Xcode creates code signing and provisioning assets for you as you need them but because some assets depend on others, dialogs may appear asking you to fix problems while you enable capabilities. For example, you may be asked to assign a team to your project, create a development certificate, and register a device so that Xcode can create your team provisioning profile. A development provisioning profile is not required to enable capabilities, but is required to build and launch an app that uses the capabilities. To avoid these dialogs and warnings, create your code signing identity and team provisioning profile now, as described in “Creating the Team Provisioning Profile.” Otherwise, read “Troubleshooting” for how to resolve issues as they occur.

Configuring App Sandbox for Mac Apps

Sandboxing provides the last line of defense against stolen, corrupted, or deleted user data if malicious code exploits your app. Sandboxing also minimizes damage from coding errors in your app or in frameworks you link against. Simply enabling sandboxing provides the maximum level of restrictions on how an app can interact with the rest of the system. All apps submitted to the Mac App Store are required to use sandboxing. Therefore, if you plan to submit your app to the Mac App Store, enable sandboxing during development.

You configure sandboxing by enabling this feature and then optionally granting permission for specific types of functions.

bullet
To configure App Sandbox
  1. In the project navigator, select the project and your target to display the project editor.

  2. Click Capabilities.

  3. If App Sandbox isn’t enabled, select the switch in the App Sandbox row.

    ../Art/4_enableappsandbox1_2x.png

    Xcode adds an entitlements file to your project and automatically enters default values for some entitlements. Xcode also enables the App Sandbox entitlement.

  4. Use the App Sandbox checkboxes in this area to describe the minimum set of capabilities the target needs to do its job.

    ../Art/4_enableappsandbox_2x.png

You can set specific permissions for file types, too. To set the access for a file type, choose a permission from the pop-up menu in the row that best describes the file type.

../Art/4_appsandboxfileaccess_2x.png

For a complete description of App Sandbox entitlements, refer to Entitlement Key Reference. If you’re enabling sandboxing for an existing app, read App Sandbox Design Guide to learn the locations that a sandboxed app can access.

Adding iCloud Support

iCloud storage allows you to share a user’s data among multiple instances of your app running on different iOS devices and Macs. Your app needs to be provisioned to use iCloud, which includes setting entitlements in your Xcode project.

Enabling iCloud

Before you can configure iCloud key-value storage or iCloud document storage, you enable iCloud in Xcode.

bullet
To enable iCloud
  1. In the project navigator, select the project and your target to display the project editor.

  2. Click Capabilities.

  3. If iCloud isn’t enabled, select the switch in the iCloud row.

    ../Art/4_enableicloud_2x.png
  4. If a dialog appears asking whether Xcode should request a development certificate on your behalf, click Request.

Xcode automatically provisions your app to use iCloud.

Configuring iCloud Key-Value Storage

iCloud key-value storage allows an app to share small amounts of data with other instances of itself running on the user’s other devices.

bullet
To configure iCloud key-value storage
  1. In the project editor, click Capabilities and, if necessary, click the iCloud disclosure triangle.

  2. Select “Use key-value store.”

    The identifier defaults to your bundle ID.

    ../Art/4_enablekeyvaluestorage_2x.png
  3. If you want to change the identifier, double-click your bundle ID and enter a new identifier in the Ubiquity Containers area.

    For most apps, the default value is what you want. However, if your app shares its key-value storage with another app, you must specify the bundle identifier for the other app instead.

To learn how to use iCloud key-value storage for preferences, read iCloud Design Guide.

Configuring iCloud Document Storage

iCloud document storage is used to store user documents and app data in the user’s iCloud account. Each app has a container in the user’s iCloud account identified by its App ID. An app can access containers belonging to other apps created by your team as well.

To configure iCloud document storage, add one or more iCloud containers. Add your bundle ID to the container list or add a wildcard App ID to match a set of App IDs. The first container identifier can’t be a wildcard App ID.

bullet
To add an iCloud container
  1. In the project editor, click Capabilities and, if necessary, click the iCloud disclosure triangle.

  2. Click the Add button (+) at the bottom of the Ubiquity Containers area.

  3. Enter the App ID for the container you want to add.

    ../Art/4_enabledocumentstorage_2x.png

To delete a container, select it in the Ubiquity Containers area, and click the Delete button (–).

For guidance on selecting iCloud containers, read iCloud Design Guide.

Enabling Game Center

Game Center is Apple’s social gaming network. It allows players to connect their devices to the Game Center service and to exchange information.

To use Game Center, first enable Game Center in Xcode.

bullet
To enable Game Center
  1. In the project navigator, select the project and your target to display the project editor.

  2. Click Capabilities.

  3. If Game Center isn’t enabled, select the switch in the Game Center row.

    ../Art/4_enablegamecenter_2x.png
  4. If a dialog appears asking whether Xcode should request a development certificate on your behalf, click Request.

Xcode automatically provisions your app to use Game Center and adds the Game Kit framework to your project.

For Mac apps, Xcode also sets your Outgoing network entitlements in the App Sandbox section, located in the Capabilities pane in Xcode. If your app also listens for network connections, it needs to allow incoming connections. To set additional network entitlements, read “Configuring App Sandbox for Mac Apps.”

For how to write your Game Kit code, read Game Center Programming Guide. To configure your app in iTunes Connect, read “Adding New Apps” in iTunes Connect Developer Guide to create the app record (enter your explicit App ID), and read Game Center Configuration Guide for iTunes Connect to configure game features.

Enabling In-App Purchase

In-App Purchase embeds a store directly into your app by enabling you to connect to the store and securely process payments from the user. You can use In-App Purchase to collect payment for enhanced functionality or for additional content usable by your app. After configuring this technology in your Xcode project, you configure it in iTunes Connect. You also use iTunes Connect to create your in-app purchases.

bullet
To enable In-App Purchase
  1. In the project navigator, select the project and your target to display the project editor.

  2. Click Capabilities.

  3. If In-App Purchase isn’t enabled, select the switch in the In-App Purchase row.

    ../Art/4_enableinapppurchase_2x.png
  4. If a dialog appears asking whether Xcode should request a development certificate on your behalf, click Request.

Xcode automatically provisions your app to use In-App Purchase and adds the Store Kit framework to your project for you.

For how to write your In-App Purchase code, read In-App Purchase Programming Guide. To create an app record and enter the explicit App ID in iTunes Connect, read “Adding New Apps” in iTunes Connect Developer Guide. To create in-app purchases, read In-App Purchase Configuration Guide for iTunes Connect.

Configuring Keychain Sharing

Enabling keychain sharing allows your app to share passwords in the keychain with other apps developed by your team.

bullet
To enable keychain sharing
  1. In the project navigator, select the project and your target to display the project editor.

  2. Click Capabilities.

  3. If Keychain Sharing isn’t enabled, select the switch in the Keychain Sharing row.

    ../Art/4_enablekeychain_2x.png
  4. If a dialog appears asking whether Xcode should request a development certificate on your behalf, click Request.

Xcode adds the keychain-access-groups key to the entitlements file.

If you want, you can restrict your app to a set of keychain access groups.

bullet
To limit your app to a set of keychain access groups
  1. In the project editor, click Capabilities and, if necessary, click the Keychain Sharing disclosure triangle.

  2. Click the Add button (+) at the bottom of the Keychain Groups area.

  3. Enter the keychain access group you want to add.

    ../Art/4_enablekeychain2_2x.png

To delete a keychain access group, select it in the Keychain Groups area and click the Delete button (–).

Configuring Push Notifications

Apple Push Notification service (APNs) allows an app that isn’t running in the foreground to notify the user that it has information for the user. Unlike other capabilities, you don’t configure push notifications in your Xcode project. To enable push notifications, you create an explicit App ID that enables push notifications and a corresponding client SSL certificate.

You can create only one explicit App ID that matches your bundle ID. Therefore, if Xcode created an explicit App ID for you—for example, when you added another capability that requires an explicit App ID—you should use it; otherwise, you create an explicit App ID that matches your bundle ID. You then generate and download a corresponding client SSL certificate—this step fully enables push notifications—and refresh provisioning profiles in Xcode. Later, you install the client SSL certificate and key on your server.

To learn more about using push notifications in your app, read Local and Push Notification Programming Guide.

Locating Your App’s Explicit App ID

Normally, Xcode creates and manages App IDs for you. For example, if you enable iCloud first, Xcode creates a wildcard App ID—either for iOS apps (Xcode iOS Wildcard App ID) or for Mac apps (Xcode Mac Wildcard App ID). If you later enable Game Center or In-App Purchase, Xcode creates an explicit App ID. However, if you disable Game Center, Xcode continues using the explicit App ID. So, first check Member Center to see if your app has an explicit App ID.

bullet
To locate an explicit App ID
  1. In Member Center, select Certificates, Identifiers & Profiles.

  2. Under Identifiers, select App IDs.

  3. Locate an App ID whose ID is the same as the bundle ID.

    Compare the values in the ID column with the bundle ID that appears in the General pane in the Xcode project editor. In Member Center, the name of an Xcode-managed explicit App ID begins with the text “Xcode iOS App ID” or “Xcode Mac App ID.”

    ../Art/4_locateappid_2x.png

Creating an Explicit App ID

If no explicit App ID matches the bundle ID, create an explicit App ID, as described in “Registering App IDs.” When prompted to select services, select the Push Notifications checkbox and follow the steps in “Enabling Push Notifications” to generate a client SSL certificate.

Enabling Push Notifications

You enable push notifications when you create or edit an explicit App ID, but push notifications aren’t fully enabled until you generate a client SSL certificate. A client SSL certificate allows your notification server to connect to the APNs. Each App ID is required to have its own client SSL certificate. As with signing certificates, you use separate client SSL certificates for development and production.

Create the development SSL certificate when you first enable push notifications and later return to Member Center to create the production SSL certificate, as described in “Creating Push Notification Client SSL Certificates.”

bullet
To enable push notifications
  1. In Certificates, Identifiers & Profiles, select Identifiers.

  2. Under Identifiers, select App IDs.

  3. Select the explicit App ID and click Edit.

    ../Art/4_editappid_2x.png
  4. Scroll down and select the Push Notifications checkbox.

  5. Click Create Certificate under the type of SSL certificate you want to create.

    ../Art/4_enablepushnotifications_2x.png
  6. Follow the instructions on the next webpage to create a certificate request on your Mac, and click Continue.

  7. Click Choose File.

  8. In the dialog that appears, select the certificate request file (with a .certSigningRequest extension) and click Choose.

  9. Click Generate.

    ../Art/4_generatesslcertificate_2x.png
  10. Optionally, click Download.

    You can also download the certificate from Member Center later.

  11. Click Done.

Verifying Your Steps

Verify that the App ID enables push notifications.

bullet
To verify the App ID settings
  1. In Certificates, Identifiers & Profiles, select Identifiers and under Identifiers, select App IDs.

  2. Select the explicit App ID that matches the bundle ID.

    A green circle followed by Enabled appears in the Push Notifications row and Development or Distribution column depending on the type of client SSL certificate you created earlier. A yellow circle followed by Configurable in either the Development or Distribution column indicates a missing client SLL certificate.

    ../Art/4_verifyappid_2x.png

If a development SLL certificate is missing, read “Creating Push Notification Client SSL Certificates” to create it.

Refreshing Provisioning Profiles in Xcode

Changes you make using Member Center don’t automatically appear in Xcode. Therefore, refresh the provisioning profiles in Xcode before you start using push notifications. Xcode creates a corresponding development provisioning profile or regenerates an existing provisioning profile for you. An Xcode-managed provisioning profile that uses an explicit App ID begins with the text “iOS Team Provisioning Profile:” or “Mac Team Provisioning Profile:” followed by the bundle ID.

bullet
To refresh provisioning profiles
  1. In the Xcode Preferences window, click Accounts.

  2. Select your team, and click View Details.

    ../Art/2_aboutaccountsprefs_2x.png../Art/2_aboutaccountsprefs_2x.png
  3. In the dialog that appears, click the Refresh button in the lower-left corner.

    ../Art/4_refreshprofiles_2x.png../Art/4_refreshprofiles_2x.png
  4. If a dialog appears asking to create your distribution certificate, click Not Now or Request.

  5. Click Done.

Verifying Your Steps

Use Member Center to verify that the provisioning profile was either created or regenerated to enable push notifications.

bullet
To verify that a provisioning profile enables push notifications
  1. In Certificates, Identifiers & Profiles, select Identifiers.

  2. Under Provisioning Profiles, select Development.

  3. Select the Xcode-managed provisioning profile that matches the bundle ID.

    Push notifications should appear in the “Enabled Services” list. (In-App Purchase and Game Center are enabled by default for an explicit App ID.)

    ../Art/4_verifyprofile_2x.png

Installing Client SSL Certificates

For how to install the client SSL certificate and key on a server, read “Provisioning Procedures” in Local and Push Notification Programming Guide. For techniques to resolve push notification server issues, read Troubleshooting Push Notifications.

Configuring Maps

The Maps service allows apps to get directions or ask the Maps app to display directions. In addition, iOS apps that are able to display point-to-point directions can register as routing apps and make those directions available to Maps and other apps. For both iOS and Mac apps, you use Xcode to enable the Maps service. For iOS routing apps, you use iTunes Connect to upload a geographic coverage file.

For how to write your MapKit framework code, read Location and Maps Programming Guide.

Enabling Maps in Xcode

Enable Maps in your Xcode project, and for iOS routing apps, select one or more supported modes.

bullet
To enable Maps and select modes
  1. In the project navigator, select the project and your target to display the project editor.

  2. Click Capabilities.

  3. If Maps isn’t enabled, select the switch in the Maps row.

    ../Art/4_enablemaps1_2x.png
  4. If a dialog appears asking whether Xcode should request a development certificate on your behalf, click Request.

  5. For iOS routing apps, select one or more supported modes from the checkboxes below.

    You’re required to select one or more supported Routing modes.

    ../Art/4_enablemaps_2x.png

For iOS apps, Xcode adds necessary keys to your information property list, and adds the Map Kit framework to your project. For Mac apps, Xcode adds a Maps entitlement to the App ID and adds the Map Kit framework to your project.

Configuring an iOS Routing App

You perform additional steps to configure an iOS app that provides point-to-point directions for other apps. Before continuing, review the tasks that you perform to configure an iOS routing app:

Task

../Art/checkbox_checked_2x.png

Enable Maps in Xcode.

../Art/checkbox_checked_2x.png

Select one or more supported modes in Xcode.

../Art/checkbox_unchecked_2x.png

Write the code to provide routing directions.

../Art/checkbox_unchecked_2x.png

Create an app record and optionally, upload your app’s geographic coverage file.

../Art/checkbox_unchecked_2x.png

Upload a binary of your app to the store.

../Art/checkbox_unchecked_2x.png

If necessary, upload your app’s geographic coverage file.

Providing Routing Directions

To learn how to create a routing app, read “Providing Directions” in Location and Maps Programming Guide.

Creating an App Record in iTunes Connect

To create an app record in iTunes Connect, follow the steps in “Adding New Apps” in iTunes Connect Developer Guide. Routing apps must provide a geographic coverage file that defines the regions that your app supports. You can upload the geographic coverage file when you create the app record, or later after you upload a binary, as described in “Uploading the Geographic Coverage File to iTunes Connect.”

Submitting a Binary to the Store

To upload a binary to iTunes Connect, follow the steps in “Submitting Your App.”

Uploading the Geographic Coverage File to iTunes Connect

If you submit a binary for a routing app, Apple doesn’t start the approval process until you upload the geographic coverage file.

bullet
To upload the geographic coverage file after you submit your binary
  1. Sign in to iTunes Connect.

  2. On the iTunes Connect homepage, click Manage Your Apps.

  3. Locate the app you want to edit, and click the large icon or app name.

  4. Click View Details for the version of your app that you want to edit.

  5. Click the Edit button that appears next to the Version Information section.

  6. Click the Choose File button under Routing App Coverage File.

  7. Locate the file and click Choose.

  8. Click Upload File.

    If the file isn’t formatted correctly, a message appears at the top of the page.

Configuring Passbook for iOS Apps

Passbook presents digital representations of information—such as a coupon, ticket for a show, or boarding pass—that allow users to redeem a real-world product or service. You can use Passbook in several ways:

First, you enable Passbook in your Xcode project.

bullet
To enable Passbook
  1. In the project navigator, select the project and your target to display the project editor.

  2. Click Capabilities.

  3. If Passbook isn’t enabled, select the switch in the Passbook row.

    ../Art/4_enablepassbook_2x.png
  4. If a dialog appears asking whether Xcode should request a development certificate on your behalf, click Request.

Xcode automatically provisions your app to use Passbook and adds the Pass Kit framework to your project.

Optionally, you can restrict your app to a subset of your pass type identifiers. This is especially useful if you develop multiple apps that use passes.

If you don’t have a pass type identifier, create one before enabling this feature.

bullet
To create a pass type identifier
  1. In Certificates, Identifiers & Profiles, select Identifiers.

  2. Under Identifiers, select Pass Type IDs.

  3. Click the Add button (+) in the upper-right corner.

  4. Enter a description and identifier, and click Continue.

    ../Art/4_createpasstypeid_2x.png
  5. Review the settings and click Register.

  6. Click Done.

You can then use Xcode to restrict your app to a set of pass type identifiers.

bullet
To limit your app to using a subset of pass type identifiers
  1. In the project editor, click Capabilities and, if necessary, click the Passbook disclosure triangle.

  2. Select “Allow subset of pass types.”

    If there are no pass type identifiers in Member Center, the radio button reverts to “Allow all team pass types.”

  3. If necessary, click the Refresh button under the Pass Types list to display your pass type identifiers.

    ../Art/4_selectpasstypeids_2x.png
  4. Select the pass type identifiers you want to use.

To use a pass type identifier in your app, read “Setting the Pass Type Identifier and Team ID” in Passbook Programming Guide.

Configuring Background Modes for iOS Apps

Enabling background modes allows your app to continue running in the background.

bullet
To enable background modes
  1. In the project navigator, select the project and your target to display the project editor.

  2. Click Capabilities.

  3. If Background Modes isn’t enabled, select the switch in the Background Modes row.

    ../Art/4_enablebackgroundmodes1_2x.png
  4. If a dialog appears asking whether Xcode should request a development certificate on your behalf, click Request.

  5. Optionally, select the supported modes from the checkboxes below.

    ../Art/4_enablebackgroundmodes_2x.png

Xcode adds the background modes to the information property list.

For guidance on selecting background modes, read “App States and Multitasking” in iOS App Programming Guide.

Enabling Inter-App Audio for iOS Apps

Inter-app audio allows your app to export audio that other apps can use.

bullet
To enable inter-app audio
  1. In the project navigator, select the project and your target to display the project editor.

  2. Click Capabilities.

  3. If Inter-App Audio isn’t enabled, select the switch in the Inter-App Audio row.

    ../Art/4_enableinterappaudio_2x.png
  4. If a dialog appears asking whether Xcode should request a development certificate on your behalf, click Request.

Xcode automatically provisions your app to use inter-app audio and adds the Core Audio framework to your project.

Enabling Data Protection for iOS Apps

Data protection adds a level of security to files stored on disk by your app. Data protection uses the built-in encryption hardware present on specific devices to store files in an encrypted format on disk. Your app needs to be provisioned to use data protection.

bullet
To enable data protection
  1. In the project navigator, select the project and your target to display the project editor.

  2. Click Capabilities.

  3. If Data Protection isn’t enabled, select the switch in the Data Protection row.

    ../Art/4_enabledataprotection_2x.png
  4. If a dialog appears asking whether Xcode should request a development certificate on your behalf, click Request.

The default level of protection is complete protection, in which files are encrypted and inaccessible when the device is locked. You can programmatically set the level of protection for files created by your app, as described in “Protecting Data Using On-Disk Encryption” in iOS App Programming Guide.

Configuring Newsstand for iOS Apps

Newsstand enables an app to organize a user’s magazine and newspaper app subscriptions into a folder. To use Newsstand, add some keys to the information property list and add artwork to your Xcode project. For more information on creating a Newsstand app, refer to Newsstand for Developers. For how to add Newsstand cover icons to your Xcode project, read “Newsstand Icons” in iOS Human Interface Guidelines.

Troubleshooting

If there was a problem enabling a technology, an error message appears in that area of the project editor under Steps. After reading the error message, click Fix Issue to repair the problem. If you have a development certificate and for iOS apps, an iOS device chosen from the Scheme pop-up menu, Xcode can create your team provisioning profile for you.

../Art/4_nodevices_2x.png

Recap

In this chapter, you learned how to configure key technologies and services in Xcode and, in some cases, in Member Center and iTunes Connect.