CloudKit JS Tutorial for iOS

Learn how to use CloudKit JS to create a web app to access the database of a CloudKit iOS app, making your app’s data available on the web! By Audrey Tam.

Leave a rating/review
Save for later
Share
Update 9/21/16: Updated for Xcode 8, iOS 10 and Swift 3.

iCloud does a lot of great things. It bridges the gap between iOS and macOS by storing and syncing app data and files so the user can access their stuff from any Apple device.

Notes and Photos are excellent examples of the power of this service — if your content is on one device, it’s reliably on the rest of them within moments. It’s almost magical.

In addition to the obvious use cases, iCloud hosts apps’ public and private databases and handles user authentication.

CloudKit is the framework that affords access to iCloud, providing tons of APIs to make it easier to incorporate iCloud’s magical ways into your creations.

When Apple announced CloudKit in 2014, a lot of developers requested access to their app’s CloudKit data via a web service. Apple listened: in 2015, Apple announced CloudKit Web Services, a JSON/HTTPS interface for CloudKit.

In addition, Apple took it a step further and provided CloudKit JS, which makes it simple to create a web-based interface to access a CloudKit app’s databases. CloudKit JS wraps the REST API in concise code, so you don’t have to compose paths manually or parse JSON.

As you work through this CloudKit JS tutorial, you’ll create a web app to access the database of a CloudKit iOS app. When you’re done, it’ll provide web access to users and even make app data available to non-iOS users!

Prerequisites

You’ll need basic understanding of HTML and JavaScript for this tutorial. For a quick refresher, check out W3Schools.

This CloudKit JS tutorial also assumes you have working knowledge of CloudKit. If you don’t, we suggest starting with our CloudKit Tutorial: Getting Started.

Also nice to have, but not required:

  • Membership in the Apple Developer or Apple Developer Enterprise program.
  • Some familiarity with Knockout.js to create data bindings and Skeleton to layout the web page.

Carry on FTW!  TBH YOLO... and also FOMO

CloudKit JS

CloudKit JS features a similar design to CloudKit iOS, which makes it easier for iOS developers to create CloudKit web apps. Its main features include:

  • Web sign in with Apple ID — your app won’t see usernames and passwords, but you’ll give users the option to be discoverable. When a user opts-in, the app will be given their name. Other users will be able to discover them if they know their email address.
  • Full CRUD (create, read, update, and delete) access to public and private databases.
  • Feature parity with CloudKit iOS, including subscriptions and notifications, using completions via JavaScript promises.

I promise to tell you all about promises soon

Best of all, because CloudKit JS feels familiar to web developers, you can simply give them your container ID, API key and database schema and let them build the web app. ;]

CloudKit JS works on mainstream browsers, including Safari, Firebox, Chrome, Internet Explorer and Microsoft Edge.

In February 2016, Apple announced that CloudKit now supports server-to-server web service requests, enabling reading and writing to CloudKit databases from server-side processes or scripts. You’ll see why this is significant at the end of this tutorial.

Getting Started

As a relative n00b to social media, I often learn new acronyms from people I follow on Twitter.

For instance, TIL means “Today I Learned” — I felt it’s the perfect name for this sample app. It’s a simple premise: users can view and add acronym definitions to a public CloudKit database.

To run the sample CloudKit iOS app, you must be a member of the Apple Developer Program or the Apple Developer Enterprise Program. You won’t be able to run the iOS app if you’re not. :[

However, non-members can still build the web app to access my CloudKit container. You’ll just need to skip certain sections related to CloudKit setup — it’ll be clear what to skip.

If you don’t have a Mac, that’s okay! You don’t need one to build the web app.

Download and unzip TIL Starter. It contains the starter iOS app, web app, and server files.

Setting up CloudKit and the iOS App

Note: This is one of those spots where “Apple Developers” part ways with those who are not. ;]

  • If you’re not an Apple Developer, skip to the Configuring CloudKit JS section — although you won’t play around with the sample config, you’ll see what’s needed from a CloudKit app in order to create its web app.
  • If you are a member, follow the steps below to set up the sample CloudKit iOS app using your own iCloud container.

Open TIL.xcodeproj. Select the TIL project in the project navigator, and then under Targets\TIL\General change the Bundle Identifier and Team to match your information. Tap Fix Issue to get Xcode to create the provisioning profile.

xcode01

In Targets\TIL\Capabilities, toggle iCloud OFF then ON again, and select Key-value storage, CloudKit, and Use default container.

Note: Enabling CloudKit in your app automatically creates a default container to store the app’s databases and user records. However, it only stores your app’s public data. Private data saves directly to users’ iCloud accounts. Fortunately, iCloud automatically handles user registration and creates a unique identifier for each user. You’ll add authentication later in this tutorial.

Tap CloudKit Dashboard to open the CloudKit Dashboard in a browser (use Safari for best results). You can use the dashboard to access, set up and view records online, and manage your CloudKit app.

xcode02

Sign in to the iCloud account that matches the Team you set in Targets\TIL\General. Select the TIL container from the list.

dashboard01

Note: If you don’t see TIL, try refreshing the page. Sometimes CloudKit’s dashboard won’t show new data, but waiting a few seconds and refreshing typically fixes the issue.

Select Schema\Record Types and press + to create a new record type. Name it Acronym and add two fields. Name the first short and the second long. Make sure both fields’ type is set to String. Tap Save.

dashboard02

In Public Data\Default Zone, create two new Acronym records. For the first, set its long value to Today I Learned and short to TIL. For the second, set long to For The Win and short to FTW.

Note: As with the TIL container, you may not see Acronym appear under Default Zone straight away. You might just see NewRecordType until you refresh the page.

dashboard03

Go to the iPhone simulator, open Settings and sign in to iCloud. Build and run the TIL iOS app. Your new records should appear!

TIL Starter App screenshot

In the iOS app, tap the + button and add two items: BTW/By The Way and TBH/To Be Honest.

Back in your browser, change the Sort by order in the CloudKit dashboard’s Default Zone to sort by new items — it’s a little hack that “refreshes” the records in the CloudKit dashboard.

dashboard04