Mastering iOS UserDefaults: Best Practices, Shared Containers, and Real‑Time Monitoring

Introduction

UserDefaults is the preferred key‑value store for persisting simple preferences between launches of a Swift app, backed by a property‑list (plist) file. It works well for flags such as "hasSeenOnboarding" or a list of favorite stocks.

UserDefaults.standard.set(true, forKey: "has-seen-onboarding")
UserDefaults.standard.set(["AAPL", "TSLA"], forKey: "favorite-stocks")
print(UserDefaults.standard.bool(forKey: "has-seen-onboarding")) // true
print(UserDefaults.standard.array(forKey: "favorite-stocks")) // ["AAPL", "TSLA"]

Sharing UserDefaults via App Groups

By enabling an App Group, multiple apps or extensions can read and write the same UserDefaults container. Adding the App Group capability in Xcode creates a shared suite that can be accessed through a custom initializer.

extension UserDefaults {
    static let group = UserDefaults(suiteName: "group.your.identifier")
}

UserDefaults.group.set(["AAPL", "TSLA"], forKey: "favorite-stocks")

Any app or extension that belongs to the same group can now read or write the "favorite-stocks" key, enabling features such as a widget that displays the user's chosen stocks.

Supported Data Types

UserDefaults can only store objects that are property‑list compatible. Attempting to store an unsupported type throws an exception, for example when trying to save a custom struct directly.

*** Terminating app due to uncaught exception ‘NSInvalidArgumentException’, reason: ‘Attempt to insert non‑property list object UserDefaults.Stock(symbol: “AAPL”) for key last-opened-stock’

To store custom data, encode it to Data with JSONEncoder (or another encoder) before saving, and decode it when reading.

Data

String

NSNumber (numbers)

Date

Array

Dictionary

Bool

If your type is not in this list, convert it to one of the supported types first.

Observing Changes

While you can listen to UserDefaults.didChangeNotification, a more ergonomic approach is to use a property‑wrapper that publishes changes, providing real‑time monitoring without boilerplate.

Real‑time Monitoring with RocketSim

To speed up testing of preference‑driven features, the author built a "UserDefaults Editor" in the RocketSim app. The editor loads the plist file, lets you edit keys, and highlights changes with a blue background.

The workflow is simple: edit a value, see the visual cue, optionally reset it with a toggle, and relaunch the app to verify that UI elements such as a one‑time tooltip behave as expected.

Debugging Overrides

During debugging you may want to temporarily override stored values. The RocketSim editor supports loading a custom scheme file that pre‑populates UserDefaults, making it easy to test edge cases without modifying production code.

Alternative Solutions

Keychain for Sensitive Data

UserDefaults is not suitable for credentials, API keys, or any sensitive information. Store such data securely in the iOS Keychain.

NSUbiquitousKeyValueStore for Cross‑Device Sync

If preferences need to be shared across a user's Apple devices, consider NSUbiquitousKeyValueStore, which synchronizes a similar key‑value store via iCloud.

Conclusion

UserDefaults provides a straightforward way to persist simple preferences and share them across apps using App Groups. Pay attention to the supported data types, monitor changes when needed, and switch to Keychain or iCloud‑backed stores for sensitive or cross‑device data.