path: root/docs/html/preview/backup/index.jd

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>
&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="9"/&gt;
    &lt;uses-sdk android:targetSdkVersion="android-MNC"/&gt;
    &lt;application ...
<strong>        android:fullBackupContent="&#64;xml/mybackupscheme"&gt;</strong>
    &lt;/application&gt;
    ...
&lt;/manifest&gt;
</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>
&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 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 only the resources specified 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
		<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>
&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="9"/&gt;
    &lt;uses-sdk android:targetSdkVersion="android-MNC"/&gt;
    &lt;application ...
<strong>        android:allowBackup="false"&gt;</strong>
    &lt;/application&gt;
    ...
&lt;/manifest&gt;
</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>&lt;PACKAGE&gt;</code> parameter:
</p>

<pre>$ 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>$ 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, clear the backup data and associated metadata 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>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>