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 through the developer center, including any additional setup that may be required. More information on each framework is linked from each section.

Contents

This section covers:

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 either 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 adjoining guides.

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.

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.