Migrating Users' Progress Between App Versions

Warning: As of May 31, 2017, Amazon is no longer accepting new Underground app submissions. For more information, see Underground Actually Free Program FAQ – 2017 Update

Introduction

In addition to making the appropriate code changes to your app for Amazon Underground (see [Migrating Your App to Amazon Underground][underground/migrating-your-app-to-amazon-underground]), you should also implement a way to migrate the data and files associated with the non-Underground users of your app who switch to the Amazon Underground version. This page discusses the various approaches and techniques to consider using when migrating user data, state, and files from the non-Underground version to the Amazon Underground version of your app.

Determining What User Data to Migrate

When your app is published to Amazon Underground, and your existing customers download the new Amazon Underground version of your app, those customers will expect their existing accomplishments to be reflected in the Amazon Underground version. For example, game users do not want to re-start the game at Level 1, or have to re-build their acquired game currency all over again. For a notepad-style app, users expect any documents created in the non-Underground app are available in the Amazon Underground version of the app.

Generally, users expect the following data and items to be available in the Amazon Underground version of their app:

Game progress (levels achieved, high scores, rewards gained)
Individual or character progress (a level 20 knight vs. a level 1 knight)
In-app currency
Competitive progress (leaderboard standing)
Documents and image files (notes, edited images, spreadsheets)
Media (music, video, images)
Settings and preferences (colors, control layouts, default fonts, templates)

Tools for Migrating User Data

Cloud-based sync solutions provide a way to migrate user progress between different versions of your app. The following list provides an introduction to several cloud save solutions that you can use to migrate users progress from a non-Underground to an Amazon Underground version of your app. You may find that the best solution for your app is to use a combination of these options:

Amazon Web Services S3 and Cognito: Use Amazon Web Services (AWS) S3 and the Data Transfer API from the AWS Mobile SDK to create your own cloud solution, or use Amazon Cognito to sync user identity and mobile app data in the AWS Cloud. See http://aws.amazon.com/cognito/.
Amazon Drive: Amazon Drive is available as a paid service that can store user progress data, similarly to DropBox, Google Drive, and other cloud storage solutions. See Amazon Drive.
Login with Amazon: Use Login with Amazon to manage user identity support between app versions. See http://login.amazon.com/.
DropBox, Google Drive, and OneDrive: For document-centric apps, you can enable your users to log into a third party cloud storage solution to access their documents and files.
Login with Facebook: Use the Facebook SDK to provide identity support. This solution requires you create two separate Android App IDs, one for the non-Underground version, which you already have if you are using Facebook Login, and a new one for the Amazon Underground version. Each of these IDs uses the same Facebook Hash Key but will need separate package names. If you prefer to use a different identity service, other identity services generally work in similar ways. To locate your Facebook Hash Key, see https://forums.developer.amazon.com/articles/165/where-can-i-get-my-facebook-hash-key.html.
Proprietary Solutions: If you have your own proprietary cloud save solution, be aware that using the package name at run-time to access data may not work for sharing data between non-Underground and Amazon Underground versions of your app. You might need to modify your app's code to transform the Amazon Underground version of the package name to match the non-Underground version, or you may need to modify your cloud solution to accept an alternate identifier for identifying the app and version.

Migrating Locally Stored Android App Preferences, Settings, and Files

Android app preferences, settings, and files created by an app are stored locally in Shared Preferences, Internal Storage or SQLite databases. A new version of an app, such as an Amazon Underground version, does not have visibility to these data stores. To share this data, the non-Underground version of your app must store data in external storage (in the Android sense) so that the Amazon Underground version of your app can also access these items.

The following process is a suggested workflow for migrating locally stored data and files from a non-Underground version of your app to an Amazon Underground version. Remember to follow general security best practices when working with externally-stored files. Consider encrypting any user data stored externally. To migrate these data and files:

Update the non-Underground version of your app so that each time that the state is changed in private app storage, the appropriate data is also stored in external storage.
In the Amazon Underground version of your app, on startup, check external storage for shared data, and import this data into the private storage of the app. If this data import is lengthy, communicate to the user that the app is importing the previous app state.
After importing the externally stored data into the Amazon Underground version of your app, delete the data from external storage.

For more details, see the section on saving files that can be shared with other apps in the Android developer documentation (http://developer.android.com/guide/topics/data/data-storage.html). Note that the techniques described on this page also apply to Amazon devices, such as Amazon Fire tablets.

Leaving Amazon Underground

If your app leaves Amazon Underground, use the same tools and techniques to ensure that users do not lose their progress or standings achieved while your app was part of Amazon Underground. For example, if your app leaves Amazon Underground, make the same considerations to migrate users from an Amazon Underground to a non-Underground version of your app.

See the Amazon Underground Schedule for more details about leaving the Amazon Underground program.

Last updated: Jul 13, 2017