Guidelines for roaming app data

Windows 8 automatically transitions certain app data between user devices. No heavy lifting required from the app developer. Roaming app data provides a great end-user experience for apps where the user utilizes more than one device, such as a PC at work and a tablet at home. Follow the guidelines below when you design your app to include app data roaming where appropriate.

The application data sample shows how to use the Windows Runtime app data APIs to store and retrieve data that is specific to each user and Windows Store app.

The user experience

If a user installs your app on a second device after she has used it on another device first, all settings and preferences made on the first device are automatically applied and made available on the second device. This provides a desirable user experience involving a minimum amount of setup work for your app on the user's second device, since everything is already configured according to user preference. Any future changes to these settings and preferences will also transition automatically, providing a uniform experience across all devices, even if devices are being upgraded or replaced over time. Consider this example scenario: Peter just bought a new Windows 8 tablet and opens his favorite calendar app. He is delighted to find that all his calendar accounts are already configured and show his calendar appointments in his familiar color preferences established on his laptop.

In addition to settings and preferences, Windows 8 also transitions session or state info. This allows end-users to continue to use an app session that was closed or abandoned on one device, when they transfer to a secondary device. Consider this example scenario: Susie was playing her favorite puzzle game just before she was heading out to work. She takes out her Windows 8 tablet on the bus, opens the puzzle game, and can continue playing from her last game state, which includes her new high score.

Design guidelines

Utilizing roaming app data in your app is easy and does not require significant changes to code. It is best to utilize roaming app data for all size-bound data and settings that are used to preserve a user’s settings preferences as well as app session state. To make sure that your app makes the best use of this feature, you should follow these design guidelines.

DO

Do use roaming for preferences and customizations

Roam any app data that the end-user would anyways choose to set on each device, such as user preferences. This could include info such as:

  • Favorite sports team (sports news app)
  • Favorite movie genre (media app)
  • Background color customization
  • App view preferences
Do use roaming to let users continue a task across devices

Roam any app data that enables users to pick up a task right where they left off on a different device. This could include info like:

  • Last position in the app context (e.g. a page number in book-reader app)
  • High score or game level info
  • Navigation back stack
  • Composing a to-do list
  • Composing email

 

DON'T

Use these guidelines to avoid creating a poor user experience.

Don’t use roaming for info that is local to a device

Sometimes, there is info that is only meaningful on a specific device—for example, a path name to a local file resource on a PC. This info should not be part of roaming app data and must remain local to a device. You may still decide to roam local info provided the app is capable of gracefully recovering in case the info is not valid on the secondary device.

Don't use roaming to move large datasets

There is a limit to the size of app data that each app may roam. See ApplicationData.RoamingStorageQuota | roamingStorageQuota property for more details. If an app hits this limit, none of its app data can roam until the app’s total roamed app data is less than the limit again. For this reason, it is best to restrict roaming to user preferences, links, and small data files. As part of your app design it is important to consider how to put a bound on larger data so as to not exceed the limit. E.g. 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 instant syncing or for frequently changing info

Windows roams app data opportunistically and doesn't guarantee an instant sync. In scenarios where a user is offline or on a high latency network, roaming could be delayed significantly. Don't build a UI that depends on a sync to occur instantly. If your app frequently changes info – for example, the up-to-the-second position in a song or movie – do not use roaming app data for this data. Instead pick a less frequent representation that still provides good user experience – e.g. current song played, current movie chapter played, etc. For important, time critical settings a special high priority settings unit is available that provides a more frequent updates. See Managing app data for more details.

 

Additional considerations

Pre-requisites

Any user can benefit from roaming app data as long as they are using a Microsoft Account to log on to their device. App data must be written via the proper mechanisms for transition between devices. Apps can transition data between any devices that utilize the same Microsoft Account Connected account. See Managing app data for more details. Users or Group Policy Administrators have the option to switch off roaming app data on a device altogether. Users who do not utilize a Microsoft Account or operate devices where roaming app data has been switched off will still be able to utilize your app regardless, but any app data will stay local to each device.

Device trust

Data stored in the credential vault will only transition if a user has made a device “trusted”.

Conflict resolution

Roaming app data is not intended for simultaneous use of apps on more than one device at a time, as it could lead to undesired and unexpected situations. In case a particular data unit has been changed on two devices, causing a conflict in the following synchronization, the system will always favor the value that was written last. This will ensure that the app utilizes the most up-to-date info. 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 transitioned.

The right time for writing data

Depending on the expected life-time of the setting, data should be written at different times. Infrequent, slowly changing app data should be written immediately. On the other hand, app data that changes frequently should be only 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.

The data changed event

Since roaming app data could change at any time, the system provides the developer with a Data Changed event. In order to properly use roaming app data it is imperative that the app listens to this event and then takes the appropriate action to update to the then current data.

Excessive usage protection

The system has various protection mechanisms in place to avoid inappropriate use of resources. In case 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 to only use increasing version numbers, since an undesired situation, including data loss, could occur when transitioning to a lower data version number that represents newer data. Please note that app data only roams between apps with the same version number. For example, devices on version 2 will transition data between themselves and devices on version 3 will do the same, but there is no automatic transition between version 2 and version 3 devices. This is the responsibility of the app at the time of version number update. Installing a new app that has previously been utilizing various version numbers on other devices will start out with the highest version number app data available.

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:

Security considerations

These articles provide guidance for writing C++ code with security in mind.

Related topics

Tasks
Quickstart: Roaming app data (JavaScript)
Quickstart: Roaming app data (C#/VB/C++)
Concepts
Accessing app data with the Windows Runtime
Guidelines
UX guidelines for Windows Store apps
Guidelines for app settings
Reference
Windows.Storage.ApplicationData
Windows.Storage.ApplicationData.RoamingSettings
Windows.Storage.ApplicationDataCompositeValue
Windows.Storage.ApplicationDataContainer
Windows.Storage.ApplicationDataContainerSettings
WinJS.Application
Samples
Application data sample

 

 

Show:
© 2014 Microsoft