Working with Capabilities

Using App Services to expand iOS app functionality

PDF for offline use

Let us know how you feel about this

Translation Quality


0/250

last updated: 2017-03

Adding capabilities to an application often requires additional provisioning setup. This guide explains the setup needed for all capabilities.

Overview

Apple provides developers with capabilities, often known as app services, as a means of extending functionality and widening the scope of what iOS apps can do. The capabilities allow developers to add a deeper integration of platform features to their application, such as: the ability to have monetary transactions initiated from the app, additional device services such as Siri, and more. These capabilities can be used with Xamarin.iOS projects. The full list of services is described below:

  • App Groups
  • Associated Domains
  • Data Protection
  • Game Center
  • HealthKit
  • HomeKit
  • Wireless Accessory Configuration
  • iCloud
  • In-App Purchase
  • Inter-App Audio
  • Apple Pay
  • Wallet
  • Push Notification
  • Personal VPN
  • Siri
  • Maps
  • Background Modes
  • Keychain Sharing

Capabilities can be enabled either through Xcode or manually in the Apple Developer Portal. Certain capabilities such as Wallet, Apple Pay, and iCloud require additional configuration of the App IDs.

This guide explains how to enable each of these App Services in your application in both Xcode and manually, including any additional setup that may be required. More information on each framework is linked from each section.

Contents

This guide introduces the following:

Adding App Services

To use capabilities, the app must have a valid provisioning profile that contains an App ID with the correct service enabled. Creating this provisioning profile can either be done automatically in Xcode or manually in the Apple Developer Center. This section explains how to use Xcode or the Developer Center to enable most capabilities. There are some capabilities such as Wallet, iCloud, Apple Pay, and App Groups that require additional setup. These are explained in detail in the sections later in this guide.

Xcode

Xcode 8 introduced a simplified way to add the elements required to work with capabilities. Xamarin developers can use Xcode to quickly create a provisioning profile with a suitable App ID. This process, described below, can be used for any app service in the list:

  1. Open Xcode and create a ‘dummy’ project. Give the dummy project the same name as your Xamarin.iOS project. The bundle identifier should be identical to the bundle identifier of your Xamarin.iOS project:

    Xcode Create Project

  2. Ensure Automatically manage signing is selected:

    Automatically manage signing selection

  3. Once the app has been created, go to the tab named Capabilities:

    Xcode Capabilities tab

  4. Browse to the capability that you wish to add, and move the switch to the ON position.

  5. This will create a provisioning profile with an App ID that contains the capability and adds the entitlement to the profile.
  6. In Xamarin Studio / Visual Studio, browse to Project Options > Bundle Signing and set the provisioning profile to the one that was just created in Xcode:

    Xamarin Studio Project Options

Developer Center

Using the developer center is a two step process that requires creating an App ID and then using that App ID to create a provisioning profile. These steps are detailed below.

Creating an App ID with an app service

  1. Browse to the Apple Developer Center on a Mac (the build host mac if using a windows machine) and log in.
  2. Select Certificates, Identifiers, and Profiles:

    Apple Developer Center

  3. Under Identifiers, select App IDs:

    App ID selection in Developer Center

  4. Press the + button in the top right corner to create a new App ID.

  5. Enter an App ID description, select Explicit App ID, and enter a bundle ID in the format com.domain.appname. This bundle ID should match the bundle ID in your project:

    Adding App ID details

  6. Under App Services select the service or services that are required in your app:

    App Services selection page

  7. Press Continue.

  8. Confirm your App ID. Each service will be in one of the following states: Enabled, Disabled, or Configurable, as illustrated below. If it’s Enabled, it is ready to be used in a provisioning profile. If it is Configurable, additional setup is required for this capability. These additional steps are described in more detail in later sections.

    App ID confirmation

  9. Click Register and then Done. The newly created App ID should display in the iOS App IDs list.

Creating a Provisioning Profile

