docs/html/preview/backup/index.jd

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>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        package="com.my.appexample"&gt;
    &lt;uses-sdk android:minSdkVersion="MNC"/&gt;
    &lt;uses-sdk android:targetSdkVersion="MNC"/&gt;
    &lt;app ...
<strong>        android:fullBackupContent="&#64;xml/mybackupscheme"&gt;</strong>
    &lt;/app&gt;
    ...
&lt;/manifest&gt;
</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>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;full-backup-content&gt;
    &lt;exclude domain="database" path="device_info.db"/&gt;
&lt;/full-backup-content&gt;
</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>
&lt;full-backup-content&gt;
    &lt;include domain=["file" | "database" | "sharedpref" | "external" | "root"] path="string" /&gt;
    &lt;exclude domain=["file" | "database" | "sharedpref" | "external" | "root"] path="string" /&gt;
&lt;/full-backup-content&gt;
</pre>

<p>
  The following elements and attributes allow you to specify the files to include and exclude from
  backup:
</p>

<ul>
  <li>
  <code>&lt;include&gt;</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>&lt;include&gt;</code> tag, the system backs up <em>only the resources specified</em>
  with this element.
  </li>

  <li>
  <code>&lt;exclude&gt;</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>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        package="com.my.appexample"&gt;
    &lt;uses-sdk android:minSdkVersion="MNC"/&gt;
    &lt;uses-sdk android:targetSdkVersion="MNC"/&gt;
    &lt;app ...
<strong>        android:allowBackup="false"&gt;</strong>
    &lt;/app&gt;
    ...
&lt;/manifest&gt;
</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>&lt;PACKAGE&gt;</code> parameter:
</p>

<pre class="noprettyprint">
$ adb shell bmgr fullbackup &lt;PACKAGE&gt;</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>&lt;PACKAGE&gt;</code> parameter:
</p>

<pre class="noprettyprint">
$ adb shell bmgr restore &lt;PACKAGE&gt;
</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 &gt; Backup</strong>, factory resetting the device, or by
  calling this command:
</p>

<pre>$ adb shell bmgr wipe &lt;TRANSPORT&gt; &lt;PACKAGE&gt;</pre>

<p>
  The <code>&lt;TRANSPORT&gt;</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>