- Users often invest significant time and effort collecting data and setting preferences within + Users often invest significant time and effort creating data and setting preferences within apps. Preserving that data for users if they replace a broken device or upgrade to a new one is - an important part of ensuring a great user experience. The Android M Preview system helps ensure - a good experience for users in this circumstances by automatically backing up app data to the - cloud. + an important part of ensuring a great user experience. Devices running the Android M Preview + system help ensure a good experience for users in these circumstances by automatically backing up + app data to Google Drive. The app data is automatically restored if a user changes or upgrades a + device.
- This behavior is enabled by default for all apps installed on devices running Android M or - higher. No additional app code is required. The system provides users with the ability opt out of - automatic data backups for individual apps. You can also choose to limit what data from your app - is backed up. + Automatic backups are enabled for all apps installed on devices running the Android M Preview. No + additional app code is required. The system provides users with the ability opt out of automatic + data backups. You can also choose to limit what data from your app is backed up.
@@ -23,25 +35,31 @@ page.tags=backup your app.
-- The automatic backup feature preserves the data your app creates on a user device by uploading 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 Drive quota. During the M - Preview period, users can store up to 25MB per Android app. + 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 Drive quota. During + the M Preview period, users can store up to 25MB per Android app.
Automatic backups occur every 24 hours, when the device is idle, charging, and connected to a Wi-Fi network. When these conditions are met, the Backup Manager service uploads all available backup data to the cloud. When the user transitions to a new device, or uninstalls and reinstalls - the backed up application, a restore operation will take place, copying the backed up data into - the newly installed application’s data directory. + the backed up app, a restore operation copies the backed up data into the newly installed + app’s data directory. +
+ ++ Note: If your app uses the legacy + Android Backup service, this new behavior + does not apply and the existing backup behavior works as usual.
-Not all app data should be backed up, such as temporary files and caches, so the automatic backup @@ -49,37 +67,33 @@ page.tags=backup
getCacheDir() and
- getCodeCacheDir()
- methods.
+ getExternalFilesDir()
+ {@link android.content.Context#getExternalFilesDir getExternalFilesDir()}
method.
getNoBackupFilesDir()
- method.
+ - The data created by any app installed on an M device is backed up, except for the automatically - excluded files listed in the previous section. You can further limit and configure what data gets - backed up from your app using settings in your app manifest. + The data created by any app installed on an M Preview device is backed up, except for the + automatically excluded files listed in the previous section. You can further limit and configure + what data gets backed up from your app using settings in your app manifest.
-- Depending on what data your application needs and how you save it, you may need to set specific + 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. The automatic backup service supports setting these backup rules through use of an XML configuration file and the app manifest. In the app manifest, you can specify a backup scheme configuration file as shown in the @@ -93,31 +107,31 @@ page.tags=backup package="com.my.appexample"> <uses-sdk android:minSdkVersion="9"/> <uses-sdk android:targetSdkVersion="android-MNC"/> - <application ... + <app ... android:fullBackupContent="@xml/mybackupscheme"> - </application> + </app> ... </manifest>
- In this example code, the android:fullBackupContent attribute specifies an XML file, located in
- the res/xml/ directory of your app development project, named
- mybackupscheme.xml. This configuration file can include rules for what files are
- backed up. The following example code shows a configuration file that excludes a specific file
- from backups:
+ In this example code, the android:fullBackupContent attribute specifies an XML file,
+ located in the res/xml/ directory of your app development project, named
+ mybackupscheme.xml. This configuration file includes rules for what files are backed
+ up. The following example code shows a configuration file that excludes a specific file from
+ backups:
<?xml version="1.0" encoding="utf-8"?>
- <full-backup-content>
+<full-backup-content>
<exclude domain="database" path="device_info.db"/>
</full-backup-content>
- This backup configuration only excludes a specific database file from being backed up. All other - files are backed up. + This example backup configuration only excludes a specific database file from being backed up. + All other files are backed up.
<include>. Use this element if you want to specify a set of resources to
- back up, instead of having the system back up all data in your app by default. When you specify
- an <include> tag, the system backs up only the resources specified with this
- element.
+ <include>. Use this element if you want to specify a set of resources to
+ back up, instead of having the system back up all data in your app by default. When you specify
+ an <include> tag, the system backs up only the resources specified
+ with this element.
<exclude>. Use this element to specify a set of resources to exclude from
- backup. The system backs up all data in your app, except for resources specified with this
- element.
+ <exclude>. Use this element to specify a set of resources to exclude from
+ backup. The system backs up all data in your app, except for resources specified with this
+ element.
domain. The type of resource you want to include or exclude from backup. The valid
- values you can specify for this attribute include:
+ domain. The type of resource you want to include or exclude from backup. The valid
+ values you can specify for this attribute include:
root. Specifies that the resource is in the app’s root directory.
- root. Specifies that the resource is in the app’s root directory.
+ file. Corresponds to a resource in the directory returned by the
- getFilesDir()
- method.
- file. Corresponds to a resource in the directory returned by the
+ {@link android.content.Context#getFilesDir getFilesDir()} method.
+ database. Corresponds to a database returned by the getDatabasePath()
- method or by using the SQLiteOpenHelper
- class.
- database. Corresponds to a database returned by the
+ {@link android.content.Context#getDatabasePath getDatabasePath()} method or by using the
+ {@link android.database.sqlite.SQLiteOpenHelper} class.
+ sharedpref. Corresponds to a SharedPreferences
- object returned by the
- getSharedPreferences() method.
- sharedpref. Corresponds to a {@link android.content.SharedPreferences} object
+ returned by the {@link android.content.Context#getSharedPreferences getSharedPreferences()}
+ method.
+ external. Specifies that the resource is in external storage, and corresponds
- to a file in the directory returned by the getExternalFilesDir()
- method.
- external. Specifies that the resource is in external storage, and corresponds
+ to a file in the directory returned by the
+ {@link android.content.Context#getExternalFilesDir getExternalFilesDir()} method.
+ path. The file path to a resource that you want to include or exclude from
- backup.
- path. The file path to a resource that you want to include 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 application element of
+ android:allowBackup attribute to false in the app element of
your manifest. This setting is illustrated in the following example code:
Once you have created a backup configuration, you should test it to make sure your app saves data @@ -240,24 +248,39 @@ page.tags=backup performing a test backup:
-$ adb shell setprop log.tag.BackupXmlParserLogging VERBOSE+
+$ adb shell setprop log.tag.BackupXmlParserLogging VERBOSE +
- To manually enable a backup, call the following command, specifying the package name for your app
- as the <PACKAGE> parameter:
+
To manually run a backup, first you must initialize the Backup Manager by calling the following + command:
-$ adb shell bmgr fullbackup <PACKAGE>+
+$ adb shell bmgr run ++ +
+ Next, you manually backup your application using the following command, specifying the package
+ name for your app as the <PACKAGE> parameter:
+
+$ adb shell bmgr fullbackup <PACKAGE>+
- To manually initiate a restore after your app data is backed-up, call the following command,
+ To manually initiate a restore after your app data is backed up, call the following command,
specifying the package name for your app as the <PACKAGE> parameter:
$ adb shell bmgr restore <PACKAGE>+
+$ adb shell bmgr restore <PACKAGE> +
Warning: This action stops your app and wipes its data before performing the restore @@ -273,7 +296,9 @@ page.tags=backup
- If you run into issues, clear the backup data and associated metadata by calling this command. + If you run into issues, you can clear the backup data and associated metadata by turning backup + off and on in the Settings > Backup, factory resetting the device, or by + calling this command:
$ adb shell bmgr wipe <TRANSPORT> <PACKAGE>@@ -285,16 +310,17 @@ page.tags=backup
$ adb shell bmgr list transports-
The following are known issues with the automatic backup service: