diff options
Diffstat (limited to 'docs/html/preview/backup/index.jd')
| -rw-r--r-- | docs/html/preview/backup/index.jd | 300 |
1 files changed, 300 insertions, 0 deletions
diff --git a/docs/html/preview/backup/index.jd b/docs/html/preview/backup/index.jd new file mode 100644 index 0000000..9ef5db0 --- /dev/null +++ b/docs/html/preview/backup/index.jd @@ -0,0 +1,300 @@ +page.title=Automatic App Data Backup +page.tags=backup + +@jd:body + +<p> + Users often invest significant time and effort collecting 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. +</p> + +<p> + 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. +</p> + +<p> + This document describes the new system behavior and how to specify what data is backed up for + your app. +</p> + +<h2>Overview</h2> + +<p> + 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. +</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 application, a restore operation will take place, copying the backed up data into + the newly installed application’s data directory. +</p> + + +<h3>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 <code><a href= + "{@docRoot}reference/android/content/Context.html#getCacheDir()">getCacheDir()</a></code> and + <code><a href= + "{@docRoot}reference/android/content/ContextWrapper.html#getCodeCacheDir()">getCodeCacheDir()</a></code> + methods. + </li> + + <li>Files located on external storage, unless they reside in the directory referred to by the + <code><a href= + "{@docRoot}reference/android/content/Context.html#getExternalFilesDir(java.lang.String)">getExternalFilesDir()</a></code> + method. + </li> + + <li>Files located in the directory referred to by the <code><a href= + "{@docRoot}reference/android/content/Context.html#getNoBackupFilesDir()">getNoBackupFilesDir()</a></code> + method. + </li> +</ul> + +<h2>Configuring Data Backup</h2> + +<p> + 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. +</p> + +<h3>Including or Excluding Data</h3> + +<p> + Depending on what data your application 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="9"/> + <uses-sdk android:targetSdkVersion="android-MNC"/> + <application ... +<strong> android:fullBackupContent="@xml/mybackupscheme"></strong> + </application> + ... +</manifest> +</pre> + +<p> + In this example code, the android:fullBackupContent 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 can include 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 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 only the resources specified 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 + <code><a href="{@docRoot}reference/android/content/Context.html#getFilesDir()">getFilesDir()</a></code> + method. + </li> + + <li> + <code>database</code>. Corresponds to a database returned by the <code><a href= + "{@docRoot}reference/android/content/Context.html#getDatabasePath(java.lang.String)">getDatabasePath()</a></code> + method or by using the <code><a href= + "{@docRoot}reference/android/database/sqlite/SQLiteOpenHelper.html">SQLiteOpenHelper</a></code> + class. + </li> + + <li> + <code>sharedpref</code>. Corresponds to a <code><a href= + "{@docRoot}reference/android/content/SharedPreferences.html">SharedPreferences</a></code> + object returned by the <code><a href= + "{@docRoot}reference/android/content/Context.html#getSharedPreferences(java.lang.String,%20int)"> + getSharedPreferences()</a></code> 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 <code><a href= + "{@docRoot}reference/android/content/Context.html#getExternalFilesDir(java.lang.String)">getExternalFilesDir()</a></code> + 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>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 application 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="9"/> + <uses-sdk android:targetSdkVersion="android-MNC"/> + <application ... +<strong> android:allowBackup="false"></strong> + </application> + ... +</manifest> +</pre> + + +<h2>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>$ adb shell setprop log.tag.BackupXmlParserLogging VERBOSE</pre> + +<h4>Testing Backup</h4> + +<p> + To manually enable a backup, call the following command, specifying the package name for your app + as the <code><PACKAGE></code> parameter: +</p> + +<pre>$ 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>$ 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, clear the backup data and associated metadata 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>Known Issues</h2> + +<p>The following are known issues with the automatic backup service:</p> + +<ul> + <li>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 application. It is important to query the API for a new + registration id after being installed on a new device - which will 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>
\ No newline at end of file |