Jeehut / CloudStorage

Swift property wrapper to sync settings through iCloud key-value storage

@CloudStorage property wrapper

Sync settings through iCloud key-value storage.

What is this?

Similar to @AppStorage and @SceneStorage in iOS14, this @CloudStorage property wrapper persists values across app restarts. But this also synchronizes these values across devices using iCloud Key-Value Storage.

Usage

Step 1: Enable the iCloud "Key-value storage" service

1. Select your project file in Xcode, select the target and click "Signing & Capabilities"
2. Hit the "+ Capability" button in the top-left
3. Search for "iCloud" and add the capability
4. Enable the "Key-value storage" service

📺 Watch the screen recording of this instruction

Step 2: Add this library as an SPM dependency

Hit File -> Add Packages... and paste the URL of this GitHub repo to add it to your project.

Step 3: Use the property wrapper

These values will be synced between devices of the user of your app:

@CloudStorage("readyForAction") var readyForAction: Bool = false
@CloudStorage("numberOfItems") var numberOfItems: Int = 0
@CloudStorage("orientation") var orientation: String?

See also the example app in this repository.

For what should this be used?

The same caveats apply as with key-value storage itself:

Key-value storage is for discrete values such as preferences, settings, and simple app state.

Use iCloud key-value storage for small amounts of data: stocks or weather information, locations, bookmarks, a recent documents list, settings and preferences, and simple game state. Every app submitted to the App Store or Mac App Store should take advantage of key-value storage.

From Apple's documenation on choosing the proper iCloud Storage API

In general, key-value storage is not meant as a general purpose syncing service. If you need any advanced capabilities to prevent data loss, consider using CloudKit instead.

Syncing between apps and extensions

To sync the same key-value items between different apps (from the same team) or even between an app and its extensions, follow these steps:

1. Designate one of the apps as the primary app
2. In the other apps/extensions, change the iCloud Key-Value Storage ID manually to be the same as the primary app

For example, if your primary app has the bundle identifier com.example.my-app, and its .entitlements file has this entry:

<key>com.apple.developer.ubiquity-kvstore-identifier</key>
<string>$(TeamIdentifierPrefix)$(CFBundleIdentifier)</string>

Make sure in the other apps or extensions to configure the .entitlements file like so:

<key>com.apple.developer.ubiquity-kvstore-identifier</key>
<string>$(TeamIdentifierPrefix)com.example.my-app</string>

See also: Configuring a Common iCloud Container for Multiple Apps (developer.apple.com)

Authors

Nonstrict B.V., Tom Lokhorst & Mathijs Kadijk, released under MIT License