Enabling CloudKit in Your App

CloudKit is an app service available only to apps distributed through the store. CloudKit requires additional configuration in your Xcode project. Your app must be provisioned and code signed to access CloudKit. To avoid code signing issues, enable CloudKit using the Capabilities pane in Xcode. There should be no need for you to edit entitlements directly in Xcode or your developer account at developer.apple.com/account.

About Containers and Databases

Multiple apps and users have access to iCloud, but data is segregated and encapsulated in partitions called containers. The containers belonging to your app cannot be accessed by apps from another developer. However, your apps can share containers. Multiple apps can share the same container, and one app can use multiple containers. There’s one default container per app, but you can create additional custom containers. The identifier for the default container matches the app’s bundle ID. The other container IDs you specify need to be unique across all developer accounts.

../Art/containers_2x.png

An app has access to both a public and private database in each container. The public database is for storing user and app data that is shared between all instances of the app. By default, all users can read the public database, but they need to enter iCloud credentials to write to the public database. There’s a private database for each user of your app, but the app only has access to the private database of the current user. The user has to enter iCloud credentials for the app to read and write to the private database.

../Art/databases_2x.png

Setup

To perform all the steps in this document, you need:

Verify that you have performed these tasks before you begin using CloudKit. For step-by-step instructions, read App Distribution Quick Start.

Task

../Art/checkbox_checked_2x.png

Join the Apple Developer Program or Apple Developer Enterprise Program.

../Art/checkbox_checked_2x.png

Create an Xcode project that builds and runs.

../Art/checkbox_checked_2x.png

Add your Apple ID to Accounts preferences.

../Art/checkbox_checked_2x.png

Create your team provisioning profile:

  • 1. For Mac apps, choose Mac App Store as the signing identity.

  • 2. Select your team from the Team pop-up menu.

  • 3. Click Fix Issue.

../Art/checkbox_checked_2x.png

For Mac apps, enable App Sandbox in the Capabilities pane.

If you successfully complete the preceding tasks, the error message and Fix Issue button below the Team pop-up menu in the General pane disappears. The screenshot below shows the General pane for an iOS app when the code signing assets are successfully created.

../Art/2_create_teamprofile_2x.png

For complete steps on creating a team provisioning profile, read App Distribution Quick Start. To troubleshoot code signing and provisioning, read Troubleshooting in App Distribution Guide.

Enable iCloud and Select CloudKit

CloudKit is one of three app services provided by iCloud. The other iCloud app services—key-value storage and iCloud documents—also appear in the iCloud settings in Xcode. To use CloudKit, you first enable iCloud and then select the CloudKit service.

To enable iCloud and select CloudKit

  1. In the Capabilities pane, select the switch in the iCloud row.

    Xcode provisions your app to use iCloud. (Key-value storage is enabled by default.)

  2. Select the CloudKit checkbox.

    Xcode creates a default CloudKit container based on the bundle ID and adds the CloudKit framework to your project.

    ../Art/2_enable_cloudkit.shot/Resources/shot_2x.png../Art/2_enable_cloudkit.shot/Resources/shot_2x.png

Your app can now store data and documents in iCloud.

Access CloudKit Dashboard

Use CloudKit Dashboard to manage your CloudKit container schema and records. The schema describes the organization of records, fields, and relationships in a database. A record is an instance of a record type. In a relational database, a record type corresponds to a table and a record corresponds to a row in a table.

To sign in to CloudKit Dashboard

  1. In the iCloud settings in the Capabilities pane, click CloudKit Dashboard.

    Alternatively, go to https://icloud.developer.apple.com/dashboard.

  2. If necessary, enter your Apple ID credentials and click Sign In.

    All the containers for all the teams you belong to appear in the container pop-up menu in the upper-left corner of the window. The assets for the selected container (named Gallery in the screenshot) are displayed.

    ../Art/2_cloudkit_dashboard_home.shot/Resources/shot_2x.png../Art/2_cloudkit_dashboard_home.shot/Resources/shot_2x.png

To sign out, choose Sign Out from the account pop-up menu in the upper-right corner of the window.

Share Containers Between Apps

Optionally, configure your app to use multiple containers or share a container with other apps. For example, you might use one app internally to create record types and records programmatically to return a database to a known state. This app needs to share the same container as the end-user app you are developing and testing. To do this, you enable the first app to use the default container of the second app or create a custom container that both apps share. Apps running on different platforms (iOS, Mac, and tvOS) can also be configured to share the same containers.

Add Containers to an App

Select an existing container ID used by another app or create a new one.

To add a container to an app

  1. In the Capabilities pane under the iCloud settings, select “Specify custom containers.”

    When you previously selected the CloudKit service, Xcode created a default container ID for your app that matches the bundle ID. A checkmark appears next to the default container ID.

    ../Art/3_specifycontainers1_2x.png
  2. If necessary, click the Refresh button below the Containers table to download containers from your developer account that are used by other apps.

  3. In the row of the container ID you want to add, select the checkbox.

    Xcode updates the list of container IDs in the entitlements file.

    The screenshot below shows the Curator app sharing the Gallery app’s default container.

    ../Art/3_specifycontainers2.shot/Resources/shot_2x.png../Art/3_specifycontainers2.shot/Resources/shot_2x.png

Create Custom Containers

Alternatively, create a custom container shared by multiple apps.

To create a custom container

  1. If "Use default container” is selected, select “Specify custom containers.”

  2. Click the Add button (+) at the bottom of the table.

  3. In the dialog that appears, enter an identifier for the container you want to add.

    A container ID begins with iCloud. followed by a string in reverse DNS notation.

    ../Art/3_addicloudcontainerdialog_2x.png
  4. Click OK.

    Xcode adds the new container ID to the Xcode project entitlements file and to your developer account

If you want to share the new container ID with another app, add the container to the app, as described in Add Containers to an App.

Verify Your Steps

You can view all the container IDs for your team in the Capabilities pane in Xcode or your developer account. In your developer account, you can also add containers and edit the name of containers.

To view container IDs in your developer account

  1. Go to Certificates, Identifiers & Profiles and for Mac apps, choose OS X from the pop-up menu on the left.

  2. Under Identifiers, select iCloud Containers.

  3. Optionally, in the upper right corner, click the search button and enter text in the search field.

    ../Art/3_viewing_membercenter_containers.shot/Resources/shot_2x.png../Art/3_viewing_membercenter_containers.shot/Resources/shot_2x.png

Create an iCloud Account for Development

You’ll need an iCloud account to save records to a CloudKit container. You’ll enter the credentials for this iCloud account on the device that you run your app. If you don’t have an iCloud account, create one that you can use during development. On your Mac, launch System Preferences and click iCloud. Click Create Apple ID under the Apple ID text field and follow the instructions.

../Art/2_create_icloud_account_2x.png../Art/2_create_icloud_account_2x.png

Recap

In this chapter, you learned how to: