Back up user data with Auto Backup

Auto Backup for Apps automatically backs up a user's data from apps that target and run on Android 6.0 (API level 23) or later. Android preserves app data by uploading it to the user's Google Drive—where it's protected by the user's Google Account credentials. The amount of data is limited to 25MB per user of your app and there's no charge for storing backup data. Your app can customize the backup process or opt out by disabling backups.

For an overview of Android's backup options and guidance about which data you should back up and restore, see the data backup overview.

For a walk-through on setting up Auto Backup, also try the Auto Backup for Android Codelab.

Files that are backed up

By default, Auto Backup includes files in most of the directories that are assigned to your app by the system:

Shared preferences files.
Files saved to your app's internal storage, accessed by getFilesDir() or getDir(String, int).
Files in the directory returned by getDatabasePath(String), which also includes files created with the SQLiteOpenHelper class.
Files on external storage in the directory returned by getExternalFilesDir(String).

Auto Backup excludes files in directories returned by getCacheDir(), getCodeCacheDir(), or getNoBackupFilesDir(). The files saved in these locations are only needed temporarily, or are intentionally excluded from backup operations.

You can configure your app to include and exclude particular files. For more information, see the Include and exclude files section.

Note: Android does not treat the configuration of components as user data. If your app enables or disables specific components in its manifest while it is running, do not expect AutoBackup to save and restore the configuration. To preserve the configuration state, save it in Shared Preferences and recover Shared Preferences on restore. If you want your app to save its state, store state in Shared Preferences and recover Shared Preferences on restore.

Backup location

Backup data is stored in a private folder in the user's Google Drive account, limited to 25MB per app. The saved data does not count towards the user's personal Google Drive quota. Only the most recent backup is stored. When a backup is made, the previous backup (if one exists) is deleted. The backup data can't be read by the user or other apps on the device.

Users can see a list of apps that have been backed up in the Google Drive Android app. On an Android-powered device, users can find this list in the Drive app's navigation drawer under Settings > Backup and reset > App data.

Backups from each device-setup-lifetime are stored in separate datasets as shown in the following examples:

If the user owns two devices, then a backup dataset exists for each device.
If the user factory resets a device and then sets up the device with the same account, the backup is stored in a new dataset. Obsolete datasets are automatically deleted after a period of inactivity.

Backup schedule

Backups occur automatically when all of the following conditions are met:

The user has enabled backup on the device. In Android 9, this setting is in Settings > System > Backup.
At least 24 hours have elapsed since the last backup.
The device is idle.
The device is connected to a Wi-Fi network (if the device user hasn't opted in to mobile-data backups).

In practice, these conditions occur roughly every night but a device might never back up (for example, if it never connects to a network). To conserve network bandwidth, the upload takes place only if the app data has changed.

During Auto Backup, the system shuts down the app to make sure it is no longer writing to the file system. By default, the backup system ignores apps that are running in the foreground because users would notice their apps being shut down. You can override the default behavior by setting the backupInForeground attribute to true.

To simplify testing, Android includes tools that let you manually initiate a backup of your app. For more information, see Test backup and restore.

Restore schedule

Data is restored whenever the app is installed, either from the Play store, during device setup (when the system installs previously installed apps), or from running adb install. The restore operation occurs after the APK is installed, but before the app is available to be launched by the user.

During the initial device setup wizard, the user is shown a list of available backup datasets and is asked which one to restore the data from. Whichever backup dataset is selected becomes the ancestral dataset for the device. The device can restore from either its own backups or the ancestral dataset. The device prioritize its own backup if backups from both sources are available. If the user didn't go through the device setup wizard, then the device can restore only from its own backups.

To simplify testing, Android includes tools that let you manually initiate a restore of your app. For more information, see Test backup and restore.

Enable and disable backup

Apps that target Android 6.0 (API level 23) or higher automatically participate in Auto Backup. In your app manifest file, set the boolean value android:allowBackup to enable or disable backup. The default value is true but to make your intentions clear, we recommend explicitly setting the attribute in your manifest as shown below:

<manifest ... >
    ...
    <application android:allowBackup="true" ... >
        ...
    </application>
</manifest>

You can disable backups by setting android:allowBackup to false. You might want to do this if your app can recreate its state through some other mechanism or if your app deals with sensitive information that Android shouldn't back up.

Include and exclude files

By default, the system backs up almost all app data. For more information, see Files that are backed up. This section shows you how to define custom XML rules to control what gets backed up.

In AndroidManifest.xml, add the android:fullBackupContent attribute to the <application> element. This attribute points to an XML file that contains backup rules. For example:
```
<application ...
    android:fullBackupContent="@xml/my_backup_rules">
</application>
```
Create an XML file called my_backup_rules.xml in the res/xml/ directory. Inside the file, add rules with the <include> and <exclude> elements. The following sample backs up all shared preferences except device.xml:
```
<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    <include domain="sharedpref" path="."/>
    <exclude domain="sharedpref" path="device.xml"/>
</full-backup-content>
```

XML config syntax

The XML syntax for the configuration file is shown below:

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

Inside the <full-backup-content> tag, you can define <include> and <exclude> elements:

<include> - Specifies a file or folder to backup. By default, Auto Backup includes almost all app files. If you specify an <include> element, the system no longer includes any files by default and backs up only the files specified. To include multiple files, use multiple <include> elements.
Note: Files in directories returned by getCacheDir(), getCodeCacheDir(), or getNoBackupFilesDir() are always excluded even if you try to include them.
<exclude> - Specifies a file or folder to exclude during backup. Here are some files that are typically excluded from backup:
- Files that have device specific identifiers, either issued by a server or generated on the device. For example, Google Cloud Messaging (GCM) needs to generate a registration token every time a user installs your app on a new device. If the old registration token is restored, the app may behave unexpectedly.
- Account credentials or other sensitive information. Consider asking the user to reauthenticate the first time they launch a restored app rather than allowing for storage of such information in the backup.
- Files related to app debugging, such as instant run files. To exclude instant run files, add the rule <exclude domain="file" path="instant-run"/>
- Large files that cause the app to exceed the 25MB backup quota.

Note: If your configuration file specifies both elements, then the backup contains everything captured by the <include> elements minus the resources named in the <exclude> elements. In other words, <exclude> takes precedence.

Each element must include the following two attributes:

domain - specifies the location of resource. Valid values for this attribute include the following:
- root - the directory on the filesystem where all private files belonging to this app are stored.
- file - directories returned by getFilesDir().
- database - directories returned by getDatabasePath(). Databases created with SQLiteOpenHelper are stored here.
- sharedpref - the directory where SharedPreferences are stored.
- external the directory returned by getExternalFilesDir()

Note: You cannot back up files outside of these locations.

path: Specifies a file or folder to include in or exclude from backup. Note that:
- This attribute does not support wildcard or regex syntax.
- You can use . to reference the current directory, however, you cannot reference the parent directory .. for security reasons.
- If you specify a directory, then the rule applies to all files in the directory and recursive sub-directories.

The include element can also contain the requiredFlags attribute, which the section describing how to define conditional requirements for backup section discusses in more detail.

Define device conditions required for backup

If your app saves sensitive information on the device, you can specify conditions under which your app's data is included in the user's backup. You can add the following conditions in Android 9 (API level 28) or higher:

clientSideEncryption: The user's backup is encrypted with a client-side secret. This form of encryption is enabled on devices running Android 9 or higher as long as the user has enabled backup in Android 9 or higher and has set a screen lock (PIN, pattern, or password) for their device.
deviceToDeviceTransfer: The user is transferring their backup to another device that supports local device-to-device transfer (for example, Google Pixel).

If you've upgraded your development devices to Android 9, you need to disable and then re-enable data backup after upgrading. This is because Android only encrypts backups with a client-side secret after informing users in Settings or the Setup Wizard.

To declare the inclusion conditions, set the requireFlags attribute to the desired value or values in your in the <include> elements within your set of backup rules:

my_backup_rules.xml

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    <!-- App data isn't included in user's backup
         unless client-side encryption is enabled. -->
    <include domain="file" path="."
             requireFlags="clientSideEncryption" />
<full-backup-content>

If your app implements a key-value backup system, or if you implement BackupAgent yourself, you can also apply these conditional requirements to your backup logic by performing a bitwise comparison between a BackupDataOutput object's set of transport flags and your custom backup agent's FLAG_CLIENT_SIDE_ENCRYPTION_ENABLED or FLAG_DEVICE_TO_DEVICE_TRANSFER flags.

The following code snippet shows an example use of this method:

Kotlin

class MyCustomBackupAgent : BackupAgent() {
    override fun onBackup(oldState: ParcelFileDescriptor?,
            data: BackupDataOutput?, newState: ParcelFileDescriptor?) {
        if (data != null) {
            if ((data.transportFlags and
                    FLAG_CLIENT_SIDE_ENCRYPTION_ENABLED) != 0) {
                // Client-side backup encryption is enabled.
            }

            if ((data.transportFlags and FLAG_DEVICE_TO_DEVICE_TRANSFER) != 0) {
                // Local device-to-device transfer is enabled.
            }
        }
    }

    // Implementation of onRestore() here.
}

Java

public class MyCustomBackupAgent extends BackupAgent {
    @Override
    public void onBackup(ParcelFileDescriptor oldState, BackupDataOutput data,
            ParcelFileDescriptor newState) throws IOException {
        if ((data.getTransportFlags() &
                FLAG_CLIENT_SIDE_ENCRYPTION_ENABLED) != 0) {
            // Client-side backup encryption is enabled.
        }

        if ((data.getTransportFlags() &
                FLAG_DEVICE_TO_DEVICE_TRANSFER) != 0) {
            // Local device-to-device transfer is enabled.
        }
    }

    // Implementation of onRestore() here.
}

Implement BackupAgent

Apps that implement Auto Backup do not need to implement a BackupAgent. However, you can optionally implement a custom BackupAgent. Typically, there are two reasons for doing this:

You want to receive notification of backup events such as, onRestoreFinished() or onQuotaExceeded(long, long). These callback methods are executed even if the app is not running.
You can't easily express the set of files you want to backup with XML rules. In these rare cases, you can implement a BackupAgent that overrides onFullBackup(FullBackupDataOutput) to store what you want. To retain the system's default implementation, call the corresponding method on the superclass with super.onFullBackup().

If you implement a BackupAgent, by default the system expects your app to perform key/value backup and restore. To use the file-based Auto Backup instead, set the android:fullBackupOnly attribute to true in your app's manifest.

During auto backup and restore operations, the system launches the app in a restricted mode to both prevent the app from accessing files that could cause conflicts and let the app execute callback methods in its BackupAgent. In this restricted mode, the app's main activity is not automatically launched, its Content Providers are not initialized, and the base-class Application is instantiated instead of any subclass declared in the app's manifest.

Caution: To avoid errors, make sure that the parts of your app that execute in the restricted mode (mostly your BackupAgent) do not access content providers in the same app or attempt to cast the Application object. If you cannot avoid those patterns, then consider implementing Key/Value backup or disabling backup entirely.

Your BackupAgent must implement the abstract methods onBackup() and onRestore(), which are used for key-value backup. But if you don't want to perform key-value backup, you can just leave your implementation of those methods blank.

For more information, see Extending BackupAgent.

Additional resources

For more information about Auto Backup, consult the following resources.

Codelabs

Auto Backup for Android