Auto Backup for Apps

Users often invest significant time and effort creating data and setting preferences within apps. Preserving that data for users if they replace a broken device or upgrade to a new one is an important part of ensuring a great user experience. Devices running the Android M Preview system help ensure a good experience for users in these circumstances by automatically backing up app data to Google Drive. The app data is automatically restored if a user changes or upgrades a device.

Automatic backups are enabled for all apps installed on devices running the Android M Preview. No additional app code is required. The system provides users with the ability to opt out of automatic data backups. You can also choose to limit what data from your app is backed up.

This document describes the new system behavior and how to specify what data is backed up for your app.

Overview

The automatic backup feature preserves the data your app creates on a user device by uploading it to the user’s Google Drive account and encrypting it. There is no charge to you or the user for data storage and the saved data does not count towards the user's personal Drive quota. During the M Preview period, users can store up to 25MB per Android app.

Automatic backups occur every 24 hours, when the device is idle, charging, and connected to a Wi-Fi network. When these conditions are met, the Backup Manager service uploads all available backup data to the cloud. When the user transitions to a new device, or uninstalls and reinstalls the backed up app, a restore operation copies the backed up data into the newly installed app’s data directory.

Note: If your app uses the legacy Android Backup service, this new behavior does not apply and the existing backup behavior works as usual.

Automatically Excluded Data Files

Not all app data should be backed up, such as temporary files and caches, so the automatic backup service excludes certain data files by default:

• Files in the directories referred to by the getCacheDir() and getCodeCacheDir() methods.
• Files located on external storage, unless they reside in the directory referred to by the getExternalFilesDir() method.
• Files located in the directory referred to by the getNoBackupFilesDir() method.

Configuring Data Backup

The data created by any app installed on an M Preview device is backed up, except for the automatically excluded files listed in the previous section. You can further limit and configure what data gets backed up from your app using settings in your app manifest.

Including or Excluding Data

Depending on what data your app needs and how you save it, you may need to set specific rules for including or excluding certain files or directories. The automatic backup service supports setting these backup rules through use of an XML configuration file and the app manifest. In the app manifest, you can specify a backup scheme configuration file as shown in the following example:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        package="com.my.appexample">
    <uses-sdk android:minSdkVersion="MNC"/>
    <uses-sdk android:targetSdkVersion="MNC"/>
    <app ...
        android:fullBackupContent="@xml/mybackupscheme">
    </app>
    ...
</manifest>

In this example code, the android:fullBackupContent attribute specifies an XML file, located in the res/xml/ directory of your app development project, named mybackupscheme.xml. This configuration file includes rules for what files are backed up. The following example code shows a configuration file that excludes a specific file from backups:

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    <exclude domain="database" path="device_info.db"/>
</full-backup-content>

This example backup configuration only excludes a specific database file from being backed up. All other files are backed up.

Backup Configuration Syntax

The backup service configuration allows you to specify what files to include or exclude from backup. The syntax for the data backup configuration xml file is as follows:

<full-backup-content>
    <include domain=["file" | "database" | "sharedpref" | "external" | "root"] path="string" />
    <exclude domain=["file" | "database" | "sharedpref" | "external" | "root"] path="string" />
</full-backup-content>

The following elements and attributes allow you to specify the files to include and exclude from backup:

• <include>. Use this element if you want to specify a set of resources to back up, instead of having the system back up all data in your app by default. When you specify an <include> tag, the system backs up only the resources specified with this element.
• <exclude>. Use this element to specify a set of resources to exclude from backup. The system backs up all data in your app, except for resources specified with this element.
• domain. The type of resource you want to include or exclude from backup. The valid values you can specify for this attribute include:
• • root. Specifies that the resource is in the app’s root directory.
  • file. Corresponds to a resource in the directory returned by the getFilesDir() method.
  • database. Corresponds to a database returned by the getDatabasePath() method or by using the SQLiteOpenHelper class.
  • sharedpref. Corresponds to a SharedPreferences object returned by the getSharedPreferences() method.
  • external. Specifies that the resource is in external storage, and corresponds to a file in the directory returned by the getExternalFilesDir() method.
  • path. The file path to a resource that you want to include or exclude from backup.

Prohibiting Data Backups

You can choose to prevent automatic backups of any of your app data by setting the android:allowBackup attribute to false in the app element of your manifest. This setting is illustrated in the following example code:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        package="com.my.appexample">
    <uses-sdk android:minSdkVersion="MNC"/>
    <uses-sdk android:targetSdkVersion="MNC"/>
    <app ...
        android:allowBackup="false">
    </app>
    ...
</manifest>

Testing Backup Configuration

Once you have created a backup configuration, you should test it to make sure your app saves data and can be restored properly.

Enabling Backup Logging

To help determine how the backup feature is parsing your XML file, enable logging before performing a test backup:

$ adb shell setprop log.tag.BackupXmlParserLogging VERBOSE

Testing Backup

To manually run a backup, first you must initialize the Backup Manager by calling the following command:

$ adb shell bmgr run

Next, you manually backup your application using the following command, specifying the package name for your app as the <PACKAGE> parameter:

$ adb shell bmgr fullbackup <PACKAGE>

Testing Restore

To manually initiate a restore after your app data is backed up, call the following command, specifying the package name for your app as the <PACKAGE> parameter:

$ adb shell bmgr restore <PACKAGE>

Warning: This action stops your app and wipes its data before performing the restore operation.

You initiate the restore process for your app by uninstalling and reinstalling your app. The app data is automatically restored from the cloud once the app installation is complete.

Troubleshooting Backups

If you run into issues, you can clear the backup data and associated metadata by turning backup off and on in the Settings > Backup, factory resetting the device, or by calling this command:

$ adb shell bmgr wipe <TRANSPORT> <PACKAGE>

The <TRANSPORT> value must be prefixed by com.google.android.gms. To get the list of transports, call the following command:

$ adb shell bmgr list transports

Known Issues

The following are known issues with the automatic backup service:

• Google Cloud Messaging - For apps that use Google Cloud Messaging for push notifications, there is a known issue where backing up the registration ID returned by Google Cloud Messaging registration can break push notifications for the restored app. It is important to query the API for a new registration ID after being installed on a new device, which is not be the case if the old registration ID was backed up. To avoid this, exclude the registration id from the set of backed up files.