Use a CKSubscription object to track changes occurring on the server.


@interface CKSubscription : NSObject


A subscription acts like a persistent query on the server that can track the creation, deletion, and modification of records. When changes occur, they trigger the delivery of push notifications so that your app can respond appropriately.

Subscription objects do not become active until you save them to the server and the server has time to index them. To save a subscription object, use a CKModifySubscriptionsOperation object or the saveSubscription:completionHandler: method of CKDatabase. To cancel a subscription, delete the corresponding subscription object from the server.

Most of the configuration for subscription objects happens at initialization time. The only other piece of configuration to perform is to specify how to deliver push notifications to the user’s device. Use the notificationInfo property of this object to configure the push notification delivery options. You must save the subscription object to the database before your changes take effect.

Handling the Resulting Push Notifications

When a record modification causes a subscription to fire, the server sends push notifications to all devices with that subscription except for the one that made the original change to the record. For subscription-generated push notifications, the server can add data to the notification payload that indicates the condition that triggered the notification. In the application:didReceiveRemoteNotification:fetchCompletionHandler: method of your app delegate, create a CKNotification object from the provided userInfo dictionary. You can query the CKNotification object for the information relevant to the notification.

In addition to sending a record ID with a push notification, you can ask the server to send a limited amount of data from the record that triggered the notification. In the CKNotificationInfo object you assign to your subscription’s notificationInfo property, you can use the desiredKeys property to specify one or more keys to include in the notification.

Because push notifications have a limited payload size, the server may omit keys and other pieces of data to keep the payload under the maximum limit. If that happens, you can fetch the entire data payload from the server with a CKFetchNotificationChangesOperation object. That operation object returns instances of the CKQueryNotification or CKRecordZoneNotification classes that provide information about the push notifications that were delivered to your app.


Initializing a Query-Based Subscription

- initWithRecordType:predicate:options:

Initializes and returns a query-based subscription that monitors records with the specified options.

- initWithRecordType:predicate:subscriptionID:options:

Initializes and returns a query-based subscription object that monitors records and has a specific name.


Initializing a Zone-Based Subscription

- initWithZoneID:options:

Initializes and returns a subscription object that monitors all records in the specified record zone.

- initWithZoneID:subscriptionID:options:

Initializes and returns a subscription object that monitors the specified zone and has a custom name that you provide.


Accessing the Subscription Search Parameters


The ID of the record zone to monitor.


The record type being monitored in a query-based subscription.


The matching criteria to apply to records.


Specifying the Push Notification Data


The configuration data for push notifications sent by the subscription.

Accessing the Subscription Metadata


The type of behavior provided by the subscription.


The options for triggering notifications.


The unique identifier for the subscription.



Constants that identify a subscription’s behavior.


Configuration options for a subscription.



Inherits From