Added implementation for NSUbiquitousKeyValueStore #237

arthef · 2025-06-21T03:59:48Z

Using NSUbiquitousKeyValueStore settings can be automatically shared between devices. The implantation follows convention of other implementations and is mainly based on the NSUserDefaultsSettings code.

Except standard initialization, no other special code is needed. However, to make key-value storage work, the app needs to be correctly configured in Xcode:

In the app project, TARGETS, Signing & Capabilities a new capability needs to be added (+ Capability):

iCloud, Service: Key-value storage

Also, it is highly recommended to add and implement external change listener(s) to make the app aware of the settings change on other device.

… callbacks.

russhwolf

Thanks for the contribution! I've never worked with NSUbiquitousKeyValueStore so I want to make sure everything works as expected before merging this.

The most important item to that end is to make sure this class passes the test suite for Settings implementations, in order to verify that it behaves as expected. This means adding a test class that extends BaseSettingsTest. Because it requires entitlements, this takes a bit of setup. You can use the keychain-tests module as a template.

I have other priorities at the moment so I don't expect to get this merged before the next library release (1.4.0).

...rm-settings/src/appleMain/kotlin/com/russhwolf/settings/NSUbiquitousKeyValueStoreSettings.kt

russhwolf · 2025-06-21T16:14:23Z

...rm-settings/src/appleMain/kotlin/com/russhwolf/settings/NSUbiquitousKeyValueStoreSettings.kt

+            callback.invoke()
+        }
+        val observer = NSNotificationCenter.defaultCenter.addObserverForName(
+            name = NSUbiquitousKeyValueStoreDidChangeExternallyNotification,


I'm not certain this will work as intended. The documentation for NSUbiquitousKeyValueStoreDidChangeExternallyNotification suggests that notifications are only served from external changes, meaning that if we update a value in-app it won't propagate to listeners. This would break the expectations of ObservableSettings

You are correct here. The notification does not trigger to the app which made the change, which is, as I understand, your intended function.
The notification from the NSUbiquitousKeyValueStore changes is only triggered for apps running on other devices.
However, I could not see any other place or way or API to implement external changes notification for the app, therefore I used this one.
From what I read in the documentation, the NSUbiquitousKeyValueStore does not send notification to the local app at all.

If you have any idea or suggestion on how to implement this in a different way, please let me know. I can rewrite the code.

I'll have to think about this some. I'm not sure whether it makes sense to use ObservableSettings instead of Settings here. Do we eventually see updated values on get calls even without subscribing to external notifications?

russhwolf · 2025-06-21T16:17:27Z

...rm-settings/src/appleMain/kotlin/com/russhwolf/settings/NSUbiquitousKeyValueStoreSettings.kt

+internal expect fun NSUbiquitousKeyValueStore.intForKey(defaultName: String): Int
+internal expect fun NSUbiquitousKeyValueStore.setInt(value: Int, forKey: String)
+internal expect fun NSUbiquitousKeyValueStore.longForKey(defaultName: String): Long
+internal expect fun NSUbiquitousKeyValueStore.setLong(value: Long, forKey: String)
+internal expect fun NSUbiquitousKeyValueStore.setFloat(value: Float, forKey: String)
+internal expect fun NSUbiquitousKeyValueStore.floatForKey(defaultName: String): Float


There's no reason to use expect/actual for these if the implementations are the same for 32-bit and 64-bit systems.

As I said, not fully understanding the library implementation I tried to keep it as close to the NSUserDefaults as possible. I can rewrite this part if you want. Please confirm.

Yes, please rewrite it without expect/actual

russhwolf · 2025-06-21T16:23:30Z

...rm-settings/src/appleMain/kotlin/com/russhwolf/settings/NSUbiquitousKeyValueStoreSettings.kt

+
+    private fun addListener(key: String, callback: () -> Unit): SettingsListener {
+        val block = { _: NSNotification? ->
+            callback.invoke()


This probably should be caching the previous value, similar to other implementations, in order to avoid triggering the listener when nothing has changed.

I ran several tests and have it working in my app. It looks like the NSUbiquitousKeyValueStore takes care of avoiding notifications if nothing changed. So, it basically handles it itself efficiently. Therefore, from my experience, caching here is not needed for the NSUbiquitousKeyValueStore implementation. However, I can put it back for consistency with other implementations.

Please confirm that this is what you want.

The issue is, if you have two different keys "a" and "b" but you're only observing "a", the notification will trigger for changes to both "a" and "b". The cache ensures that the update callbacks only trigger when the key you're observing changes.

I added cache back and confirmed it works as expected during my tests.

…ings/NSUbiquitousKeyValueStoreSettings.kt Yes, I agree, this makes sense. Co-authored-by: Russell Wolf <russhwolf@users.noreply.github.com>

…ings/NSUbiquitousKeyValueStoreSettings.kt Ok, TBH, when I was working on the code, I did not fully understand the existing implementation and therefore, tried to keep the new class as close to the NSUserDefaults implementation as possible. Co-authored-by: Russell Wolf <russhwolf@users.noreply.github.com>

arthef · 2025-07-22T21:59:52Z

Hopefully with my recent commits all concerns are resolved.
Please take a look and let me know if there is anything else to be done to accept the PR.

russhwolf · 2025-07-25T19:11:34Z

I'd like to get tests running against this as well. I can take a pass at it at some point but probably not soon.

coreypett-cube · 2025-10-20T16:24:56Z

Any ETA on this? Soon to fork and apply @arthef's work.

russhwolf · 2025-10-30T01:40:40Z

No ETA, sorry. I don't want to merge this without having tests running against it. Open to contributions there.

If you want it sooner you should be able to just copy NSUbiquitousKeyValueStoreSettings.kt to your project without needing to fork anything.

kobit added 2 commits June 18, 2025 23:03

Added support for NSUbiquitousKeyValueStore on iOS/MacOS

b0b75b5

Corrected code documentation and removed caching from change listener…

cb5017e

… callbacks.

russhwolf requested changes Jun 21, 2025

View reviewed changes

arthef and others added 4 commits June 21, 2025 11:05

Update multiplatform-settings/src/appleMain/kotlin/com/russhwolf/sett…

f9dc483

…ings/NSUbiquitousKeyValueStoreSettings.kt Yes, I agree, this makes sense. Co-authored-by: Russell Wolf <russhwolf@users.noreply.github.com>

Added cache back to the update listeners. Confirmed it works.

5195f57

Rewritten code without unnecessary expect/actual as requested.

cfd6316

Added implementation for NSUbiquitousKeyValueStore #237

Are you sure you want to change the base?

Added implementation for NSUbiquitousKeyValueStore #237

Uh oh!

Conversation

arthef commented Jun 21, 2025

Uh oh!

russhwolf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

arthef commented Jul 22, 2025

Uh oh!

russhwolf commented Jul 25, 2025

Uh oh!

coreypett-cube commented Oct 20, 2025

Uh oh!

russhwolf commented Oct 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants