Add custom UserDefaults store support for app groups and shared defaults

Author: nbasham

.github/workflows/ci.yml

@@ -0,0 +1,17 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build
+        run: swift build
+      - name: Test
+        run: swift test

.gitignore

@@ -47,44 +47,4 @@ playground.xcworkspace
 .swiftpm
 
 .build/
-
-# CocoaPods
-#
-# We recommend against adding the Pods directory to your .gitignore. However
-# you should judge for yourself, the pros and cons are mentioned at:
-# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
-#
-# Pods/
-#
-# Add this line if you want to avoid checking in source code from the Xcode workspace
-# *.xcworkspace
-
-# Carthage
-#
-# Add this line if you want to avoid checking in source code from Carthage dependencies.
-# Carthage/Checkouts
-
-Carthage/Build/
-
-# Accio dependency management
-Dependencies/
-.accio/
-
-# fastlane
-#
-# It is recommended to not store the screenshots in the git repo.
-# Instead, use fastlane to re-generate the screenshots whenever they are needed.
-# For more information about the recommended setup visit:
-# https://docs.fastlane.tools/best-practices/source-control/#source-control
-
-fastlane/report.xml
-fastlane/Preview.html
-fastlane/screenshots/**/*.png
-fastlane/test_output
-
-# Code Injection
-#
-# After new code Injection tools there's a generated folder /iOSInjectionProject
-# https://github.com/johnno1962/injectionforxcode
-
-iOSInjectionProject/
+.DS_Store

.spi.yml

@@ -0,0 +1,4 @@
+version: 1
+builder:
+  configs:
+    - documentation_targets: [CloudUserDefaults]

README.md

@@ -1,22 +1,20 @@
 # About
+Just drop one file in your project and add a few lines of code and your settings are now visible to all your user's devices.
 
 CloudUserDefaults automatically syncs `UserDefaults` **values** that use a **key** with a specified prefix to the cloud. Silently listening to system events it detects when a `UserDefaults` **key** with a given prefix is changed and automatically syncs the **value**. For example, if you choose ***cloud_*** as the prefix `UserDefaults.standard.set(1, forKey: "cloud_count")` is set on all the user's devices.
 
 This is based on Mugunth Kumar's elegant solution `MKiCloudSync` an Objective-C [GitHub repository](https://github.com/MugunthKumar/MKiCloudSync) that is now archived. Thanks to [Paul Hudson for the introduction to `MKiCloudSync`](https://www.hackingwithswift.com/example-code/system/how-to-store-userdefaults-options-in-icloud).
 
