UserDefaults
An interface to the user’s defaults database, which stores system-wide and app-specific settings.
Declaration
class UserDefaultsMentioned in
Overview
A UserDefaults object provides access to the defaults system, which is a persistent store for app-specific and system-wide settings. You use this system to store nonsensitive information, such as app-specific configuration details. The system also stores configuration details that apply to all apps, such as the current language settings for the device. In your code, you check values from this system and use them to dynamically alter your app’s appearance or behavior. The term defaults refers to the fact that the stored data determines the default startup state and behavior.
To access the defaults system, obtain a UserDefaults object and call its methods to read and write values. The standard object is a shared object you use to read and write your app’s standard settings. You can also create unique UserDefaults objects to manage specific sets of settings. For example, you can create a UserDefaults object that reads and writes settings your app shares with an app extension. Don’t subclass UserDefaults.
Each item you store in a defaults object consists of a key-value pair, where each key is a string that you use to locate the item and each value is a data object. The defaults database supports the same value types found in property list files, including types like Int, Float, Double, Bool, String, URL, NSNumber, Date, Array, and Dictionary. To include other types of objects in the defaults database, archive them to a Data object first and store that object instead. Prefer simple types over custom objects whenever possible.
With the exception of managed devices in educational institutions, the system stores defaults locally on the current device. When you write values to a UserDefaults object, the object updates its in-memory version of that information right away, and writes the value to disk asynchronously. When someone backs up their device, the system includes any persistent defaults databases in the backup data. Because the data is device-specific, you don’t use the defaults system to share data between devices. To share data between someone’s devices, use the NSUbiquitousKeyValueStore instead.
While your app is running, the defaults system generates notifications to let you know when values change. To observe changes to individual settings, add a Using Key-Value Observing in Swift to your UserDefaults object, using key names to build the path to the setting you want. To observe changes for all settings, register for a UserDefaults.DidChangeMessage or didChangeNotification with your UserDefaults object.
The UserDefaults type is thread-safe, and you can use the same object in multiple threads or tasks simultaneously.
Domains and settings search paths
To integrate settings from different sources, the defaults system organizes them into domains. An app defines its own custom settings, but the system defines settings that apply to all apps. Similarly, you might choose to override a specific setting temporarily to test one of your app’s features. The defaults system provides domains for each of these cases along with several others.
When you request the value of a setting, the UserDefaults object searches its domains in a specific order until it finds the value you want. The following table lists the key domains that the defaults system supports and their search order. Some domains might not be present for all apps. For example, the managed domain is present only on administrator-managed devices.
Domain | Type | Description |
|---|---|---|
Managed | persistent | This domain contains settings that an administrator provided for a managed device. The system saves these values persistently on the current device. |
volatile | This domain contains the settings you specified when launching your app from the command-line or Xcode. These keys represent temporary overrides of settings, and the system discards them after the app quits. | |
Educational managed | persistent | For managed devices in an educational institution, this domain contains any settings saved to the iCloud key-value store for that institution. The system saves these settings persistently on a server, not on the device. |
App | persistent | This domain contains the settings your app saves, either programmatically or using its settings UI. Each |
Suite | persistent | This domain contains custom settings from an app group or other app you specify at runtime. This domain is absent by default, but you can add a suite using the Addsuite(named:) method. The system saves these settings persistently on the current device. |
persistent | This domain contains keys present for all apps on the system. The system provides the keys for this domain, and apps can’t write to it. The system saves these settings persistently on the current device. | |
volatile | This domain contains system-provided default values and the default values you register for your app at launch time. Registering a set of default values prevents your code from receiving |
The system stores data for most persistent domains on the current device, and doesn’t share that data with other devices. To share settings among all of a person’s devices, save them using an NSUbiquitousKeyValueStore object instead.
Settings in managed environments
If your app supports managed environments, an administrator might configure any managed devices with a default set of settings. For example, in a computer lab or classrom environment, a teacher might set default settings that the lessons require. Apps can’t write to managed domains, so if your app encounters a managed setting, disable or hide any controls that someone might use to change that setting’s value. To determine if a setting is managed, call the objectIsForced(forKey:) or objectIsForced(forKey:inDomain:) method of your UserDefaults object.
An app running on a managed device can use NSUbiquitousKeyValueStore to share small amounts of data with the person’s other devices. Use this store for data that your app can safely share with other instances of itself. For example, a textbook app might save the current page number so that the person can continue reading from the same place on any of their devices.
For more details about managing devices, see Device Management.
Sandbox considerations
A sandboxed app cannot access or modify the settings of another app or process, with the following exceptions:
An app can modify settings for one of its app extensions.
An app can modify settings for an app group to which it belongs.
If you use the addSuite(named:) method to add the identifier for an unrelated app, the method doesn’t give you access to the other app’s settings. Instead, the system writes changes to your app’s settings, not to the third-party app’s settings.
Topics
Creating a user defaults object
Registering default settings
Getting the value of a key
bool(forKey:)integer(forKey:)float(forKey:)double(forKey:)url(forKey:)string(forKey:)stringArray(forKey:)data(forKey:)object(forKey:)array(forKey:)dictionary(forKey:)dictionaryRepresentation()
Setting the value for a key
Monitoring settings changes and issues
UserDefaults.DidChangeMessagedidChangeNotificationUserDefaults.SizeLimitExceededMessagesizeLimitExceededNotification
Removing settings values
Adding and removing search domains
Getting the domain names
Managing domain-specific values
persistentDomain(forName:)setPersistentDomain(_:forName:)volatileDomain(forName:)setVolatileDomain(_:forName:)removePersistentDomain(forName:)removeVolatileDomain(forName:)