Connected Storage Overview

The Connected Storage API allows Xbox One titles to save title data to local storage that is synchronized to the cloud whenever the Xbox One is connected to the internet. Saved data will be available on any other connected Xbox One after synchronization. The exact granularity of the data preserved is specific to each title. Developers are encouraged to save title state as accurately as possible to offer the best resume experience.

Developers should divide title save data into logical groupings which are independently updateable rather than writing monolithic saves. This allows titles to reduce the amount of data they write in various situations, reducing both local resource consumption and upload bandwidth usage. The API also allows titles to update more than one data item in an atomic operation which is guaranteed to succeed entirely or not take effect at all (for instance in the case of catastrophic failure mid-save).

Because Xbox One allows users to quickly switch among titles, developers should design their title to keep their current state ready to save on short notice in anticipation of receiving a Suspend event, which can happen virtually at any time. The ConnectedStorageContainer API uses RAM outside of the title reservation as the first point of storage in order to maximize title write speed during the short suspend time window. The system then persists the data to durable storage, reconciles it with any other data writes since the last upload, and schedules data uploads. Once stored and queued for upload, the system is robust to various failures such as network connectivity loss or power failure.

Xbox One Connected Storage API

Xbox One Connected Storage delivers the following features:

Provides a total of 256 MB of storage per user per TitleID/SCID.
Provides a total of 64 MB of storage per machine per TitleID/SCID.
Provides handling in case of power failures.
Data is automatically synchronized to the cloud.
Cloud backed data is available across Xbox One devices.
Platform handles cross-device syncing and conflict management independent of title.

There is a 16 MB limit on the amount of data that can be uploaded per call to SubmitUpdatesAsync.

When a title has reached its storage limit for a user or the per-machine storage, calls to SubmitUpdatesAsync will fail.

Configuring your app for connected storage

When using the Connected Storage API, all read and write operations are associated with an Xbox Live Primary Service Configuration ID (SCID), which is defined in your app’s manifest file, AppXManifest.xml, as part of the XboxLive element under the xbox.live mx:Extension element.

  <Extensions>
    <mx:Extension Category="xbox.live">
      <mx:XboxLive TitleId="<your title ID>" PrimaryServiceConfigId="<your SCID>" RequireXboxLive="<boolean indicating Live requirement>" />
    </mx:Extension>
  </Extensions>

You can also use the appx manifest to give your app permission to access game save data from another title. You will need to add the other title’s SCID to the AllowReadFrom element as shown in this example:

  <Extensions>
    <mx:Extension Category="xbox.live">
      <mx:XboxLive TitleId="<your title ID>" PrimaryServiceConfigId="<your SCID>" RequireXboxLive="<boolean indicating Live requirement>">
        <mx:ConnectedStorage>
          <mx:AllowReadFrom ServiceConfigId="<other SCID">" />
        </mx:ConnectedStorage>
      </mx:XboxLive>
    </mx:Extension>
  </Extensions>

Note that when submitting your app, you will need to provide a business justification for accessing another title’s data before it can be published.

For more information about acquiring the title ID and SCID for your app, see Setting Up Sandboxes for Xbox Live Development.

Connected storage space

At a high level, all data in the connected storage system is associated with either a user or a machine (for example, an individual Xbox One console). All data saved by an app for a particular user or machine is stored in a connected storage space.

Each user of your app gets a connected storage space with a limit of 256 MB total storage. It’s important to note that this storage is dedicated to your app alone — it is not shared with other apps.

Your app also has 64 MB of space in a local connected storage space for the machine, which is independent of users and can be accessed even if no users are signed in.

To acquire a connected storage space, your app calls ConnectedStorageSpace::GetForMachineAsync, ConnectedStorageSpace::GetForUserAsync, or ConnectedStorageSpace::GetSyncOnDemandForUserAsync.

GetForMachineAsync gets a connected storage space for your app for the current machine. This data is always kept locally and never syncs to the cloud.

GetForUserAsync gets and synchronizes a connected storage space for a user of your app. All containers in the space are synced, so this is a potentially long-running operation – especially if the user has saved data on one device and is resuming gameplay for the first time on another device. Once this operation finishes, any interactions with the connected storage space will not require any response from the cloud to complete.

GetSyncOnDemandForUserAsync gets a connected storage space for a user of your app that synchronizes containers “on demand.” The initial sync downloads only necessary metadata about containers from the cloud. This operation is fast and, under good network conditions, the user will probably not see a loading screen. These containers can then be accessed the same way as with GetForUserAsync, but a full download will not occur until the container is actually accessed (i.e. one or more blobs are read, or a blob query is performed). Containers that do not need to sync behave just like a normal connected storage space.

The decision whether to synchronize on demand or all at once is left to the app developer. If the amount of data saved by your app is small, it is strongly recommended you do a full synchronization with GetForUserAsync, as the benefits of on-demand synchronization will not be noticeable. However, if your app uses particularly large saves and the user does not need all of them to play, using GetSyncOnDemandForUserAsync may significantly improve the user experience by only fetching the data they need.

Each GetFor*Async method provides an overload method that accepts another title’s SCID in a string parameter. This will require an additional AllowReadFrom element in the appx manifest as described in the Configuring your app for connected storage section above. For user spaces, the save game data will be downloaded from the cloud if necessary. Note that this space will be read-only. You cannot write to another title’s Connected Storage. This is also indicated in the ConnectedStorageSpace::IsReadOnly property.

Containers and blobs

The connected storage container, or container for short, is the basic unit of storage. Each connected storage space can contain numerous containers.

Data is stored in containers as one or more buffers called blobs. For each container, there is a container file that contains references to the data file for each blob in the container.

To store data in a container, call ConnectedStorageContainer::SubmitUpdatesAsync, providing a map of names and blobs (Buffer objects). All changes described in a SubmitUpdatesAsync call are applied atomically, that is, either all the blobs will be updated as requested, or the entire operation will be aborted, and the container will remain in the state it was prior to the call.

A method overload of ConnectedStorageContainer.SubmitUpdatesAsync (Generic IMapView, Generic IIterable, String) allows you to provide a friendly display name for containers. Use of this overload is strongly encouraged. You can use these names in your app to provide friendly displays to the user without having to read from the container by calling ContainerInfoQueryResult::GetContainerInfo2Async.

Additionally, in the future, the platform may enable storage management on a per-container level, allowing these names to be shown to the user instead of the generic phrase “save data.”

Individual save operations that use SubmitUpdatesAsync are limited to 16 MB of data at a time.

Note The Connected Storage API requires your title to have its title ID and service configuration ID (SCID) properly configured in order to work. For more information about these required IDs, see Setting Up Sandboxes for Xbox Live Development.

If you do not set your SCID and Title ID in the Package.appxmanifest properly, your Connected Storage API calls will fail with the following error code:

NoAccess - 0x80830002 - The operation failed because the title does not have write access to the container storage space.

If you do not have the ConnectedStorage service enabled for your SCID or you do not configure and publish your Xbox Live config properly, the Connected Storage API may present UI saying that it was unable to get your latest save data. See Xbox Live Services for more documentation.

In this section

Saving Data Using Connected Storage
Describes how to save data to connected storage.

Loading Data Using Connected Storage
Describes how to read data from connected storage.

Loading Data on Demand
Describes how to read data from connected storage on demand.

Clearing Local Storage
Describes how to delete data stored on the development kit using the Connected Storage API.

Working with Connected Storage Buffers
Describes how to access a Buffer instance’s data.