<!--
{
  "availability" : [
    "iOS: 5.0.0 -",
    "iPadOS: 5.0.0 -",
    "macCatalyst: 13.1.0 -",
    "macOS: 10.7.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 9.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/NSUbiquitousKeyValueStore",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "c:objc(cs)NSUbiquitousKeyValueStore"
  },
  "title" : "NSUbiquitousKeyValueStore"
}
-->

# NSUbiquitousKeyValueStore

An iCloud-based container of key-value pairs you share among instances of your app
running on a person’s devices.

```
class NSUbiquitousKeyValueStore
```

## Overview

Use the shared `NSUbiquitousKeyValueStore` object to store settings, configuration
information, and app-specific data in a person’s iCloud account and share it among
instances of your app running on all of the person’s devices. The object stores a dictionary
of key-value pairs that you provide, and propagates that data to devices with the
same Apple account. Sharing data among different devices gives you a way to coordinate
your app’s behavior on those devices. For example, a textbook app might save the
current page number on someone’s iPhone so that the person can continue reading
from the same place on their other devices.

> Important: Don’t store personal or sensitive information in the key-value store. The
> system stores the information on disk in an unencrypted format. Store personal or sensitive
> information in the person’s Keychain instead.

Each app has a single iCloud key-value store object, which you retrieve from the
[`default`](/documentation/Foundation/NSUbiquitousKeyValueStore/default) class property. Use this same object throughout
your app to read and write values. Don’t subclass `NSUbiquitousKeyValueStore`.

