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 tablet 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.
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 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 tablet on the bus, opens the puzzle game and can continue playing from her last game state, which includes her new high score.
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 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:
|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:
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.
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.
Data stored in the credential vault will only transition if a user has made a device “trusted”.
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.
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.
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.
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.
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.
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.
Developers can use the Windows 8 Roaming Monitor to monitor and affect the status of their app's roaming state.
These articles provide guidance for writing secure C++ code.
These files don't roam even if they are placed in the RoamingFolder:
- Any file types that behave like folders, for example, files with the .zip and .cab extensions
- Files that have names with leading spaces
- Files that have names with these unicode characters:
e794, e795, e796, e7c7, e816, e817, e818, e81e, e826, e82b, e82c, e831, e832, e83b, e843, e854, e855, e864, e7e2, e7e3, and e7f3
- File paths (file name + extension) that are longer than 256 characters
- Empty folders
- Quickstart: Roaming application data (C#/VB/C++)
- Application data
- UX guidelines for Windows Store apps
- Guidelines for app settings
- Application data sample