training/backup/autosyncapi.jd

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 users 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>
&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="23"/&gt;
    &lt;uses-sdk android:targetSdkVersion="23"/&gt;
    &lt;application ...
<strong>        android:fullBackupContent="&#64;xml/mybackupscheme"&gt;</strong>
    &lt;/app&gt;
    ...
&lt;/manifest&gt;
</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>
&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>

<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>
&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 in, and exclude
  from, backup:
</p>

<ul>
  <li>
  <code>&lt;include&gt;</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>&lt;include&gt;</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>&lt;include&gt;</code> elements
  </li>

  <li>
  <code>&lt;exclude&gt;</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>&lt;include&gt;</code> and <code>&lt;exclude&gt;</code> elements,
  <code>&lt;exclude&gt;</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 apps 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>
&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="23"/&gt;
    &lt;uses-sdk android:targetSdkVersion="23"/&gt;
    &lt;application ...
<strong>        android:allowBackup="false"&gt;</strong>
    &lt;/application&gt;
    ...
&lt;/manifest&gt;
</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 youre 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>&lt;PACKAGE&gt;</code> parameter to specify the package name for your app:
</p>

<pre class="no-pretty-print">
$ adb shell bmgr fullbackup &lt;PACKAGE&gt;</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>&lt;PACKAGE&gt;</code> parameter to specify the package name for your
  app:
</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 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 &gt; Backup</strong>, factory-resetting the device, or
  executing this command:
</p>

<pre>$ adb shell bmgr wipe &lt;TRANSPORT&gt; &lt;PACKAGE&gt;</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>