NSPersistentCloudKitContainer Sync Status in SwiftUI: Events, Imports, and Honest UI

NSPersistentCloudKitContainer does not provide a single “everything is synced” property. It produces setup, import, and export events, while the system decides when network work actually runs. A trustworthy SwiftUI status therefore has to report what the app has observed without promising that every device is current.

This guide builds that boundary. It uses NSPersistentCloudKitContainer.eventChangedNotification for operational state, NSPersistentStoreRemoteChange for UI refresh, and a persisted success date for a useful “last sync activity” message.

If the underlying container is still unreliable, start with the production NSPersistentCloudKitContainer guide and the CloudKit troubleshooting checklist.

Understand what each notification proves

Apple exposes two notifications that answer different questions. Its CloudKit synchronization debugging technote explicitly separates observing container events from responding to persistent-store changes:

• NSPersistentCloudKitContainer.eventChangedNotification reports setup, import, and export activity. Use it for operational status and errors.
• NSPersistentStoreRemoteChange tells your app that the persistent store changed. Use it to consume persistent history, merge changes, and refresh visible data.

An import event ending successfully proves that one import operation completed. It does not prove that no newer server changes exist. An export event ending successfully proves that one export completed. It does not prove that another device already imported it.

That distinction should shape the labels in the product. “Sync activity completed” is supportable. “All devices are up to date” is usually not.

Model status as observed activity

A small state model is enough for most apps:

import CoreData

enum CloudSyncPhase: Equatable {
    case idle
    case settingUp
    case importing
    case exporting
    case failed(message: String)
}

struct CloudSyncSnapshot: Equatable {
    var phase: CloudSyncPhase = .idle
    var lastSuccessfulActivity: Date?
}

Avoid a Boolean named isSynced. It collapses setup, import, export, delay, and failure into a claim the framework cannot verify.

Observe container events once

Give monitoring one long-lived owner. Do not install a notification observer in every view.

import CoreData
import Observation

@MainActor
@Observable
final class CloudSyncMonitor {
    private(set) var snapshot = CloudSyncSnapshot()
    private var task: Task<Void, Never>?

    func start() {
        guard task == nil else { return }

        task = Task { [weak self] in
            let notifications = NotificationCenter.default.notifications(
                named: NSPersistentCloudKitContainer.eventChangedNotification
            )

            for await notification in notifications {
                guard !Task.isCancelled else { break }
                self?.receive(notification)
            }
        }
    }

    func stop() {
        task?.cancel()
        task = nil
    }

    private func receive(_ notification: Notification) {
        guard let event = notification.userInfo?[
            NSPersistentCloudKitContainer.eventNotificationUserInfoKey
        ] as? NSPersistentCloudKitContainer.Event else {
            return
        }

        if event.endDate == nil {
            snapshot.phase = switch event.type {
            case .setup: .settingUp
            case .import: .importing
            case .export: .exporting
            @unknown default: .idle
            }
            return
        }

        if event.succeeded {
            snapshot.phase = .idle
            snapshot.lastSuccessfulActivity = event.endDate
        } else {
            snapshot.phase = .failed(
                message: event.error?.localizedDescription
                    ?? "Cloud sync did not complete."
            )
        }
    }
}

The monitor starts once near the persistence stack or app root. If the app supports multiple stores or CloudKit scopes, keep state per store identifier rather than allowing one successful event to hide a failure from another store.

Do not treat events as progress percentages

Container events expose start and end dates, type, success, and error. They do not expose reliable record counts or a percentage complete. A progress bar that advances from 0 to 100 is invented state.

Use an indeterminate indicator while setup, import, or export is active:

import SwiftUI

struct CloudSyncStatusView: View {
    let snapshot: CloudSyncSnapshot

