Guidelines for roaming app data
The operating system 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 (Windows) 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, the operating system 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.
Utilizing roaming app data in your app is easy and doesn't require significant changes to code. It's 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 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:
|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:
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's important to 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 instant syncing or for frequently changing info
The operating system 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 – don't use roaming app data for this data. Instead, pick a less frequent representation that still provides good user experience – for example, current song played, current movie chapter played, and so on. For important, time critical settings a special high priority settings unit is available that provides more frequent updates. For more info, see Managing app data.
Roaming data across different types of devices
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 two different types of devices. To roam data across different versions of your app, provide the same Package Family Name (PFN) in the app manifest file for each version of the app. The PFN is a read-only value on the Packaging page of Manifest Designer. A PFN is based, in part, on the package name. To generate the same PFN for each version of your app, assign the same package name to both versions of the app on the Packaging page of Manifest Designer.
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. For more info, see Managing app data. 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.
Data stored in the credential vault will only transition if a user has made a device “trusted”.
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 operating 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 operating system provides the developer with a DataChanged 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 operating system has various protection mechanisms in place to avoid inappropriate use of resources. In case app data does not transition as expected, it's likely that the device has been temporarily restricted. Waiting for some time will usually resolve this situation automatically and no action is required.
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's 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 doesn't transition within a certain time frame, please check the following items and make sure that:
- Your roaming app data doesn't 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 app.
These articles provide guidance for writing C++ code with security in mind.