Now create a provisioning profile that contains this App ID. Follow the steps below:

  1. In the Apple Developer Center, browse to Provisioning Profiles > All:

    Provisioning Profile section

  2. Press the + button in the top right corner to create a new provisioning profile.

  3. Select the type of provisioning profile that you need, and click Continue:

    Provisioning Profile selection

  4. From the dropdown list, select the App ID that was created in the steps above and press Continue:

    App ID selection

  5. Select the certificates used to sign the app and press Continue:

    Certificate selection

  6. Select the devices to be included in this profile and press Continue:

    Select devices for Provisioning Profile

  7. Give the profile a name so that it can be identified and press Continue to generate the profile:

    Name provisioning Profile

  8. Press the Download button to download it, and double-click on the file in Finder to install the provisioning profile.

  9. In Xamarin Studio / Visual Studio, browse to Project Options > Bundle Signing and set the provisioning profile to the one that was just created:

    Xamarin Studio Project Options

⚠️

Note: You may also need to set entitlement keys in the Entitlement.plist file and privacy keys in the Info.plist file. More information on these entitlements is provided in the Working with Entitlements guide.

Wallet

Wallet is an app that stores and displays barcodes and other content allowing users to display tickets, boarding passes, and coupons right from their device. This information is stored on a pass. For example, a boarding pass or a single ticket would be a singular pass.

Developers can work with Wallet in a variety of ways:

  • To create a pass, an application does not need to be built. A Passfile is a zipped archive that contains some JSON files and optional metadata files. To prepare this, a Pass Type ID and a Pass certificate is required. This information is then declared in a JSON file. More information on provisioning a Passfile can be found in the Introduction to PassKit guide.

  • Companion Apps are written to distribute passes. They also have the functionality to create, edit, and update passes and then to add them to the Wallet app. A good example of this kind of app would be a cinema app – once a user purchases a ticket through the app, that ticket can be added directly from the app to Wallet. To use a companion app, your provisioning profile must include an App ID with the Wallet features, which can be set either as described in the Xcode section above, or in the steps below. Your app must also include the required entitlements.

  • Conduit Apps are apps which do not manipulate passes directly. They have minimum interaction with the pass beyond receiving it and giving the user the option of adding them to Wallet. These apps do not need any special provisioning or entitlements, but will use some methods from the PassKit Framework.

Developer Center

To create a new provisioning profile for use with Wallet, do the following:

  1. Browse to the Certificates, Identifiers, and Profiles section of the Apple Developer Portal.
  2. Under Identifiers, browse to App IDs:

    App ID selection

  3. Click the + icon in the top right of the page.

  4. Register a new App ID by giving it a Name and a bundle identifier. (Note that this bundle identifier must match the bundle ID in your project):

    Add App ID details

  5. Select the Wallet App Service from the list of services:

    Select service screen

  6. Press Continue, and then Register to create the App ID.

If required, existing App IDs can be edited to add the Wallet capability.

Once the App has been created, you must create, or regenerate, a new provisioning profile with the App ID that contains the necessary capabilities:

Using newly created App ID to create provisioning profile

For more information on using Wallet refer to the following guides:

iCloud

iCloud provides iOS users with a convenient and simple way to store their content and share it between devices. There are four ways that developers can use iCloud to provide a means of storage for their users: Key-Value storage, UIDocument Storage, CoreData, and using CloudKit directly to provide storage for Individual files and directories. For more information on these, refer to the Introduction to iCloud guide.

Adding the iCloud capability to an application is slightly more difficult than other App Services because of containers. Containers are used in iCloud to store information for an app, and allow all information contained in a single iCloud account to be segregated – like the sandboxing on a user’s iOS device. For more information on containers, refer to the Introduction to CloudKit guide.

Xcode

The steps in section Adding App Services above can be used to toggle the required iCloud capability. Depending on which means of storage is being used in your app, you may need to do additional setup. The image below shows the iCloud capabilities pane:

iCloud Capability section

First select the required service. If iCloud Documents or CloudKit have been selected, you must select a container. Selecting the default container will create a new container that is unique to the app. Alternatively, if you have created a container either via Xcode or the developer portal, select it here.

Developer Center

When provisioning a new app through the developer center there are two steps that need to be taken:

  1. Create a container.
  2. Create an App ID with the iCloud capability and add the container to it.
  3. Create a Provisioning profile that includes this App ID

The steps below will guide you through these steps:

  1. Browse to the Apple Developer Center and go to the Certificates, Identifier, and Profiles section:

    Apple Developer Center main page

  2. Under Identifiers select iCloud Containers, and then select the + to create a new container:

    iCloud Container screen

  3. Enter a Description and a unique Identifier for the iCloud container:

    iCloud container registration screen

  4. Press Continue, ensure that the information is correct, and press Register to create the iCloud Container:

    iCloud container registration screen

