Class: Container

.setUpAuth()

This sample demonstrates how to authenticate a user with your app. There are two steps to authentication:

1. Setting up auth. This step checks whether a user is signed in. If you have specified auth.persist = true in your configuration you could run setUpAuth while bootstrapping your app and this function will use the stored cookie. The promise resolves with a userInfo object or null and a sign-in or sign-out button will have been appended to the button container with id apple-sign-in-button or apple-sign-out-button (whichever is appropriate). These containers need to be in the DOM before executing the function and their IDs can be customized in CloudKit.configure.
2. Binding handlers to the rendered button. The promises whenUserSignsIn and whenUserSignsOut are resolved when the user signs-in/out respectively. The former resolves with a userInfo object.

Class: Container

.fetchCurrentUserIdentity()

This sample demonstrates how to fetch the currently signed-in user’s userIdentity object. If the current user has made himself discoverable to the app, this object will have nonempty nameComponents.

Class: Container

.discoverAllContactUserInfos()

This sample demonstrates how to obtain a list of userInfo objects corresponding to users of the app in the signed-in user’s iCloud Contacts who have made themselves discoverable to the app.

Class: Container

.discoverUserInfoWithEmailAddress()

This sample demonstrates how to look up a discoverable user’s name by email address. This method will always return a userInfo object with the emailAddress field populated. The other fields will be populated only if a matching discoverable user is found.

Class: Container

.discoverUserInfoWithUserRecordName()

This sample demonstrates how to look up a discoverable user’s info by userRecordName. The .catch() block is invoked when no matching user is found.

Page Not Found

The page you were looking for was not found. Please use the menu on the left to navigate the app.

Class: Container

.registerForNotifications()

This sample shows how to add a notification listener to the container. The listener will get called whenever the server sends us a notification of an update to a subscription. In order to receive notifications your app must park a connection with the notification backend using registerForNotifications.

Class: Database

.saveRecords()

This sample demonstrates how an authenticated user can save a record to his/her private database. Our example records are of type Items. Leave the recordName field blank to let the server generate a record name. Leave the recordChangeTag field blank when creating a new record and supply the latest server change tag when modifying an existing record.

Class: Database

.deleteRecords()

This sample demonstrates how an authenticated user can delete a record from the private database.

Class: Database

.fetchRecords()

This sample demonstrates how to fetch a record by record name from the private database.

Class: Database

.saveSubscription()

This sample demonstrates how a user can subscribe to a change to a record in a specific zone (zone subscription) as well as to changes to records that match a query condition (query subscription). Once subscribed, your app can register for notifications of changes.

Class: Database

.deleteSubscription()

This sample shows how to delete a subscription by ID.

Class: Database

.fetchSubscription()

This sample shows how to fetch a subscription by ID.

Class: Database

.fetchAllSubscriptions()

This sample shows how to fetch all subscriptions.

Class: Database

.fetchChangedRecords()

This sample demonstrates how an authenticated user can get all changes relative to a sync token in a custom zone. If no sync token is provided all records in the zone are returned. The response will always contain a new sync token which can be cached in the client and sent in a new sync request. The sync token can also be used for paginating a result set. The moreComing boolean on the response indicates if the result set is incomplete.

When you have a zone-level subscription you can get notified of changes to that zone and you would typically run fetchChangedRecords to then fetch the latest changes and bring your client up-to-date.

Class: Database

.saveRecordZone()

This sample shows how to create a custom zone in the user’s private database. Zones are useful for syncing a user’s data. Once you have created a custom zone you will be able to create records in that zone and test the sync feature.

Class: Database

.deleteRecordZone()

This sample shows how to delete a custom zone by name from the private database.

Class: Database

.fetchRecordZone()

This sample shows how to fetch a record zone by name from the private database.

Class: Database

.fetchAllRecordZones()

This sample shows how to list all record zones in your private database. The response will always contain the default zone.

Class: Database

.performQuery()

This sample demonstrates how any user can query records in the public database. The same example will work equally well for querying records in a user’s private database. We will query records of type Items which has the following schema:

• name : String
• location : Location
• asset : Asset

Our code sample gets the client’s geolocation and asks for a list of Items sorted by closest distance from this location.

Getting started with CloudKit JS V2

This web application provides executable sample code for the core API methods provided by the CloudKit JS JavaScript library. While these methods cover many typical use cases, there are more flexible versions available if needed which allow for batch requests and more configuration. The user is advised to refer to the CloudKit JS Reference for more information.

All code examples can be run by clicking the play button at the top of the page. The results will be displayed below the sample code block.

Downloading and running CloudKit Catalog

The static assets which make up this tutorial are available for download as a convenient zip package from the Github. The configuration code resides in the file js/init.js.

CloudKit.configure({
                    containers: [{

                    // Change this to a container identifier you own.
                    containerIdentifier: 'iCloud.io.startway.CloudKitCatalog',

                    apiTokenAuth: {
                        // And generate a web token through CloudKit Dashboard.
                        apiToken: '<Insert your API Token here>',

                        persist: true, // Sets a cookie.
                        
                        signInButton: {
                        id: 'apple-sign-in-button',
                        theme: 'black' // Other options: 'white', 'white-with-outline'.
                        },

                        signOutButton: {
                        id: 'apple-sign-out-button',
                        theme: 'black'
                        }
                    },

                    environment: 'development'
                    }]
                });

Change the container identifier to one that you own. For more information on how to create a container see CloudKit Quick Start. Once you have a container, you will need to create an Items record type with fields:

• name : String
• location : Location
• asset : Asset

You can do this as well as generate an API token through the CloudKit Dashboard.

Obtaining the CloudKit JS library

CloudKit JS is hosted at https://cdn.apple-cloudkit.com/ck/2/cloudkit.js. Include the library on your web page using either of the two methods below. You will automatically get updates and bug fixes as they are released.

Option #1 - Load CloudKit JS synchronously

<script src="https://cdn.apple-cloudkit.com/ck/2/cloudkit.js"></script>

Option #2 - Load CloudKit JS asynchronously

<!-- Listen for the cloudkitloaded event on the window object. -->
<script>
    window.addEventListener('cloudkitloaded', function() {
        // Now the global namespace CloudKit is defined and you can proceed
        // to configure your application.
    });
</script>

<!-- Include the script with the ‘async’ attribute. -->
<script src="https://cdn.apple-cloudkit.com/ck/2/cloudkit.js" async></script>

Browser support

CloudKit JS is supported on Safari, Firefox, Chrome, Internet Explorer and Microsoft Edge, including embedded web views. For security reasons, a mobile web view must launch the Apple sign-in page in a native browser in order to use iCloud authentication.