CloudKit Namespace

Classes

Interfaces

Enums

Delegates

Remarks

The CloudKit namespace allows application developers to control the flow of data between their applications and iCloud. iCloud provides server-side data storage, both "public" that is shared between all instances of an application or specific applications and "private" that is unique to a single user. iCloud storage and transport is encrypted and synchronized between Apple devices. CloudKit does not provide client-side persistence or data caching -- CloudKit functionality is only available while the user has an active Internet connection.

The highest-level class in the CloudKit is CKContainer. A CloudKit Container (sometimes referred to in Apple documentation as a "Ubiquity container") is an information store identified with a particular name. Apple advises using a name of the form "iCloud.{reverse DNS}.{appName}", for instance, "iCloud.com.mycompany.MyApp". Developers must create and configure their containers using the iCloud Dashboard, available by way of the Apple developer portal.

A single CKContainer may contain both public data, which is shared between all instances of the app (see PublicCloudDatabase), and private data, which contains user-specific data (see PrivateCloudDatabase). Within iCloud, public data is stored in the app's iCloud storage while private data is stored in the user's private iCloud storage. The public CKDatabase is available to all connected users of the app, whether or not they are logged in to iCloud. The private CKDatabase is only available if the user is logged in to iCloud. Developers must write their code such that it reacts gracefully to changes in the user's login or connection status.

These public and private CKDatabase objects store structured records. These are represented by CKRecord objects. In addition to field-like key-value data, these records may hold CKAsset large objects either directly (retrieved with the containing CKRecord) or as references (allowing lazy retrieval of the large data).

All CKRecord instances are stored within a CKRecordZone. A CKRecordZone is something like a traditional database instance: it can contain multiple CKRecord stores that may refer to each other but not to stores in other CKRecordZone instances and CKRecordZone objects can be used to coordinate atomic operations across multiple CKRecord stores. The similarity to a database instance is not universal; for instance, a developer may use FetchRecordAsync to retrieve a CKRecord directly from the CKDatabase without referring to the zone. The default CKRecordZone is available via DefaultRecordZone. Developers may create additional zones using the CloudKit dashboard and use them to partition their data logically.

CloudKit apps require a provisioning profile with the com.apple.developer.icloud-services entitlement and an app-specific Bundle Identifier (e.g., "com.mycompany.CloudKitApp"). Developers must create and configure such a provisioning profile.

The following demonstrates some typical uses of CloudKit that work on single records:

//Create
private async Task<CKRecord> StoreInCloudKit (string name, CLLocation loc, int stationId)
{
    string containerName = "iCloud.com.example.CKWork";
    var container = CKContainer.FromIdentifier (containerName);
    CKDatabase publicDatabase = container.PublicCloudDatabase;
    var zoneId = CKRecordZone.DefaultRecordZone ().ZoneId;
    var recordType = "StationReferences";

    var record = new CKRecord (recordType);
    record ["Name"] = new NSString (name);
    record ["Position"] = loc;
    record ["StationID"] = new NSNumber (stationId);

    var storedRecord = await publicDatabase.SaveRecordAsync (record);
    return storedRecord;
}

//Retrieve (via ID)
private async Task<CKRecord> AccessCloudKit ()
{
    string containerName = "iCloud.com.example.CKWork";
    var container = CKContainer.FromIdentifier (containerName);
    CKDatabase publicDatabase = container.PublicCloudDatabase;

    var recordNameIHappenToKnow = "7eaf0432-2fa4-475f-851a-c6a19b3f8587";
    var recordId = new CKRecordID (recordNameIHappenToKnow);
    var record = await publicDatabase.FetchRecordAsync (recordId);

    return record;
}

//Retrieve (query)
private async Task<CKRecord []> QueryCloudKit ()
{
    string containerName = "iCloud.com.example.CKWork";
    var container = CKContainer.FromIdentifier (containerName);
    CKDatabase publicDatabase = container.PublicCloudDatabase;

    var zoneId = CKRecordZone.DefaultRecordZone ().ZoneId;
    Console.WriteLine ($"Default zone name = '{zoneId.ZoneName}' owner = '{zoneId.OwnerName}'");
    /*
    var zoneName = "_defaultZone";
    var ownerName = "__defaultOwner__";
    var zoneId0 = new CKRecordZoneID (zoneName, ownerName);

    Console.WriteLine ($"Assert { zoneId0 == zoneId }");
    */

    var recordType = "StationReferences";

    var location = new CLLocation (19.7303, -155.056);
    var predicate = NSPredicate.FromFormat ("distanceToLocation:fromLocation:(Position, %@) < 100", location);

    var query = new CKQuery (recordType, predicate);

    var result = await publicDatabase.PerformQueryAsync (query, zoneId);
    return result;
}

//Update
private async Task<CKRecord> UpdateInCloudKit (CKDatabase database, CKRecord record, NSString key, NSObject newValue)
{
    record [key] = newValue;
    var modifiedRecord = await database.SaveRecordAsync (record);
    return modifiedRecord;
}

//Delete
private async Task<CKRecordID> DeleteRecord (CKDatabase database, CKRecord record)
{
    var id = record.Id;
    var deletedId = await database.DeleteRecordAsync (id);
    return deletedId;
}