Skip to content

Most visited

Recently visited

navigation

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. For apps whose target SDK version is Android 6.0 (API level 23) and higher, 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.

Note: To protect user privacy, the device user must have opted in to Google services for Auto Backup to work. The Google services opt-in dialog appears when the user goes through the Setup Wizard or configures the first Google account on the device.

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:

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="23"/>
    <uses-sdk android:targetSdkVersion="23"/>
    <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:

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:

Disabling 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:

<?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="23"/>
    <uses-sdk android:targetSdkVersion="23"/>
    <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 in Settings > 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.

This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.