Use a CKSubscription
object to track changes occurring on the server.
SDKs
- iOS 8.0+
- macOS 10.10+
- Mac Catalyst 13.0+
- tvOS 9.0+
- watchOS 3.0+
Framework
- Cloud
Kit
Declaration
@interface CKSubscription : NSObject
Overview
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 CKModify
object or the save
method of CKDatabase
. To cancel a subscription, delete the corresponding subscription object from the server.
Note
You don’t need to enable push notifications for the app’s explicit App ID in your developer account at developer.apple.com to receive subscription notifications. Xcode automatically adds the APNs entitlement to your entitlement file when you enable CloudKit. To learn about enabling CloudKit, read Enabling CloudKit in Your App.
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 notification
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.
Note
Subscriptions must be created in the Development environment first and then promoted to Production. Attempting to create a subscription directly in the Production environment will result in an error.
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:
method of your app delegate, create a CKNotification
object from the provided user
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 CKNotification
object you assign to your subscription’s notification
property, you can use the desired
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 CKFetch
object. That operation object returns instances of the CKQuery
or CKRecord
classes that provide information about the push notifications that were delivered to your app.