    var body: some View {
        LabeledContent("iCloud") {
            switch snapshot.phase {
            case .settingUp:
                ProgressView("Preparing")
            case .importing:
                ProgressView("Checking for updates")
            case .exporting:
                ProgressView("Saving changes")
            case .failed(let message):
                Label(message, systemImage: "exclamationmark.icloud")
                    .foregroundStyle(.secondary)
            case .idle:
                if let date = snapshot.lastSuccessfulActivity {
                    Text(date, style: .relative)
                } else {
                    Text("Waiting for sync activity")
                }
            }
        }
    }
}

The wording describes activity, not global freshness. It also avoids blaming the person when the system defers work for network, power, account, or scheduling reasons.

Keep the UI current after an import

An import event and a visible UI update are separate gates. Apple’s technote recommends observing NSPersistentStoreRemoteChange, consuming persistent history, merging relevant transactions into the view context, and then refreshing the interface. The eventChangedNotification reference documents the setup, import, and export event family used for the operational status.

Configure the store before loading it:

let description = container.persistentStoreDescriptions.first!
description.setOption(
    true as NSNumber,
    forKey: NSPersistentHistoryTrackingKey
)
description.setOption(
    true as NSNumber,
    forKey: NSPersistentStoreRemoteChangeNotificationPostOptionKey
)

Then give history processing its own serialized owner. The handler should fetch transactions after the last persisted history token, merge their object-ID changes into the view context, save the new token, and prune history according to the app’s retention policy.

Do not merely refetch every screen when an event arrives. The event may describe an export that changed nothing locally, and a remote-change notification may contain changes irrelevant to the visible query.

Handle first launch without showing a false empty state

On a fresh device, the local store can load before CloudKit finishes the initial import. Rendering a permanent “No items” message at that point makes working sync look like data loss.

Use three states:

1. The local store is loading: show a launch-level loading state.
2. The store loaded but no successful setup or import has been observed: show the local content plus a small “Checking iCloud” status.
3. Activity completed and the store is empty: show the real empty state.

Do not block the entire app indefinitely while waiting for an import. The device can be offline, signed out of iCloud, restricted, or legitimately empty. Let people create local content and make the sync state visible in a secondary location such as Settings or a status menu.

Persist the last successful activity carefully

Persisting lastSuccessfulActivity makes the status useful after relaunch. Store the timestamp locally; it is diagnostic state, not user content. Update it only when an observed event succeeds.

Do not call it lastSyncedAt unless the product copy explains that it means the last successful activity observed on this device. A different device may have newer changes that have not arrived yet.

Persist errors only when they help support. Raw CloudKit errors can include implementation details that are confusing in customer-facing UI. Show a plain recovery message to the person and retain the structured error code in local diagnostics or an explicitly exported support bundle.

Test the states on real devices

One simulator cannot prove cross-device synchronization. Use at least two physical devices signed into the same test account and record each gate separately:

• local save succeeds on device A;
• an export event succeeds on device A;
• an import event succeeds on device B;
• the remote-change processor merges the transaction;
• the visible query updates without relaunch;
• the UI remains honest while one device is offline;
• signing out of iCloud produces understandable behavior;
• a failed event does not erase local data or block editing.

Also test app termination and relaunch during initial import. A happy-path foreground session misses the failures that generate most sync support requests.

Production checklist

• Install event and remote-change observers once.
• Track setup, import, and export separately.
• Treat start/end events as activity, not percentage progress.
• Persist a per-device last-success date.
• Consume persistent history before refreshing SwiftUI state.
• Avoid a false empty state during a fresh-device import.
• Keep local editing available when CloudKit is delayed.
• Test export, import, UI merge, and cross-device visibility as separate gates.

Related reading

• NSPersistentCloudKitContainer production edge cases
• CloudKit sync troubleshooting
• Core Data and CloudKit conflict resolution
• SwiftData shared-database sync patterns

If a shipped app cannot distinguish local saves, exports, imports, and UI merges, a focused iOS architecture audit can map the failure before the sync stack is rewritten.