Configuring Auto Backup for Apps

Users frequently invest time and effort to configure apps just the way they like them. Switching to a new device can cancel out all that careful configuration. Devices running Android 6.0 and higher automatically back up app data to the cloud. The system performs this automatic backup for nearly all app data by default, and does so without your having to write any additional app code.

When a user installs your app on a new device, or reinstalls your app on one (for example, after a factory reset), the system automatically restores the app data from the cloud. This lesson provides information about how to configure the Auto Backup for Apps feature, explaining its default behavior and how to exclude data that you don't want the system to back up.

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 Google Drive quota. Each app can store up to 25MB. Once its backed-up data reaches 25MB, the app no longer sends data to the cloud. If the system performs a data restore, it uses the last data snapshot that the app had sent to the cloud.

Automatic backups occur when the following conditions are met:

• The device is idle.
• The device is charging.
• The device is connected to a Wi-Fi network.
• At least 24 hours have elapsed since the last backup.

Configure Data Backup

---

On devices running Android 6.0 (API level 23) or higher, the default system behavior is to back up almost all data that an app creates. The exception is automatically excluded data files. This section explains how you can use settings in your app manifest to further limit and configure what data the system backs up.

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. Auto Backup for Apps lets you set these backup rules through the app manifest, in which you specify a backup scheme configuration XML file. For 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"/>
    <application ...
        android:fullBackupContent="@xml/mybackupscheme">
    </app>
    ...
</manifest>

In this example, the android:fullBackupContent attribute specifies an XML file called mybackupscheme.xml, which resides in the res/xml/ directory of your app development project. This configuration file contains rules controlling which files are backed up. The following example code shows a configuration file that excludes a specific file, device_info.db:

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

Automatically excluded data files

Most apps do not need to, and in fact should not, back up all data. For example, the system should not back up temporary files and caches. For this reason, the automatic backup service excludes certain data files by default:

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

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 in, and exclude from, backup:

• <include>: Specifies a set of resources to back up, instead of having the system back up all data in your app by default. If you specify an <include> element, the system backs up only the resources specified with this element. You can specify multiple sets of resources to back up by using multiple <include> elements
• <exclude>: Specifies any data you want the system to exclude when it does a full backup. If you target the same set of resources with both the <include> and <exclude> elements, <exclude> takes precedence.
• domain: Specifies the type of resource you want to include in, or exclude from, backup. Valid values for this attribute include:
  • root: Specifies that the resource is in the app’s root directory.
  • file: Specifies a resource in the directory returned by the getFilesDir() method.
  • database: Specifies a database that the getDatabasePath() method returns, or that the app interacts with via the SQLiteOpenHelper class.
  • sharedpref: Specifies a SharedPreferences object that the getSharedPreferences() method returns.
  • external: Specifies that the resource is in external storage, and corresponds to a file in the directory that the getExternalFilesDir() method returns.
• path: Specifies the file path to a resource that you want to include in, or exclude from, backup.

Disabling data backups

You can choose to prevent automatic backups of any of your app data by setting the android:allowBackupattribute to false in the app element of your manifest. This setting is illustrated 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"/>
    <application ...
        android:allowBackup="false">
    </application>
    ...
</manifest>

Support Lower Versions of Android

---

There are two scenarios in which you may also need to support versions of Android lower than 6.0 (API level 23): You may be updating your existing app to take advantage of the new auto backup functionality in Android 6.0, while wanting to continue supporting earlier versions of Android. Or you may be releasing a new app, but want to make sure devices running on versions of Android predating 6.0 also have backup functionality.

Updating an existing app to support auto backup

Earlier versions of Android supported a key/value-pair-based backup mechanism, in which the app defines a subclass of BackupAgent and sets android:backupAgent in its app manifest. If your app used this legacy approach, you can transition to full-data backups by adding the android:fullBackupOnly="true" attribute to the <application/> element in the manifest. When running on a device with Android 5.1 (API level 22) or lower, your app ignores this value in the manifest, and continues performing backups in the previous manner.

Even if you’re not using key/value backups, you can still use the approach described above to do any custom processing in onCreate() or onFullBackup(). You can also use that approach to receive a notification when a restore operation happens in onRestoreFinished(). If you want to retain the system's default implementation of XML include/exclude rules handling, call super.onFullBackup().

Giving your new app support for lower versions of Android

If you are creating a new app that targets Android 6.0, but you also want to enable cloud backup for devices running on Android 5.1 (API level 22) and lower, you must also implement the Backup API.

Test Backup Configuration

---

Once you have created a backup configuration, you should test it to make sure your app saves data and can restore it 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 initialize the Backup Manager by executing the following command:

$ adb shell bmgr run

Next, manually back up your application using the following command. Use the <PACKAGE> parameter to specify the package name for your app:

$ adb shell bmgr fullbackup <PACKAGE>

Testing restore

To manually initiate a restore after the system has backed up your app data, execute the following command, using the <PACKAGE> parameter to specify the package name for your app:

$ adb shell bmgr restore <PACKAGE>

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

You can test automatic restore 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 backup fails, you can clear the backup data and associated metadata either by turning backup off and on inSettings > Backup, factory-resetting the device, or executing this command:

$ adb shell bmgr wipe <TRANSPORT> <PACKAGE>

You must prepend com.google.android.gms to the <TRANSPORT> value. To get the list of transports, execute the following command:

$ adb shell bmgr list transports

Handle Google Cloud Messaging

---

For apps that use Google Cloud Messaging (GCM) for push notifications, backing up the registration token that Google Cloud Messaging registration returned can cause unexpected behavior in notifications for the restored app. This is because when a user installs your app on a new device, the app must query the GCM API for a new registration token. If the old registration is present, because the system had backed it up and restored it, the app doesn't seek the new token. To prevent this issue from arising, exclude the registration token from the set of backed-up files.