Guidelines for roaming app data

When you store app data using the roaming ApplicationData APIs, Windows replicates this data to the cloud and synchronizes the data to all other user devices on which the app is installed. Follow these guidelines when you design your Windows Store app to include roaming app data.

Should my app using roaming data?

Use roaming data to store a user's settings, preferences, and session info to create a cohesive app experience across multiple devices. Keep in mind that roaming data is associated with a user's Microsoft account. Roaming data will only sync if a user logs into her devices using the same Microsoft account and installs the app on several devices.

For example, if a user installs your app on a second device after installing it on another device, all preferences set on the first device are automatically applied to the app on the second device (assuming the user uses the same Microsoft account to log into both devices). Any future changes to these settings and preferences will also transition automatically, providing a uniform experience regardless of device. By storing session info as roaming data, you'll enable users to continue an app session that was closed or abandoned on one device when they transfer to another device.

Don't roam app data that is specific to a device. Some info is only pertinent locally, such as a path name to a local file resource. If you do decide to roam local information, make sure that the app can recover if the info isn't valid on the secondary device.

Don't roam large sets of app data. There's a limit to the amount of app data an app may roam; use RoamingStorageQuota property to get this maximum. If an app hits this limit, no data can roam until the size of the app data store no longer exceeds the limit. When you design your app, consider how to put a bound on larger data so as to not exceed the limit. For example, if saving a game state requires 10KB each, the app might only allow the user store up to 10 games.

Don't use roaming for data that relies on instant syncing. Windows doesn't guarantee an instant sync; roaming could be significantly delayed if a user is offline or on a high latency network. Ensure that your UI doesn't depend on instant syncing.

Don't use roam frequently changing data. For example, if your app tracks frequently changing info, such as the position in a song by second, don't store this as roaming app data. Instead, pick a less frequent representation that still provides a good user experience, like the currently playing song.

Additional usage guidance

Roaming pre-requisites

Any user can benefit from roaming app data if they use a Microsoft account to log on to their device. However, users and group policy administrators can switch off roaming app data on a device at any time.
If a user chooses not to use a Microsoft account or disables roaming data capabilities, she will still be able to use your app, but app data be local to each device.

Data stored in the PasswordVault will only transition if a user has made a device “trusted”. If a device isn't trusted, data secured in this vault will not roam.

Conflict resolution

Roaming app data is not intended for simultaneous use on more than one device at a time.
If a conflict arises during synchronization because a particular data unit was changed on two devices, the system will always favor the value that was written last. This ensures that the app utilizes the most up-to-date information.
If the data unit is a setting composite, conflict resolution will still occur on the level of the setting unit, which means that the composite with the latest change will be synchronized.

When to write data

Depending on the expected lifetime of the setting, data should be written at different times. Infrequently or slowly changing app data should be written immediately.
However, app data that changes frequently should only be written periodically at regular intervals (such as once every 5 minutes), as well as when the app is suspended.
For example, a music app might write the “current song” settings whenever a new song starts to play, however, the actual position in the song should only be written on suspend.

Excessive usage protection

The system has various protection mechanisms in place to avoid inappropriate use of resources. If app data does not transition as expected, it is likely that the device has been temporarily restricted. Waiting for some time will usually resolve this situation automatically and no action is required.

Versioning

App data can utilize versioning to upgrade from one data structure to another. The version number is different from the app version and can be set at will. Although not enforced, it is highly recommended that you use increasing version numbers, since undesirable complications (including data loss)could occur if you try to transition to a lower data version number that represents newer data.

App data only roams between installed apps with the same version number. For example, devices on version 2 will transition data between each other and devices on version 3 will do the same, but no roaming will occur between a device running version 2 and a device running version 3.
If you install a new app that utilized various version numbers on other devices, the newly installed app will sync the app data associated with the highest version number.

Testing and tools

Developers can lock their device in order to trigger a synchronization of roaming app data.
If it seems that the app data does not transition within a certain time frame, please check the following items and make sure that:

Roaming data between a Windows Store app and a Windows Phone Store app

If you publish two versions of your app - a version for Windows Store and a version for Windows Phone - you can roam app data across the apps running on the two different types of devices. To roam data across different versions of your app on different types of devices, assign the same Package Family Name (PFN) to each version of the app.