Working with Capabilities
Using App Services to expand iOS app functionality
- PDF for offline use
Let us know how you feel about this
last updated: 2017-03
Adding capabilities to an application often requires additional provisioning setup. This guide explains the setup needed for all capabilities.
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
- Wireless Accessory Configuration
- In-App Purchase
- Inter-App Audio
- Apple Pay
- Push Notification
- Personal VPN
- 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.
This section covers:
- Adding App Services
- Apple Pay
- App Groups
- Next Steps
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 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:
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:
Ensure Automatically manage signing is selected:
Once the app has been created, go to the tab named Capabilities:
Browse to the capability that you wish to add, and move the switch to the ON position.
- This will create a provisioning profile with an App ID that contains the capability and adds the entitlement to the profile.
In Visual Studio for Mac / Visual Studio, browse to Project Options > Bundle Signing and set the provisioning profile to the one that was just created in Xcode:
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
- Browse to the Apple Developer Center on a Mac (the build host mac if using a windows machine) and log in.
Select Certificates, Identifiers, and Profiles:
Under Identifiers, select App IDs:
Press the + button in the top right corner to create a new App ID.
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:
Under App Services select the service or services that are required in your app:
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.
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:
In the Apple Developer Center, browse to Provisioning Profiles > All:
Press the + button in the top right corner to create a new provisioning profile.
Select the type of provisioning profile that you need, and click Continue:
From the dropdown list, select the App ID that was created in the steps above and press Continue:
Select the certificates used to sign the app and press Continue:
Select the devices to be included in this profile and press Continue:
Give the profile a name so that it can be identified and press Continue to generate the profile:
Press the Download button to download it, and double-click on the file in Finder to install the provisioning profile.
In Visual Studio for Mac / Visual Studio, browse to Project Options > Bundle Signing and set the provisioning profile to the one that was just created:
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.
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.
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.
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.