22 out of 28 rated this helpful - Rate this topic

Guidelines for roaming application data

Windows 8 automatically transitions certain application data between user devices. No heavy lifting required from the app developer. Roaming application 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 slate at home. Follow the guidelines below when you design your app to include application data roaming where appropriate.

The application data sample shows how to use the Windows Runtime application 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 slate 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 information. 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 slate 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 application data in your app is easy and does not require significant changes to code. It is best to utilize roaming application data for all size-bound data and settings that are used to preserve a user’s settings preferences as well as application session state. To make sure that your application makes the best use of this feature, you should follow these design guidelines.

DO

Do use roaming for preferences and customizations

Roam any application 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
Application view preferences

Do use roaming to let users continue a task across devices

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

Last position in the app context (e.g. a page number in book-reader app)
High score or game level information
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 information that is local to a device

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

Don't use roaming to move large datasets

There is a limit to the size of application data that each app may roam. See ApplicationData.RoamingStorageQuota | roamingStorageQuota property for more details. If an app hits this limit, none of its application data can roam until the app’s total roamed application 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 information

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 information – 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 application data for more details.

Additional considerations

Pre-requisites

Any user can benefit from roaming application data as long as they are using a Microsoft Account to log on to their device. Application 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 application 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 application 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 application data is not intended for simultaneous use of applications 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 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 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 application data should be written immediately. On the other hand, application data that changes frequently should be only written periodically at regular intervals (such as once every 5 minutes), as well as when the application is suspended. For example, a music application 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 application 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 application 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 application 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

Application data can utilize versioning of app data to upgrade from one data structure to another. The version number is different from the application 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 application data only roams between 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 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 application that has previously been utilizing various version numbers on other devices will start out with the highest version number application data available.

Testing and tools

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

Your roaming application data does not exceed the maximum size (see ApplicationData.RoamingStorageQuota | roamingStorageQuota for details).
Your files are closed and released properly.
There are at least two devices with the same data version for the application.

Security considerations

These articles provide guidance for writing secure C++ code.