To create a new App ID and add a container to it, do the following:

  1. In the Developer Center, click on App IDs under Identifiers:

    Identifier Section in Developer Center

  2. Select the + button to add a new App ID:

    Add new App ID button

  3. Enter a Name for the App ID and give it an Explicit App ID:

    Enter new App ID details

  4. Under App Services select iCloud and choose Include CloudKit support:

    Select iCloud app services

  5. Select Continue and then Register. Note that on the confirmation screen, iCloud will display with Configurable selected, with a yellow symbol:

    Confirmation screen

  6. Return to the list of App IDs and select the one that you have just created:

    Select App ID screen

  7. Scroll down to the bottom of this expanded section and click Edit:

    Edit App ID

  8. Scroll down the list to iCloud and click the Edit button:

    Edit iCloud App ID

  9. Select the Container to use with this App ID:

    Select container screen

  10. Confirm the Container assignments, and press Assign.

This App ID can now be used to generate, or to re-generate, a new provisioning profile.

For more information on using iCloud, refer to the following guides:

Apple Pay

Apple Pay enables users to pay for physical goods via their iOS device. This section describes how to create all necessary components required for Apple pay in the Apple Developer Center.

Developer Center

When provisioning a new app through the developer center, there are three steps that need to be taken:

  1. Create a Merchant ID.
  2. Create an App ID with the Apply Pay capability and add the merchant to it.
  3. Generate a certificate for the Merchant ID.

The steps below will guide you through creating the above items:

Create Merchant ID

A Merchant ID is used to let Apple Pay know that you can accept payments, and is passed to PassKit’s PaymentRequest method and used in the Apple Pay entitlement:

  1. Browse to the Apple Developer Center and go to the Certificates, Identifier, and Profiles section:

    Developer Center Merchant ID selection

  2. Under Identifiers, select Merchant IDs, and then select the + to create a new merchant ID:

  3. Fill out the form, illustrated below, with a new description and identifier. The description makes the ID identifiable to you and can be changed later. The identifier must be unique to you, and it must start with the string merchant. Apple recommends that the identifier be in the following format: merchant.com.[Your-App-Name]:

    New Merchant ID details

  4. Confirm the details, and Register your ID: 

    Merchant ID confirmation

Create an App ID with the Apple Pay capability that includes the Merchant ID

  1. In the Developer Center click on App IDs under Identifiers:

    Select App ID in Developer Center

  2. Select the + button to add a new App ID:

    Add new App ID button

  3. Enter a Name for the App ID and give it an Explicit App ID:

    App ID details screen

  4. Under App Services, select Apple Pay:

    App Services Apple Pay

  5. Select Continue and then Register. Note that on the confirmation screen Apple Pay will display with Configurable selected, with a yellow symbol:

    Confirmation Screen for Apple Pay

  6. Return to the list of App IDs and select the one you have just created:

    Edit App ID

  7. Scroll down to the bottom of this expanded section and click Edit.

  8. Scroll down the list to Apple Pay and click the Edit button:

    Edit Apple Pay App ID details

  9. Select the Merchant ID to use with this App ID, and click Continue:

    Select Merchant ID to use for App ID

  10. Confirm the Merchant ID assignments, and press Assign:

    Confirmation Screen

This App ID can now be used to generate, or re-generate, a new provisioning profile.

Create a Certificate for your Merchant ID

A certificate is required by Apple to encrypt sensitive data associated with the transaction. Each Merchant ID created must have its own certificate.

