W
Windows Apps Team
This blog was written by Hector Barbera and Sean McKenna, Program Managers, Developer and Ecosystem Platform, Operating Systems Group
Windows Phone 8 introduced backup and restore as a way to ease migration from one Windows Phone to another. Windows Phone 8.1 improves on this by adding critical data sets that weren’t previously backed up, including the user’s Start screen. When the user chooses to restore a Windows Phone 8.1 backup to a new phone (or an existing phone that’s been reset) all the Start screen tiles are restored to their previous position and size.
We expect the majority of apps to work just fine following restore. However, because Windows Phone supports secondary tiles, and those tiles may point to data that no longer exists after restore, there are a few cases that developers need to think about. Let’s talk about those cases and look at ways to deal with them.
Background
When we initially looked at backing up the user’s Start screen, a fundamental question arose very quickly: how do we handle secondary tiles? By definition, primary tiles contain no launch context, so all you need to do to make them functional is to restore the associated app along with the tile’s size and position. Secondary tiles, on the other hand, are more difficult. In some cases, a secondary tile is just a deep-link to a specific page in the app. For instance, a news app might allow the user to create a secondary tile for international news, and assuming the page still exists in the restored app, everything will work fine once the app is reinstalled. However, apps can also create secondary tiles that depend on user-generated data unique to the device, such as a shopping list in a task-management app. That’s when things get interesting!
Ideally, we’d be able to guarantee that all the data associated with secondary tiles would also be backed up and restored, but that’s simply not possible. For a variety of reasons, we decided not to back up app data for apps targeting Windows Phone 8. But even if we had, users still have the option to turn it off without disabling Start screen restore. We could have chosen to simply not restore secondary tiles for Windows Phone Store apps, but this would lead to a poor user experience on a new device. Furthermore, our testing found that most app tiles work fine after restore even if the data wasn’t restored. And because there isn’t a consistent way for the platform to determine whether a particular tile depends on data on the device, we had to choose between restoring everything and restoring nothing.
In the end, we chose to back up just the data that is closely associated with tiles, such as tile properties and images. Having made that call, what makes backup and restore work with local data is you! That is, to create a seamless user experience we’re asking you to ensure that your apps do the right thing following restore.
Under the hood
Tiles and their metadata live in the Package Manager, which is responsible for carrying out app installs, updates, and uninstalls. More importantly for us, it manages the app metadata needed to render the app list and the Start screen.
The Start screen restore feature, or SSR, simply acts as another client of the Package Manager. When a backup is triggered–either an automatic nightly backup or an on-demand backup requested by the user–SSR queries the Package Manager to read all the tile metadata and to locate any images associated with the tile. All this data is then backed up to OneDrive.
During a restore, SSR is invoked during device setup if the user chooses to restore a backed-up image. SSR then retrieves all the Start screen data in the backup, and creates temporary app entries in the Package Manager to store the tiles and their metadata. These temporary entries are placeholders that are shown until the actual app is downloaded and installed; if the user taps on one of them, the system navigates to the download queue in the Windows Phone Store app. The system also keeps an eye on the restore progress: if a placeholder tile has no corresponding app entry in the download queue (for example when the app is not available anymore), that tile is marked with an exclamation mark badge and will show an error message when tapped.
When an app with restored tiles is successfully installed, the Package Manager updates the temporary tiles with the real functional tiles.
Preparing your app for Start screen restore
The key to preparing your app for Start screen restore is to handle navigation requests from restored secondary tiles. This might happen before your app has had the chance to run for the first time and do any required housekeeping.
For example, let's say you have a weather app that lets the user add multiple locations, where weather data for those locations is fetched and cached in a local database. Naturally, the app allows you to pin secondary tiles for each location where the navigation URI for each includes a reference to the location’s ID in the local database, as shown in Figure 1. When the user taps one of these secondary tiles, the app navigates to a page that shows that location’s weather.
Upon restore, the app is reinstalled and all those pinned tiles are recreated on the Start screen. However, it’s possible that none of the other data will come back–perhaps the app is not eligible for data backup or the user disabled it. When launched for the first time on the new device, then, the app will likely query for tiles on the Start screen and try to update them, but will be unable to resolve their location IDs in its (now empty) local database. At this point, the app either leaves the tiles alone or makes them blank as shown in Figure 2. Moreover, if the user taps a secondary tile, there’s the potential for an unhandled exception if the app doesn’t check correctly for invalid location IDs.
At the very least, then, your app needs to gracefully handle invalid navigation URIs, perhaps taking the user to a default page instead. Ideally, the app would recognize an invalid location ID, fetch the appropriate data to populate its local database, and then navigate to that location’s page as expected. The key to doing this seamlessly is to store an identifier in the tile’s navigation URI that’s relevant beyond the lifetime of your local app data. In the case of our weather app, this might be a postcode or a latitude/longitude pair, depending on the search parameters supported by the web service providing our weather data, as shown in Figure 3.
Of course, there will be cases where no amount of advanced planning can overcome the loss of your local app data. Consider an app that relies on user authentication to a cloud service for most of its functionality. If that app creates secondary tiles that navigate to experiences assuming the user is signed in, the app needs to handle the case where credentials are no longer available following restore. Ideally, it would redirect the user to the app’s login page and then navigate to the original experience following sign-in.
The bottom line is that you should never assume that a specific prerequisite has actually occurred when navigating into your app from a secondary tile. Always check for failure cases and handle them gracefully.
How to test your app with Start restore
Having followed our advice here and feeling confident that your app is ready to handle a Start screen restore, how can you test it without submitting an update to the Windows Phone Store and resetting your phone? Fortunately, you can simulate the Start screen restore scenario by clearing your app state and then launching it from secondary tiles:
1. Deploy your app to your developer device or emulator using Visual Studio.
2. Use the app to create any state associated with secondary tiles (log in with credentials, add locations, download content, etc.)
3. Pin every type of secondary tile your app supports.
4. Verify that invoking the app from secondary tiles navigates to the expected location.
5. Close the app.
6. Using the Isolated Storage Explorer tool, clear the local folder of your app. Do this by replacing its local app data with an empty folder as follows, recreating the conditions that follow first installation of the app:
7. Launch the app from each pinned secondary tile to make sure the app works and handles any exceptions correctly.
If everything works as expected, you should be good to go.
Final notes
Following a Start screen restore, you might notice that some tiles don’t seem to update until you launch the corresponding app for the first time. In this release, we weren’t able to restore push channels and background task registrations for apps. We debated whether to return secondary tiles to a default state during restore, but decided it was better to make the tiles look like they did before at the risk of having stale data for some time until the user launches the app. As the developer of such an app, make sure you’re refreshing your push channel registrations and background task registrations every time you launch…but you were already doing that, right?
The Start screen is the most distinctive part of the Windows Phone user experience and we’re excited to save user’s customization time when they move to a new device. By doing your part as described in this post, you’ll ensure that your apps pick up right where they left off.
Continue reading...
Windows Phone 8 introduced backup and restore as a way to ease migration from one Windows Phone to another. Windows Phone 8.1 improves on this by adding critical data sets that weren’t previously backed up, including the user’s Start screen. When the user chooses to restore a Windows Phone 8.1 backup to a new phone (or an existing phone that’s been reset) all the Start screen tiles are restored to their previous position and size.
We expect the majority of apps to work just fine following restore. However, because Windows Phone supports secondary tiles, and those tiles may point to data that no longer exists after restore, there are a few cases that developers need to think about. Let’s talk about those cases and look at ways to deal with them.
Background
When we initially looked at backing up the user’s Start screen, a fundamental question arose very quickly: how do we handle secondary tiles? By definition, primary tiles contain no launch context, so all you need to do to make them functional is to restore the associated app along with the tile’s size and position. Secondary tiles, on the other hand, are more difficult. In some cases, a secondary tile is just a deep-link to a specific page in the app. For instance, a news app might allow the user to create a secondary tile for international news, and assuming the page still exists in the restored app, everything will work fine once the app is reinstalled. However, apps can also create secondary tiles that depend on user-generated data unique to the device, such as a shopping list in a task-management app. That’s when things get interesting!
Ideally, we’d be able to guarantee that all the data associated with secondary tiles would also be backed up and restored, but that’s simply not possible. For a variety of reasons, we decided not to back up app data for apps targeting Windows Phone 8. But even if we had, users still have the option to turn it off without disabling Start screen restore. We could have chosen to simply not restore secondary tiles for Windows Phone Store apps, but this would lead to a poor user experience on a new device. Furthermore, our testing found that most app tiles work fine after restore even if the data wasn’t restored. And because there isn’t a consistent way for the platform to determine whether a particular tile depends on data on the device, we had to choose between restoring everything and restoring nothing.
In the end, we chose to back up just the data that is closely associated with tiles, such as tile properties and images. Having made that call, what makes backup and restore work with local data is you! That is, to create a seamless user experience we’re asking you to ensure that your apps do the right thing following restore.
Under the hood
Tiles and their metadata live in the Package Manager, which is responsible for carrying out app installs, updates, and uninstalls. More importantly for us, it manages the app metadata needed to render the app list and the Start screen.
The Start screen restore feature, or SSR, simply acts as another client of the Package Manager. When a backup is triggered–either an automatic nightly backup or an on-demand backup requested by the user–SSR queries the Package Manager to read all the tile metadata and to locate any images associated with the tile. All this data is then backed up to OneDrive.
During a restore, SSR is invoked during device setup if the user chooses to restore a backed-up image. SSR then retrieves all the Start screen data in the backup, and creates temporary app entries in the Package Manager to store the tiles and their metadata. These temporary entries are placeholders that are shown until the actual app is downloaded and installed; if the user taps on one of them, the system navigates to the download queue in the Windows Phone Store app. The system also keeps an eye on the restore progress: if a placeholder tile has no corresponding app entry in the download queue (for example when the app is not available anymore), that tile is marked with an exclamation mark badge and will show an error message when tapped.
When an app with restored tiles is successfully installed, the Package Manager updates the temporary tiles with the real functional tiles.
Preparing your app for Start screen restore
The key to preparing your app for Start screen restore is to handle navigation requests from restored secondary tiles. This might happen before your app has had the chance to run for the first time and do any required housekeeping.
For example, let's say you have a weather app that lets the user add multiple locations, where weather data for those locations is fetched and cached in a local database. Naturally, the app allows you to pin secondary tiles for each location where the navigation URI for each includes a reference to the location’s ID in the local database, as shown in Figure 1. When the user taps one of these secondary tiles, the app navigates to a page that shows that location’s weather.
Upon restore, the app is reinstalled and all those pinned tiles are recreated on the Start screen. However, it’s possible that none of the other data will come back–perhaps the app is not eligible for data backup or the user disabled it. When launched for the first time on the new device, then, the app will likely query for tiles on the Start screen and try to update them, but will be unable to resolve their location IDs in its (now empty) local database. At this point, the app either leaves the tiles alone or makes them blank as shown in Figure 2. Moreover, if the user taps a secondary tile, there’s the potential for an unhandled exception if the app doesn’t check correctly for invalid location IDs.
At the very least, then, your app needs to gracefully handle invalid navigation URIs, perhaps taking the user to a default page instead. Ideally, the app would recognize an invalid location ID, fetch the appropriate data to populate its local database, and then navigate to that location’s page as expected. The key to doing this seamlessly is to store an identifier in the tile’s navigation URI that’s relevant beyond the lifetime of your local app data. In the case of our weather app, this might be a postcode or a latitude/longitude pair, depending on the search parameters supported by the web service providing our weather data, as shown in Figure 3.
Of course, there will be cases where no amount of advanced planning can overcome the loss of your local app data. Consider an app that relies on user authentication to a cloud service for most of its functionality. If that app creates secondary tiles that navigate to experiences assuming the user is signed in, the app needs to handle the case where credentials are no longer available following restore. Ideally, it would redirect the user to the app’s login page and then navigate to the original experience following sign-in.
The bottom line is that you should never assume that a specific prerequisite has actually occurred when navigating into your app from a secondary tile. Always check for failure cases and handle them gracefully.
How to test your app with Start restore
Having followed our advice here and feeling confident that your app is ready to handle a Start screen restore, how can you test it without submitting an update to the Windows Phone Store and resetting your phone? Fortunately, you can simulate the Start screen restore scenario by clearing your app state and then launching it from secondary tiles:
1. Deploy your app to your developer device or emulator using Visual Studio.
2. Use the app to create any state associated with secondary tiles (log in with credentials, add locations, download content, etc.)
3. Pin every type of secondary tile your app supports.
4. Verify that invoking the app from secondary tiles navigates to the expected location.
5. Close the app.
6. Using the Isolated Storage Explorer tool, clear the local folder of your app. Do this by replacing its local app data with an empty folder as follows, recreating the conditions that follow first installation of the app:
- Using the emulator:
ISETool.exe rs xd <your app's product ID> <path to an empty folder on your PC> - Using a physical phone:
ISETool.exe rs de <your app's product ID> <path to an empty folder on your PC>
7. Launch the app from each pinned secondary tile to make sure the app works and handles any exceptions correctly.
If everything works as expected, you should be good to go.
Final notes
Following a Start screen restore, you might notice that some tiles don’t seem to update until you launch the corresponding app for the first time. In this release, we weren’t able to restore push channels and background task registrations for apps. We debated whether to return secondary tiles to a default state during restore, but decided it was better to make the tiles look like they did before at the risk of having stale data for some time until the user launches the app. As the developer of such an app, make sure you’re refreshing your push channel registrations and background task registrations every time you launch…but you were already doing that, right?
The Start screen is the most distinctive part of the Windows Phone user experience and we’re excited to save user’s customization time when they move to a new device. By doing your part as described in this post, you’ll ensure that your apps pick up right where they left off.
Continue reading...