Sync States

Understanding CloudKit synchronization lifecycle and monitoring sync progress.

Sync States

CloudKit sync operates in phases:

1. Not Syncing

Indicator: No pending changes, no active network operations.

Conditions:

• context.hasChanges == false

• No CloudKit export/import tasks running

2. Pending Upload

Indicator: Local changes waiting for CloudKit export.

Trigger: After context.save() with modified objects.

Duration: Immediate to 30 seconds (depends on network, CloudKit queue).

3. Uploading

Indicator: CloudKit exporting records to Private/Shared Database.

Monitoring:

NotificationCenter.default.addObserver(forName: NSPersistentCloudKitContainer.eventChangedNotification) { notification in
    if let event = notification.userInfo?[NSPersistentCloudKitContainer.eventNotificationUserInfoKey] as? NSPersistentCloudKitContainer.Event {
        if event.type == .export {
            print("Syncing: \(event.succeeded ? "Success" : "Failed")")
        }
    }
}

4. Pending Download

Indicator: Remote changes detected, queued for import.

Trigger: Push notification from CloudKit with new data.

5. Downloading

Indicator: CloudKit importing records to local store.

Event:

if event.type == .import {
    print("Downloading remote changes...")
}

6. Synced

Indicator: Local and remote data consistent.

User Feedback: Show checkmark, "All changes saved".

Event Notifications

Subscribe:

NotificationCenter.default.addObserver(
    self,
    selector: #selector(handleCloudKitEvent),
    name: NSPersistentCloudKitContainer.eventChangedNotification,
    object: nil
)

Event Types:

• .setup: Initial CloudKit setup

• .import: Downloading from CloudKit

• .export: Uploading to CloudKit

Event Properties:

func handleCloudKitEvent(_ notification: Notification) {
    guard let event = notification.userInfo?[NSPersistentCloudKitContainer.eventNotificationUserInfoKey] as? NSPersistentCloudKitContainer.Event else { return }
    
    print("Type: \(event.type)")
    print("Start: \(event.startDate)")
    print("End: \(event.endDate)")
    print("Succeeded: \(event.succeeded)")
    
    if let error = event.error {
        print("Error: \(error.localizedDescription)")
    }
}

UI Sync Indicators

Simple Indicator:

@State private var isSyncing = false

var body: some View {
    HStack {
        Text("Companies")
        if isSyncing {
            ProgressView()
                .scaleEffect(0.8)
        }
    }
    .onReceive(NotificationCenter.default.publisher(for: NSPersistentCloudKitContainer.eventChangedNotification)) { notification in
        if let event = notification.userInfo?[NSPersistentCloudKitContainer.eventNotificationUserInfoKey] as? NSPersistentCloudKitContainer.Event {
            isSyncing = !event.succeeded && event.endDate == nil
        }
    }
}

Advanced: Per-Entity Sync: Track which entities are syncing:

@Published var syncingEntities = Set<String>()

func trackSyncEvent(_ event: NSPersistentCloudKitContainer.Event) {
    // Parse event.storeIdentifier or affected entity types
    if event.type == .export && !event.succeeded {
        syncingEntities.insert("Orders")
    } else if event.succeeded {
        syncingEntities.remove("Orders")
    }
}

Background Sync

Automatic: iOS performs background sync when app is inactive.

Configuration (already enabled in TheCompanyApp):

// Background notification subscriptions set up automatically
// No additional code needed

Limitations:

• Requires Background Modes capability

• iOS controls timing (battery, network)

• Not guaranteed immediate

Manual Sync Trigger

User-Initiated Refresh:

func forceSyncNow() {
    // Save any pending changes
    if viewContext.hasChanges {
        try? viewContext.save()
    }
    
    // CloudKit will export automatically
    // To force import of remote changes:
    viewContext.refreshAllObjects()
}

Pull-to-Refresh Example:

List {
    ForEach(companies) { company in
        // ...
    }
}
.refreshable {
    forceSyncNow()
}

Offline Behavior

Local-First: All operations work offline.

Queue: Changes saved to local store, sync when network available.

Indicator:

import Network

let monitor = NWPathMonitor()
monitor.pathUpdateHandler = { path in
    if path.status == .satisfied {
        print("Online - CloudKit will sync")
    } else {
        print("Offline - Changes queued")
    }
}
monitor.start(queue: DispatchQueue.global())

Sync Errors

Common Errors:

• CKErrorNetworkUnavailable: No internet

• CKErrorNotAuthenticated: Not signed in to iCloud

• CKErrorQuotaExceeded: iCloud storage full

• CKErrorZoneBusy: Too many requests, retry later

Handling:

if let ckError = error as? CKError {
    switch ckError.code {
    case .networkUnavailable:
        showAlert("No internet connection")
    case .notAuthenticated:
        showAlert("Please sign in to iCloud")
    case .quotaExceeded:
        showAlert("iCloud storage full")
    default:
        showAlert(ckError.localizedDescription)
    }
}

---

Related: Sync Architecture, Remote Change Handling, Troubleshooting