> Note: To use this object, you must distribute your app through the App Store or
> Mac App Store, and you must request the [iCloud key-value store entitlement](doc://com.apple.documentation/documentation/BundleResources/Entitlements/com.apple.developer.ubiquity-kvstore-identifier)
> in your Xcode project.

The keys in the iCloud key-value store identify the item and its purpose in your app,
and the value is a data object you use to implement the corresponding behavior in your
app. Values must be property list types such as <doc://com.apple.documentation/documentation/Swift/Int64>,
<doc://com.apple.documentation/documentation/Swift/Float>, <doc://com.apple.documentation/documentation/Swift/Double>,
<doc://com.apple.documentation/documentation/Swift/Bool>, <doc://com.apple.documentation/documentation/Swift/String>,
<doc://com.apple.documentation/documentation/Foundation/NSNumber>,
[`Date`](/documentation/Foundation/Date), <doc://com.apple.documentation/documentation/Swift/Array>, or
<doc://com.apple.documentation/documentation/Swift/Dictionary>. To include other types of
objects in the key-value store, archive them to a [`Data`](/documentation/Foundation/Data)
object first and store that object instead. Prefer simple types over custom objects
whenever possible.

When you write a new value, the iCloud key-value store saves it in memory initially
and writes it to disk asynchronously later. If the device doesn’t have an active Apple
account, the changes remain only on the current device. When the person signs into
their account, the system forwards any changes to the iCloud server and reconciles
the values there with the local ones. As you make more changes, the system keeps the
local and server-based copies of the data synchronized, updating each one at appropriate times.

When a value changes on one device, iCloud forwards that change to the person’s other devices.
If your app is running on one of those other devices, the system posts
[`didChangeExternallyNotification`](/documentation/Foundation/NSUbiquitousKeyValueStore/didChangeExternallyNotification) to report the
change. Register for that notification to keep all instances of your app in sync.

When designing the keys and values you intend to save for your app, consider the
following size limitations:

- Your app can have no more than 1024 keys in the iCloud key-value store.
- The total amount of available storage space for all values is 1 megabyte.
- The maximum size for a single value is 1 megabyte. Therefore, if you associate 1
  megabyte of data with a single key, you can’t write other keys to the store.
- The maximum length for each key string is 128 characters using the UTF-16 encoding.
  Key strings don’t count against the 1 megabyte quota for values.

If you exceed any of the prescribed limits during a write operation, the operation
fails and the system doesn’t add the keys or values to the store. If a key string
exceeds the maximum length, the system raises an exception. If a write operation
would exceed your app’s quota, the system posts [`didChangeExternallyNotification`](/documentation/Foundation/NSUbiquitousKeyValueStore/didChangeExternallyNotification)
notification with the change reason set to [`NSUbiquitousKeyValueStoreQuotaViolationChange`](/documentation/Foundation/NSUbiquitousKeyValueStoreQuotaViolationChange).

## Topics

### Getting the shared instance

[`default`](/documentation/Foundation/NSUbiquitousKeyValueStore/default)

The shared iCloud key-value store object.

### Getting values

[`bool(forKey:)`](/documentation/Foundation/NSUbiquitousKeyValueStore/bool(forKey:))

Returns the Boolean value associated with the specified key.

[`double(forKey:)`](/documentation/Foundation/NSUbiquitousKeyValueStore/double(forKey:))

Returns the double value associated with the specified key.

[`longLong(forKey:)`](/documentation/Foundation/NSUbiquitousKeyValueStore/longLong(forKey:))

Returns the 64-bit integer value associated with the specified key.

[`string(forKey:)`](/documentation/Foundation/NSUbiquitousKeyValueStore/string(forKey:))

Returns the string associated with the specified key.

[`data(forKey:)`](/documentation/Foundation/NSUbiquitousKeyValueStore/data(forKey:))

Returns the data object associated with the specified key.

[`object(forKey:)`](/documentation/Foundation/NSUbiquitousKeyValueStore/object(forKey:))

Returns the object associated with the specified key.

[`array(forKey:)`](/documentation/Foundation/NSUbiquitousKeyValueStore/array(forKey:))

Returns the array associated with the specified key.

[`dictionary(forKey:)`](/documentation/Foundation/NSUbiquitousKeyValueStore/dictionary(forKey:))

Returns the dictionary object associated with the specified key.

[`dictionaryRepresentation`](/documentation/Foundation/NSUbiquitousKeyValueStore/dictionaryRepresentation)

A dictionary with all of the key-value pairs in the iCloud key-value store.

### Setting values

[`set(_:forKey:)`](/documentation/Foundation/NSUbiquitousKeyValueStore/set(_:forKey:)-8o8mq)

Sets the value of the specified key to a Boolean value.

[`set(_:forKey:)`](/documentation/Foundation/NSUbiquitousKeyValueStore/set(_:forKey:)-1xml0)

Sets the value of the specified key to a double value.

[`set(_:forKey:)`](/documentation/Foundation/NSUbiquitousKeyValueStore/set(_:forKey:)-7tt20)

Sets the value of the specified key to a 64-bit integer value.

[`set(_:forKey:)`](/documentation/Foundation/NSUbiquitousKeyValueStore/set(_:forKey:)-2rlp)

Sets the value of the specified key to a string value.

[`set(_:forKey:)`](/documentation/Foundation/NSUbiquitousKeyValueStore/set(_:forKey:)-3ga7z)

Sets the value of the specified key to a data object.

[`set(_:forKey:)`](/documentation/Foundation/NSUbiquitousKeyValueStore/set(_:forKey:)-9e3de)

Sets the value of the specified key to a property list object.

[`set(_:forKey:)`](/documentation/Foundation/NSUbiquitousKeyValueStore/set(_:forKey:)-40a8f)

Sets the value of the specified key to an array of property list objects.

[`set(_:forKey:)`](/documentation/Foundation/NSUbiquitousKeyValueStore/set(_:forKey:)-9vmlm)

Sets the value of the specified key to a dictionary of property list objects.

### Synchronizing the in-memory cache with iCloud

[`synchronize()`](/documentation/Foundation/NSUbiquitousKeyValueStore/synchronize())

Synchronizes the in-memory keys and values with the ones stored in iCloud.

### Removing keys

[`removeObject(forKey:)`](/documentation/Foundation/NSUbiquitousKeyValueStore/removeObject(forKey:))

Removes the value for the specified key from the iCloud key-value store.

### Detecting changes to values

[`didChangeExternallyNotification`](/documentation/Foundation/NSUbiquitousKeyValueStore/didChangeExternallyNotification)

Posted when the value of one or more keys changes due to incoming data from iCloud.

[`NSUbiquitousKeyValueStoreChangeReasonKey`](/documentation/Foundation/NSUbiquitousKeyValueStoreChangeReasonKey)

A key that indicates the reason why the key-value store changed.

[`NSUbiquitousKeyValueStoreChangedKeysKey`](/documentation/Foundation/NSUbiquitousKeyValueStoreChangedKeysKey)

A key that indicates which keys changed in the iCloud key-value store.

[`NSUbiquitousKeyValueStoreServerChange`](/documentation/Foundation/NSUbiquitousKeyValueStoreServerChange)

A constant that indicates a value changed in iCloud.

[`NSUbiquitousKeyValueStoreInitialSyncChange`](/documentation/Foundation/NSUbiquitousKeyValueStoreInitialSyncChange)

A constant that indicates the initial attempt to load keys and values from iCloud is in progress.

[`NSUbiquitousKeyValueStoreQuotaViolationChange`](/documentation/Foundation/NSUbiquitousKeyValueStoreQuotaViolationChange)

A constant that indicates an attempt to write data exceeded the quota limits.

[`NSUbiquitousKeyValueStoreAccountChange`](/documentation/Foundation/NSUbiquitousKeyValueStoreAccountChange)

A constant that indicates the current Apple account changed.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)