| page.title=Configuring Auto Backup for Apps |
| page.tags=backup, marshmallow, androidm |
| page.keywords=backup, autobackup |
| page.image=images/cards/card-auto-backup_2x.png |
| |
| @jd:body |
| |
| <div id="tb-wrapper"> |
| <div id="tb"> |
| <h2>This lesson teaches you to</h2> |
| <ol> |
| <li><a href="#configuring">Configure Data Backup</a></li> |
| <li><a href="#previous-androids">Support Lower Versions of Android</a></li> |
| <li><a href="#testing">Test Backup Configuration</a></li> |
| <li><a href="#issues">Handle Google Cloud Messaging</a></li> |
| </ol> |
| <h2>You should also read</h2> |
| <ul> |
| <li><a href="{@docRoot}guide/topics/data/backup.html">Data Backup</a></li> |
| <li><a href="{@docRoot}training/backup/backupapi.html">Using the Backup API</a> |
| </li> |
| </ul> |
| |
| </div> |
| </div> |
| |
| <p> |
| 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 <a href= |
| "{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">target SDK version</a> |
| 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. |
| </p> |
| |
| <p class="note"> |
| <strong>Note:</strong> 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. |
| </p> |
| |
| <p> |
| 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. |
| </p> |
| |
| <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 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. |
| </p> |
| |
| <p>Automatic backups occur when the following conditions are met:</p> |
| <ul> |
| <li>The device is idle.</li> |
| <li>The device is charging.</li> |
| <li>The device is connected to a Wi-Fi network.</li> |
| <li>At least 24 hours have elapsed since the last backup.</li> |
| </ul> |
| </p> |
| |
| <h2 id="configuring">Configure Data Backup</h2> |
| |
| <p> |
| 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 <a href="#auto-exclude"> |
| automatically excluded data files</a>. This section explains how you can use settings in |
| your app <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">manifest</a> to further |
| limit and configure what data the system backs up. |
| </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. 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: |
| </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="23"/> |
| <uses-sdk android:targetSdkVersion="23"/> |
| <application ... |
| <strong> android:fullBackupContent="@xml/mybackupscheme"></strong> |
| </app> |
| ... |
| </manifest> |
| </pre> |
| |
| <p> |
| In this example, the <code>android:fullBackupContent</code> attribute specifies an XML file |
| called {@code mybackupscheme.xml}, which resides in the <code>res/xml/</code> 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}: |
| </p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <full-backup-content> |
| <exclude domain="database" path="device_info.db"/> |
| </full-backup-content> |
| </pre> |
| |
| <h3 id="auto-exclude">Automatically excluded data files</h3> |
| |
| <p> |
| 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: |
| </p> |
| |
| <ul> |
| <li>Files in the directories to which the |
| {@link android.content.Context#getCacheDir getCacheDir()} and |
| {@link android.content.Context#getCodeCacheDir getCodeCacheDir()} methods refer. |
| </li> |
| |
| <li>Files located on external storage, unless they reside in the directory to which the |
| {@link android.content.Context#getExternalFilesDir getExternalFilesDir()} method refers. |
| </li> |
| |
| <li>Files located in the directory to which the |
| {@link android.content.Context#getNoBackupFilesDir getNoBackupFilesDir()} method refers. |
| </li> |
| </ul> |
| <h3>Backup Configuration Syntax</h3> |
| |
| <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 in, and exclude |
| from, backup: |
| </p> |
| |
| <ul> |
| <li> |
| <code><include></code>: 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 <code><include></code> element, the system backs up <em>only the resources specified</em> |
| with this element. You can specify multiple sets of resources to back up by using multiple |
| <code><include></code> elements |
| </li> |
| |
| <li> |
| <code><exclude></code>: 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 |
| <code><include></code> and <code><exclude></code> elements, |
| <code><exclude></code> takes precedence. |
| </li> |
| |
| <li> |
| <code>domain</code>: Specifies the type of resource you want to include in, |
| or exclude from, backup. Valid values for this attribute include: |
| |
| |
| |
| <ul> |
| <li> |
| <code>root</code>: Specifies that the resource is in the app’s root directory. |
| </li> |
| |
| <li> |
| <code>file</code>: Specifies a resource in the directory returned by the |
| {@link android.content.Context#getFilesDir getFilesDir()} method. |
| </li> |
| |
| <li> |
| <code>database</code>: 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. |
| </li> |
| |
| <li> |
| <code>sharedpref</code>: Specifies a {@link android.content.SharedPreferences} object |
| that the {@link android.content.Context#getSharedPreferences getSharedPreferences()} |
| method returns. |
| </li> |
| |
| <li> |
| <code>external</code>: 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. |
| </li> |
| </ul> |
| </li> |
| <li> |
| <code>path</code>: Specifies the file path to a resource that you want to include in, or |
| exclude from, backup. |
| </li> |
| |
| </li> |
| </ul> |
| |
| |
| <h3 id="disabling">Disabling 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 {@code app} element of |
| your manifest. This setting is illustrated 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="23"/> |
| <uses-sdk android:targetSdkVersion="23"/> |
| <application ... |
| <strong> android:allowBackup="false"></strong> |
| </application> |
| ... |
| </manifest> |
| </pre> |
| |
| <h2 id="previous-androids">Support Lower Versions of Android</h2> |
| |
| <p>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.</p> |
| |
| <h3 id="updating">Updating an existing app to support auto backup</h3> |
| |
| <p>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 |
| <a href="{@docRoot}guide/topics/manifest/application-element.html#agent"> |
| {@code android:backupAgent}</a> in its |
| <a href="{@docRoot}guide/topics/manifest/application-element.html">app manifest</a>. If your app |
| used this legacy approach, you can transition to full-data backups by adding the |
| {@code android:fullBackupOnly="true"} attribute to the |
| <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application/>}</a> |
| 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.</p> |
| |
| <p>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 |
| <a href="#include-exclude">XML include/exclude rules handling</a>, call |
| {@link android.app.backup.BackupAgent#onFullBackup super.onFullBackup()}.</p> |
| |
| <h3 id="lower-versions">Giving your new app support for lower versions of Android</h3> |
| |
| <p>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 |
| <a href="{@docRoot}training/backup/backupapi.html">implement the Backup API</a>.</p> |
| |
| <h2 id="testing">Test Backup Configuration</h2> |
| |
| <p> |
| Once you have created a backup configuration, you should test it to make sure your app saves data |
| and can restore it properly. |
| </p> |
| |
| |
| <h3>Enabling Backup Logging</h3> |
| |
| <p> |
| To help determine how the backup feature is parsing your XML file, enable logging before |
| performing a test backup: |
| </p> |
| |
| <pre class="no-pretty-print"> |
| $ adb shell setprop log.tag.BackupXmlParserLogging VERBOSE |
| </pre> |
| |
| <h3>Testing Backup</h3> |
| |
| <p>To manually run a backup, first initialize the Backup Manager by executing the following |
| command: |
| </p> |
| |
| <pre class="no-pretty-print"> |
| $ adb shell bmgr run |
| </pre> |
| |
| <p> |
| Next, manually back up your application using the following command. Use the |
| <code><PACKAGE></code> parameter to specify the package name for your app: |
| </p> |
| |
| <pre class="no-pretty-print"> |
| $ adb shell bmgr fullbackup <PACKAGE></pre> |
| |
| |
| <h3>Testing restore</h3> |
| |
| <p> |
| To manually initiate a restore after the system has backed up your app data, execute the following |
| command, using the <code><PACKAGE></code> parameter to specify the package name for your |
| app: |
| </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 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. |
| </p> |
| |
| |
| <h3>Troubleshooting backups</h3> |
| |
| <p> |
| If backup fails, you can clear the backup data and associated metadata either by turning backup |
| off and on in <strong>Settings > Backup</strong>, factory-resetting the device, or |
| executing this command: |
| </p> |
| |
| <pre>$ adb shell bmgr wipe <TRANSPORT> <PACKAGE></pre> |
| |
| <p> |
| You must prepend <code>com.google.android.gms</code> to the {@code <TRANSPORT>} value. |
| To get the list of <a href="{@docRoot}google/backup/index.html">transports</a>, execute the |
| following command: |
| </p> |
| |
| <pre>$ adb shell bmgr list transports</pre> |
| |
| <h2 id="gcm">Handle Google Cloud Messaging</h2> |
| |
| <p> |
| For apps that use <a href="https://developers.google.com/cloud-messaging/gcm">Google Cloud |
| Messaging</a> (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 <a href="https://developers.google.com/cloud-messaging/android/client#sample-register"> |
| query the GCM API for a new registration token</a>. 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. |
| </p> |