| page.title=Auto Backup for Apps | |
| page.tags=backup, previewresources, androidm | |
| page.keywords=backup, autobackup, preview | |
| page.image=images/cards/card-auto-backup_2x.png | |
| @jd:body | |
| <div id="qv-wrapper"> | |
| <div id="qv"> | |
| <h2>In this document</h2> | |
| <ol> | |
| <li><a href="#overview">Overview</a></li> | |
| <li><a href="#configuring">Configuring Data Backup</a></li> | |
| <li><a href="#testing">Testing Backup Configuration</a></li> | |
| <li><a href="#issues">Known Issues</a></li> | |
| </ol> | |
| </div> | |
| </div> | |
| <p> | |
| 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. 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. | |
| </p> | |
| <p> | |
| 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 to opt out of | |
| automatic data backups. You can also choose to limit what data from your app is backed up. | |
| </p> | |
| <p> | |
| This document describes the new system behavior and how to specify what data is backed up for | |
| your app. | |
| </p> | |
| <h2 id="overview">Overview</h2> | |
| <p> | |
| 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. | |
| </p> | |
| <p> | |
| 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 app, a restore operation copies the backed up data into the newly installed | |
| app’s data directory. | |
| </p> | |
| <p class="note"> | |
| <strong>Note:</strong> If your app uses the legacy | |
| <a href="{@docRoot}google/backup/index.html">Android Backup service</a>, this new behavior | |
| does not apply and the existing backup behavior works as usual. | |
| </p> | |
| <h3 id="auto-exclude">Automatically Excluded Data Files</h3> | |
| <p> | |
| Not all app data should be backed up, such as temporary files and caches, so the automatic backup | |
| service excludes certain data files by default: | |
| </p> | |
| <ul> | |
| <li>Files in the directories referred to by the {@link android.content.Context#getCacheDir | |
| getCacheDir()} and {@link android.content.ContextWrapper#getCodeCacheDir getCodeCacheDir()} | |
| methods. | |
| </li> | |
| <li>Files located on external storage, unless they reside in the directory referred to by the | |
| {@link android.content.Context#getExternalFilesDir getExternalFilesDir()} | |
| method. | |
| </li> | |
| <li>Files located in the directory referred to by the | |
| {@link android.content.Context#getNoBackupFilesDir getNoBackupFilesDir()} method. | |
| </li> | |
| </ul> | |
| <h2 id="configuring">Configuring Data Backup</h2> | |
| <p> | |
| 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. | |
| </p> | |
| <h3 id="include-exclude">Including or Excluding Data</h3> | |
| <p> | |
| 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 | |
| following example: | |
| </p> | |
| <pre> | |
| <?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="MNC"/> | |
| <uses-sdk android:targetSdkVersion="MNC"/> | |
| <app ... | |
| <strong> android:fullBackupContent="@xml/mybackupscheme"></strong> | |
| </app> | |
| ... | |
| </manifest> | |
| </pre> | |
| <p> | |
| In this example code, the <code>android:fullBackupContent</code> attribute specifies an XML file, | |
| located in the <code>res/xml/</code> directory of your app development project, named | |
| <code>mybackupscheme.xml</code>. 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: | |
| </p> | |
| <pre> | |
| <?xml version="1.0" encoding="utf-8"?> | |
| <full-backup-content> | |
| <exclude domain="database" path="device_info.db"/> | |
| </full-backup-content> | |
| </pre> | |
| <p> | |
| This example backup configuration only excludes a specific database file from being backed up. | |
| All other files are backed up. | |
| </p> | |
| <h4>Backup Configuration Syntax</h4> | |
| <p> | |
| 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: | |
| </p> | |
| <pre> | |
| <full-backup-content> | |
| <include domain=["file" | "database" | "sharedpref" | "external" | "root"] path="string" /> | |
| <exclude domain=["file" | "database" | "sharedpref" | "external" | "root"] path="string" /> | |
| </full-backup-content> | |
| </pre> | |
| <p> | |
| The following elements and attributes allow you to specify the files to include and exclude from | |
| backup: | |
| </p> | |
| <ul> | |
| <li> | |
| <code><include></code>. 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 <code><include></code> tag, the system backs up <em>only the resources specified</em> | |
| with this element. | |
| </li> | |
| <li> | |
| <code><exclude></code>. 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. | |
| </li> | |
| <li> | |
| <code>domain.</code> The type of resource you want to include or exclude from backup. The valid | |
| values you can specify for this attribute include: | |
| </li> | |
| <li style="list-style: none"> | |
| <ul> | |
| <li> | |
| <code>root</code>. Specifies that the resource is in the app’s root directory. | |
| </li> | |
| <li> | |
| <code>file</code>. Corresponds to a resource in the directory returned by the | |
| {@link android.content.Context#getFilesDir getFilesDir()} method. | |
| </li> | |
| <li> | |
| <code>database</code>. Corresponds to a database returned by the | |
| {@link android.content.Context#getDatabasePath getDatabasePath()} method or by using the | |
| {@link android.database.sqlite.SQLiteOpenHelper} class. | |
| </li> | |
| <li> | |
| <code>sharedpref</code>. Corresponds to a {@link android.content.SharedPreferences} object | |
| returned by the {@link android.content.Context#getSharedPreferences getSharedPreferences()} | |
| method. | |
| </li> | |
| <li> | |
| <code>external</code>. 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. | |
| </li> | |
| <li> | |
| <code>path</code>. The file path to a resource that you want to include or exclude from | |
| backup. | |
| </li> | |
| </ul> | |
| </li> | |
| </ul> | |
| <h3 id="prohibit">Prohibiting Data Backups</h3> | |
| <p> | |
| You can choose to prevent automatic backups of any of your app data by setting the | |
| <code>android:allowBackup</code> attribute to <code>false</code> in the app element of | |
| your manifest. This setting is illustrated in the following example code: | |
| </p> | |
| <pre> | |
| <?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="MNC"/> | |
| <uses-sdk android:targetSdkVersion="MNC"/> | |
| <app ... | |
| <strong> android:allowBackup="false"></strong> | |
| </app> | |
| ... | |
| </manifest> | |
| </pre> | |
| <h2 id="testing">Testing Backup Configuration</h2> | |
| <p> | |
| Once you have created a backup configuration, you should test it to make sure your app saves data | |
| and can be restored properly. | |
| </p> | |
| <h4>Enabling Backup Logging</h4> | |
| <p> | |
| To help determine how the backup feature is parsing your XML file, enable logging before | |
| performing a test backup: | |
| </p> | |
| <pre class="noprettyprint"> | |
| $ adb shell setprop log.tag.BackupXmlParserLogging VERBOSE | |
| </pre> | |
| <h4>Testing Backup</h4> | |
| <p>To manually run a backup, first you must initialize the Backup Manager by calling the following | |
| command: | |
| </p> | |
| <pre class="noprettyprint"> | |
| $ adb shell bmgr run | |
| </pre> | |
| <p> | |
| Next, you manually backup your application using the following command, specifying the package | |
| name for your app as the <code><PACKAGE></code> parameter: | |
| </p> | |
| <pre class="noprettyprint"> | |
| $ adb shell bmgr fullbackup <PACKAGE></pre> | |
| <h4>Testing Restore</h4> | |
| <p> | |
| 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 <code><PACKAGE></code> parameter: | |
| </p> | |
| <pre class="noprettyprint"> | |
| $ adb shell bmgr restore <PACKAGE> | |
| </pre> | |
| <p class="warning"> | |
| <b>Warning:</b> This action stops your app and wipes its data before performing the restore | |
| operation. | |
| </p> | |
| <p> | |
| You initiate the restore process for your app by uninstalling and reinstalling your app. The app | |
| data is automatically restored from the cloud once the app installation is complete. | |
| </p> | |
| <h4>Troubleshooting Backups</h4> | |
| <p> | |
| If you run into issues, you can clear the backup data and associated metadata by turning backup | |
| off and on in the <strong>Settings > Backup</strong>, factory resetting the device, or by | |
| calling this command: | |
| </p> | |
| <pre>$ adb shell bmgr wipe <TRANSPORT> <PACKAGE></pre> | |
| <p> | |
| The <code><TRANSPORT></code> value must be prefixed by <code>com.google.android.gms</code>. | |
| To get the list of transports, call the following command: | |
| </p> | |
| <pre>$ adb shell bmgr list transports</pre> | |
| <h2 id="issues">Known Issues</h2> | |
| <p>The following are known issues with the automatic backup service:</p> | |
| <ul> | |
| <li><strong>Google Cloud Messaging</strong> - | |
| For apps that use Google Cloud Messaging for push notifications, there is a known issue where | |
| backing up the registration ID returned by Google Cloud Messaging registration can break push | |
| notifications for the restored app. It is important to query the API for a new | |
| registration ID after being installed on a new device, which is not be the case if the old | |
| registration ID was backed up. To avoid this, exclude the registration id from the set of backed | |
| up files. | |
| </li> | |
| </ul> |