diff options
Diffstat (limited to 'docs/html/preview/backup/index.jd')
| -rw-r--r-- | docs/html/preview/backup/index.jd | 327 |
1 files changed, 327 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..5953e30 --- /dev/null +++ b/docs/html/preview/backup/index.jd @@ -0,0 +1,327 @@ +page.title=Auto Backup for Apps +page.tags=backup, previewresources, androidm +page.keywords=backup, autobackup, preview + +@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 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="9"/> + <uses-sdk android:targetSdkVersion="android-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="9"/> + <uses-sdk android:targetSdkVersion="android-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> |