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:
- 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="23"/> <uses-sdk android:targetSdkVersion="23"/> <application ... android:fullBackupContent="@xml/mybackupscheme"> </app> ... </manifest>
In this example, the
android:fullBackupContent attribute specifies an XML file
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,
<?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
- Files located on external storage, unless they reside in the directory to which the
- Files located in the directory to which the
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
<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
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
database: Specifies a database that the
getDatabasePath()method returns, or that the app interacts with via the
sharedpref: Specifies a
SharedPreferencesobject that the
external: Specifies that the resource is in external storage, and corresponds to a file in the directory that the
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: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
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
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
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
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>
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
$ 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.
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
To get the list of transports, execute the
$ 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.