An object that manages the sync engine's state.
To reliably and consistently sync your app's data, a sync engine keeps a record of several important pieces of data, such as server changes tokens (for databases and record zones), subscription identifiers, the most recent ``CKUserIdentity/userRecordID``, and so on.
This class automatically manages that state on behalf of your app, but there are certain elements you can modify.
For example, you control the list of pending changes to send to the iCloud servers and manipulate that list using the ``add(pendingDatabaseChanges:)`` and ``add(pendingRecordZoneChanges:)`` methods.
If there aren't any scheduled sync operations when you invoke these methods, the engine automatically schedules one.
An engine's state changes periodically and, when it does, the sync engine dispatches a ``CKSyncEngine-5sie5/Event/stateUpdate(_:)`` event to your delegate.
The event contains an instance of ``Serialization`` and, on receipt of such an event, it's your responsibility to persist the serialized state to disk so that it's available across app launches.
On the next initialization of the sync engine, you provide the most recently persisted state as part of the engine's configuration. For more information, see ``CKSyncEngine-5sie5/Configuration/init(database:stateSerialization:delegate:)``.
Members (9)
get · iOS 17.0+
pendingDatabaseChanges
TypeScript
get pendingDatabaseChanges(): Array<CKSyncEngine_PendingDatabaseChange>
Swift declaration
final var pendingDatabaseChanges: [CKSyncEngine.PendingDatabaseChange] { get }
A list of database changes that the sync engine has yet to send to the iCloud servers.
This array contains any pending database changes to send to the iCloud servers.
After the sync engine sends those changes, your app's sync delegate receives an event of type ``CKSyncEngine-5sie5/Event/SentDatabaseChanges``.
The sync engine keeps this list up-to-date while sending changes to the server.
For example, when it successfully saves a zone, it will remove that change from this list.
If it fails to send a change due to some retryable error (e.g. a network failure), it will keep that change in this list.
Use the ``CKSyncEngine-5sie5/State/add(pendingDatabaseChanges:)`` and ``CKSyncEngine-5sie5/State/remove(pendingDatabaseChanges:)`` methods to modify the array's contents.
get · iOS 17.0+
pendingRecordZoneChanges
TypeScript
get pendingRecordZoneChanges(): Array<CKSyncEngine_PendingRecordZoneChange>
Swift declaration
final var pendingRecordZoneChanges: [CKSyncEngine.PendingRecordZoneChange] { get }
A list of record zone changes that the sync engine has yet to send to the iCloud servers.
This array contains any pending record zone changes to send to the iCloud servers.
After the sync engine sends those changes, your app's sync delegate receives an event of type ``CKSyncEngine-5sie5/Event/SentRecordZoneChanges``.
The sync engine keeps this list up-to-date while sending changes to the server.
For example, when it successfully saves a record, it removes that change from this list.
If it fails to send a change due to some retryable error (e.g. a network failure), it keeps that change in this list.
Use the ``CKSyncEngine-5sie5/State/add(pendingRecordZoneChanges:)`` and ``CKSyncEngine-5sie5/State/remove(pendingRecordZoneChanges:)`` methods to modify the array's contents.
get · iOS 17.0+
hasPendingUntrackedChanges
TypeScript
get hasPendingUntrackedChanges(): boolean
Swift declaration
final var hasPendingUntrackedChanges: Bool { get set }
A Boolean value that indicates whether there are pending changes that the sync engine is unaware of.
Use this property to inform the sync engine that there are pending changes other than those available in ``CKSyncEngine-5sie5/State/pendingRecordZoneChanges``.
After you set this property, the sync engine automatically schedules a send operation and, when that operation executes, asks your delegate to provide those changes by invoking the ``CKSyncEngineDelegate-1q7g8/nextRecordZoneChangeBatch(_:syncEngine:)`` method.
Using this property is optional and is necessary only if you track pending changes manually, outside of the sync engine's state.
set · iOS 17.0+
hasPendingUntrackedChanges
TypeScript
set hasPendingUntrackedChanges(value: boolean)
Swift declaration
final var hasPendingUntrackedChanges: Bool { get set }
A Boolean value that indicates whether there are pending changes that the sync engine is unaware of.
Use this property to inform the sync engine that there are pending changes other than those available in ``CKSyncEngine-5sie5/State/pendingRecordZoneChanges``.
After you set this property, the sync engine automatically schedules a send operation and, when that operation executes, asks your delegate to provide those changes by invoking the ``CKSyncEngineDelegate-1q7g8/nextRecordZoneChangeBatch(_:syncEngine:)`` method.
Using this property is optional and is necessary only if you track pending changes manually, outside of the sync engine's state.
get · iOS 17.0+
zoneIDsWithUnfetchedServerChanges
TypeScript
get zoneIDsWithUnfetchedServerChanges(): Array<CKRecordZone_ID>
Swift declaration
final var zoneIDsWithUnfetchedServerChanges: [CKRecordZone.ID] { get }
The identifiers of zones with changes on the server that have not yet been fetched.
The sync engine populates this list automatically, for example when receiving a push notification indicating new changes.
final func add(pendingDatabaseChanges: [CKSyncEngine.PendingDatabaseChange])
Adds the specified database changes to the state.
- Parameter pendingDatabaseChanges: An array of database changes.
Use this method to enable the sync engine to manage your pending database changes.
For example, when someone makes a change that your app needs to send to the server, use this method to record the change.
If there are no scheduled sync operations when you invoke this method, the sync engine automatically schedules one to send the changes.
After the engine sends those changes, it notifies your app's sync delegate with an event of type ``CKSyncEngine-5sie5/Event/SentDatabaseChanges``.
The sync engine maintains a consistent collection of tracked pending changes, deduplicating them as necessary.
The engine removes changes from the list as it sends them, but retains any that fail due to a recoverable error, such as a network issue or exceeding the rate limit.
- Note: The order in which you apply database changes is important.
For example:
- If you add `.saveZone(zoneA)` then `.deleteZone(zoneA)`, the sync engine discards the save and sends only the delete change.
- If you add `.deleteZone(zoneA)` then `.saveZone(zoneA)`, the sync engine discards the delete and sends only the save change.
final func add(pendingRecordZoneChanges: [CKSyncEngine.PendingRecordZoneChange])
Adds the specified record zone changes to the state.
- Parameter pendingRecordZoneChanges: An array of record zone changes.
Use this method to enable the sync engine to manage your pending record zone changes.
For example, when someone makes a change that your app needs to send to the server, use this method to record the change.
Then, when creating the change batch for the next send operation, retrieve the pending changes from the ``CKSyncEngine-5sie5/State/pendingRecordZoneChanges`` property.
If there are no scheduled sync operations when you invoke this method, the sync engine automatically schedules one to send the changes.
After the engine sends those changes, it notifies your app's sync delegate with an event of type ``CKSyncEngine-5sie5/Event/SentRecordZoneChanges``.
The sync engine maintains a consistent collection of tracked pending changes, deduplicating them as necessary.
The engine removes changes from the list as it sends them, but retains any that fail due to a recoverable error, such as a network issue or exceeding the rate limit.
- Note: The order in which you apply record zone changes is important.
For example:
- If you add `.saveRecord(recordA)` then `.deleteRecord(recordA)`, the sync engine discards the save and sends only the delete change.
- If you add `.deleteRecord(recordA)` then `.saveRecord(recordA)`, the sync engine discards the delete and sends only the save change.
final func remove(pendingDatabaseChanges: [CKSyncEngine.PendingDatabaseChange])
Removes the specified database changes from the state.
- Parameter pendingDatabaseChanges: An array of database changes.
Use this method when you no longer want the sync engine to send certain pending changes.
final func remove(pendingRecordZoneChanges: [CKSyncEngine.PendingRecordZoneChange])
Removes the specified record zone changes from the state.
- Parameter pendingRecordZoneChanges: An array of record zone changes.
Use this method when you no longer want the sync engine to send certain pending changes.