To create a certificate, follow the steps below:

  1. Select the Merchant ID that was created above and press Edit:

    Edit Merchant ID dialog

  2. On the iOS Merchant ID Settings screen, click Create Certificate:

    Create payment processing certificate

  3. Answer the following question:

    address if payments will be processed exclusively in China

  4. At this point you will be prompted to create a certificate signing request:

    Creating a certificate signing request

    ⚠️

    If you are using a payment provider for Apple Pay, such a JudoPay or Stripe, they can provide you with a properly formatted CSR that you can use at this point. Information on requesting this is found on the JudoPay and Stripe sites. To create your own CSR, follow the steps 5-8 below. Once you have a CSR go to step 9.

  5. Open the Keychain Access application, and browse to Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority:

    Create a CSR using keychain on a Mac

  6. Enter your email address, enter a name for the private key, leave CA Email Address empty, select the Save to Disk option, and select Let me specify key pair information:

    Certificate information dialog

  7. Save the CSR to a convenient location:

    Saving CSR to local machine

  8. In the Key Pair information screen, set Key Size to 256 bits and Algorithm to ECC and click Continue:

    Enter key pair information dialog

  9. On the Developer Center, click Continue to upload the CSR:

    Prepare to upload CSR to developer center

  10. Click Choose File… to select the CSR and press Continue to upload it to the developer portal:

    Upload CSR to developer center

  11. Once the certificate has been generated, download it and double click on it to install it to your keychain.

For more information on using Apple Pay, refer to the following guide:

App Groups

An App Group allows different applications (or an application and its extensions) to access a shared file storage location. App Groups can be used for data like:

Configure an new App Group

The shared location is configured using an App Group, which is configured in the Certificates, Identifiers & Profiles section on Apple Developer Center. This value must also be referenced in each project's Entitlements.plist.

The app group will have an identifier, which is typically the Bundle ID with a group. prefix. For example, the Bundle ID com.xamarin.WatchSettings would have the app group group.com.xamarin.WatchSettings.

To create a new App Group, do the following:

  1. Visit Apple's iOS Developer Center, open your Account and log in.
  2. Select Certificates, IDs & Profiles.
  3. Under Identifiers select App Groups and click the + button to create a new group.
  4. Enter a Name and an Identifier for the new group and click the Continue button:

    Add App Group details

  5. Click the Register button to create the group and the Done to return to the list of registered App Groups.

Configure an App to use App Groups

With the App Group created, configure the App IDs so that the apps can use it.

Do the following:

  1. Visit Apple's iOS Developer Center, and log in with an Apple Developer Account.
  2. From the Program Resources menu, select Certificates, IDs & Profiles.
  3. Under Identifiers select App IDs and click the + button to create a new ID.
  4. Enter a Name for the App ID and give it an Explicit App ID.
  5. Under App Services enable App Groups, then click the Continue button:

    Add App Group App Services

  6. Verify the settings and click the Register button to create the App ID.

  7. Click the Done button to return to the list of registered App IDs.
  8. Select the newly created App ID from the list and click the Edit button:

    Select App ID from list

  9. Under Service App Group, click the Edit button:

    Select App ID from list

  10. Select the App Group that was created above and click the Continue button:

    Add App Group

  11. Click the Assign button, then the Done button to return to the list of registered App IDs.

  12. Repeat these steps for any Apps (or Extensions) that will be using the App Group.

Next Steps

Once a Capability has been enabled on the server side, there is still work that needs to be done to allow your app to use the functionality. The list below describes additional steps that may need to be taken:

  • Use the framework namespace in your app.
  • Add the required entitlements to your App. Information on the entitlements required and how to add them is detailed in the Introduction to Entitlements guide.

Troubleshooting Capabilities

The list below details some of the most common issues that can create roadblocks when developing an app with an app service enabled.

  • Ensure that the correct ID has been properly created and registered in the Certificates, IDs & Profiles section of Apple's Developer Portal.
  • Ensure that the Service have been added to the App's (or Extension's) ID and that the service is configured to use the App Group/Merchant ID/Container created above in the Certificates, IDs & Profiles of Apple's Developer Portal.
  • Ensure that the Provisioning Profiles and App IDs have been installed and that the App's Info.plist (in the Xamarin Project) is using one of the App IDs configured above.
  • Ensure that the App's Entitlements.plist file (in the Xamarin Project) has the correct service enabled.
  • Ensure that the appropriate privacy-keys are set in info.plist
  • In the App's Build Settings, ensure that the Entitlements.plist file is included in the App's Bundle. Note: This is not the default setting for Debug and iOS Simulator builds.

Summary

This guide explained Capabilities, or app services, and described how they can be enabled in Xcode and in the Apple Developer Center. It also detailed how to set up more complicated services such as Wallet, iCloud, Apple Pay, and App Groups. Finally, it covered the next steps for getting set up and simple troubleshooting options.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.