-## Installation
+![CI](https://github.com/nbasham/CloudUserDefaults/actions/workflows/ci.yml/badge.svg)
 
+## Installation
 ### Swift Package Manager
-If you are using Xcode 11 or later:
  1. Click `File`
- 2. `Swift Packages`
- 3. `Add Package Dependency...`
- 4. Specify the git URL for CloudUserDefaults.
-
+ 2. `Add Package Dependencies...`
+ 3. Specify the git URL for CloudUserDefaults.
 ```swift
 https://github.com/nbasham/CloudUserDefaults.git
 ```
-
 ### Manual
 Copy `CloudUserDefaults.swift` to your project
 
@@ -26,13 +24,30 @@ In Xcode, click your project, click your target, click `Signing & Capabilities`,
 **NOTE** iCloud events are not sent to the simulator.
 
 ## Usage
-Create an instance of `CloudUserDefaults` some place it will stay in scope (e.g. in your `AppDelegate`) and call `start` with a prefix of your choosing e.g.
+Create an instance of `CloudUserDefaults` somewhere it will stay in scope and call `start` with a prefix of your choosing.
+
+**AppDelegate**
 ```swift
 import CloudUserDefaults
 ...
 let cloudUserDefaults = CloudUserDefaults()
 cloudUserDefaults.start(prefix: "cloud_")
 ```
+
+**SwiftUI**
+```swift
+import CloudUserDefaults
+
+@main
+struct MyApp: App {
+    let cloudUserDefaults = CloudUserDefaults()
+
+    init() {
+        cloudUserDefaults.start(prefix: "cloud_")
+    }
+}
+```
+
 That's it, whenever a `UserDefaults` **key** starts with `cloud_` it is automatically synced to all the user's devices e.g.
 ```swift
 UserDefaults.standard.set(42, forKey: "cloud_answer") // synced to cloud
@@ -42,17 +57,23 @@ UserDefaults.standard.set(42, forKey: "answer")       // local
 Subscribe to `CloudUserDefaults.cloudSyncNotification` if you want to be notified when user defaults from another device are delivered e.g.
 ```swift
 NotificationCenter.default.addObserver(self,
- selector: #selector(cloudUpdate(notification:)),
- name: CloudUserDefaults.cloudSyncNotification,
- object: nil)
+    selector: #selector(cloudUpdate(notification:)),
+    name: CloudUserDefaults.cloudSyncNotification,
+    object: nil)
+```
+
+## Advanced Usage
+If you use app groups (e.g. to share defaults with a widget), pass your suite instead:
+```swift
+let suite = UserDefaults(suiteName: "group.com.mycompany.myapp")!
+let cloudUserDefaults = CloudUserDefaults(defaults: suite)
+cloudUserDefaults.start(prefix: "cloud_")
 ```
+
 ## Contributing
 Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
 
 Please make sure to update tests as appropriate.
 
 ## License
 [MIT](https://choosealicense.com/licenses/mit/)
-
-
-

Sources/CloudUserDefaults/CloudUserDefaults.swift

@@ -1,39 +1,56 @@
 import Foundation
 
+/// Automatically syncs `UserDefaults` values to iCloud across all of a user's devices.
+/// Values are synced when their key matches a specified prefix.
+///
+/// Create an instance somewhere it will stay in scope, then call ``start(prefix:)``.
+///
+/// ```swift
+/// // AppDelegate
+/// let cloudUserDefaults = CloudUserDefaults()
+/// cloudUserDefaults.start(prefix: "cloud_")
+/// ```
 open class CloudUserDefaults {
 
+    /// Posted when values have been received from iCloud.
+    /// The notification object contains the full iCloud key-value dictionary.
     public static let cloudSyncNotification = Notification.Name("CloudSyncNotification")
+
     internal var prefix: String!
+    private let defaults: UserDefaults
 
-    public init() {}
+    /// Creates a new instance using the specified `UserDefaults` store.
+    /// - Parameter defaults: The `UserDefaults` instance to sync. Defaults to `UserDefaults.standard`.
+    ///   Pass a suite-based instance for app groups and widgets.
+    public init(defaults: UserDefaults = .standard) {
+        self.defaults = defaults
+    }
 
+    /// Begins listening for changes to `UserDefaults` and iCloud, syncing any key that starts with the given prefix.
+    /// - Parameter prefix: The key prefix that identifies values to sync, e.g. `"cloud_"`.
     public func start(prefix: String) {
         self.prefix = prefix
         NotificationCenter.default.addObserver(self, selector: #selector(notificationFromCloud(notification:)), name: NSUbiquitousKeyValueStore.didChangeExternallyNotification, object: nil)
-        NotificationCenter.default.addObserver(self, selector: #selector(notifyCloud(notification:)), name: UserDefaults.didChangeNotification, object: nil)
+        NotificationCenter.default.addObserver(self, selector: #selector(notifyCloud(notification:)), name: UserDefaults.didChangeNotification, object: defaults)
     }
 
     @objc internal func notificationFromCloud(notification: NSNotification) {
         let dict = NSUbiquitousKeyValueStore.default.dictionaryRepresentation
-
         //  Disable notifications to cloud while we set local values from cloud
-        NotificationCenter.default.removeObserver(self, name: UserDefaults.didChangeNotification, object: nil)
-
+        NotificationCenter.default.removeObserver(self, name: UserDefaults.didChangeNotification, object: defaults)
         for (key, value) in dict {
             if key.hasPrefix(prefix) {
-                UserDefaults.standard.set(value, forKey: key)
+                defaults.set(value, forKey: key)
             }
         }
-
         //  Resume notifications to cloud
-        NotificationCenter.default.addObserver(self, selector: #selector(notifyCloud(notification:)), name: UserDefaults.didChangeNotification, object: nil)
-
+        NotificationCenter.default.addObserver(self, selector: #selector(notifyCloud(notification:)), name: UserDefaults.didChangeNotification, object: defaults)
         //  Send a message with cloud payload that app can listen to
         NotificationCenter.default.post(name: CloudUserDefaults.cloudSyncNotification, object: dict)
     }
 
     @objc internal func notifyCloud(notification: NSNotification) {
-        let dict = UserDefaults.standard.dictionaryRepresentation()
+        let dict = defaults.dictionaryRepresentation()
         for (key, value) in dict {
             if key.hasPrefix(prefix) {
                 NSUbiquitousKeyValueStore.default.set(value, forKey: key)

Tests/CloudUserDefaultsTests/CloudUserDefaultsTests.swift

@@ -2,7 +2,6 @@ import XCTest
 @testable import CloudUserDefaults
 
 final class CloudUserDefaultsTests: XCTestCase {
-
     private let prefix = "cloud_"
     private let testKey = "test_key"
     private let testCloudKey = "cloud_test_key"
@@ -23,8 +22,6 @@ final class CloudUserDefaultsTests: XCTestCase {
     func testNotificationFromCloud() {
         let cloudUserDefaults = CloudUserDefaults()
         cloudUserDefaults.start(prefix: prefix)
-
-        //  Check that CloudUserDefaults.cloudSyncNotification is sent
         let _ = expectation(forNotification: CloudUserDefaults.cloudSyncNotification, object: nil, handler: nil)
         cloudUserDefaults.notificationFromCloud(notification: unusedNotification)
         waitForExpectations(timeout: 1, handler: nil)
@@ -35,8 +32,6 @@ final class CloudUserDefaultsTests: XCTestCase {
         cloudUserDefaults.start(prefix: prefix)
         UserDefaults.standard.set(testValue, forKey: testKey)
         UserDefaults.standard.set(testValue, forKey: testCloudKey)
-
-        //  Check that values are set in expected stores
         XCTAssertNil(NSUbiquitousKeyValueStore.default.object(forKey: testKey))
         XCTAssertNotNil(UserDefaults.standard.object(forKey: testKey))
         XCTAssertNotNil(NSUbiquitousKeyValueStore.default.object(forKey: testCloudKey))