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:
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.
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 {@code 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,
{@code device_info.db}:
<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
<exclude domain="database" path="device_info.db"/>
</full-backup-content>
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:
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
{@link android.content.Context#getFilesDir getFilesDir()} method.
database: Specifies a database that the
{@link android.content.Context#getDatabasePath getDatabasePath()} method returns, or that
the app interacts with via the {@link android.database.sqlite.SQLiteOpenHelper} class.
sharedpref: Specifies a {@link android.content.SharedPreferences} object
that the {@link android.content.Context#getSharedPreferences getSharedPreferences()}
method returns.
external: Specifies that the resource is in external storage, and corresponds
to a file in the directory that the
{@link android.content.Context#getExternalFilesDir getExternalFilesDir()} method returns.
path: Specifies the file path to a resource that you want to include in, or
exclude from, backup.
You can choose to prevent automatic backups of any of your app data by setting the
android:allowBackup attribute to false in the {@code 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>
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.
Earlier versions of Android supported a key/value-pair-based backup mechanism, in which the app defines a subclass of {@link android.app.backup.BackupAgent} and sets {@code android:backupAgent} in its app manifest. If your app used this legacy approach, you can transition to full-data backups by adding the {@code android:fullBackupOnly="true"} attribute to the {@code <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 {@link android.app.Activity#onCreate(android.os.Bundle) onCreate()} or {@link android.app.backup.BackupAgent#onFullBackup onFullBackup()}. You can also use that approach to receive a notification when a restore operation happens in {@link android.app.backup.BackupAgent#onRestoreFinished onRestoreFinished()}. If you want to retain the system's default implementation of XML include/exclude rules handling, call {@link android.app.backup.BackupAgent#onFullBackup super.onFullBackup()}.
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.
Once you have created a backup configuration, you should test it to make sure your app saves data and can restore it properly.
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
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.
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 {@code <TRANSPORT>} value.
To get the list of transports, execute the
following command:
$ adb shell bmgr list transports
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.