Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 787012b7 authored by David Friedman's avatar David Friedman
Browse files

Docs: Migrating, updating Auto Backup for Apps page for Android 6.0 release. 

Bug: 23623580

Change-Id: I1c69b162542082936f2ea1aa2a7e79ed28a478ca
parent aa32d5e5

docs/html/training/backup/auto-backup.jd

deleted100644 → 0
+0 −333
Original line number Diff line number Diff line 
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="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="#testing">Test Backup Configuration</a></li>

        <li><a href="#issues">Anticipate Known Issues</a></li>

    </ol>

    <h2>You should also read</h2>

    <ul>

      <li><a

        href="http://developer.android.com/guide/topics/data/backup.html">Data

        Backup</a></li>

    </ul>

  </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>

docs/html/training/backup/autosyncapi.jd

0 → 100644
+361 −0

File added.

Preview size limit exceeded, changes collapsed.

docs/html/training/backup/backupapi.jd

+3 −3
Original line number Diff line number Diff line
@@ -21,9 +21,9 @@ next.link=gcm.html 
    </ol>

    <h2>You should also read</h2>

    <ul>

      <li><a

        href="http://developer.android.com/guide/topics/data/backup.html">Data

        Backup</a></li>

      <li><a href="{@docRoot}guide/topics/data/backup.html">Data Backup</a></li>

      <li><a href="{@docRoot}training/backup/autosyncapi.html">Configuring Auto Backup for Apps</a>

      (Android 6.0 (API level 23) and higher)</li>

    </ul>

  </div>

</div>

docs/html/training/backup/index.jd

+22 −11
Original line number Diff line number Diff line 
page.title=Syncing to the Cloud

page.title=Backing up App Data to the Cloud

page.tags=cloud,sync,backup



trainingnavtop=true
@@ -16,21 +16,32 @@ startpage=true 
</div>

</div>



<p>By providing powerful APIs for internet connectivity, the Android framework

helps you build rich cloud-enabled apps that sync their data to a remote web

service, making sure all your devices always stay in sync, and your valuable

data is always backed up to the cloud.</p>

<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.</p>



<p>This class covers strategies for backing up data using the cloud so that

users can restore their data when installing your application on a new device.

</p>

<p>This class covers techniques for backing up data to the cloud so that

users can restore their data when recovering from a data loss (such as a factory

reset) or installing your application on a new device.</p>



<p>It is important to note that the API for cloud backup changed with the

release of Android 6.0 (API level 23). For your app to support backup both

on devices running Android 6.0, and those running Android 5.1 (API level

22) and lower, you must implement both techniques that this class explains.</p>



<h2>Lessons</h2>



<dl>

	<dt><strong><a href="autosyncapi.html">Configuring Auto Backup for Apps</a></strong></dt>

	<dd>This lesson applies to Android 6.0 (API level 23) and higher. Learn how to accomplish

  seamless app data backup and restore with zero additional lines of application code.</dd>

</dl>



<dl>

  <dt><strong><a href="backupapi.html">Using the Backup API</a></strong></dt>

  <dd>Learn how to integrate the Backup API into your Android Application, so

  that user data such as preferences, notes, and high scores update seamlessly

  across all of a user's devices</dd>

  <dd>This lesson applies to Android 5.1 (API level 22) and lower. Learn how to integrate the Backup

  API into your Android app, so all of that  app's user data, such as preferences, notes, and high

  scores, updates seamlessly across all devices linked to that Google account.</dd>

</dl>

docs/html/training/training_toc.cs

+6 −2
Original line number Diff line number Diff line
@@ -676,14 +676,18 @@ include the action bar on devices running Android 2.1 or higher." 


      <li class="nav-section">

        <div class="nav-section-header">

          <a href="<?cs var:toroot ?>training/cloudsync/index.html"

          <a href="<?cs var:toroot ?>training/backup/index.html"

             description=

             "How to sync and back up app and user data to remote web services in the

              cloud and how to restore the data back to multiple devices."

            >Syncing to the Cloud</a>

        </div>

        <ul>

          <li><a href="<?cs var:toroot ?>training/cloudsync/backupapi.html">

          <li><a href="<?cs var:toroot ?>training/backup/autosyncapi.html">

            Configuring Auto Backup for Apps

          </a>

          </li>

          <li><a href="<?cs var:toroot ?>training/backup/backupapi.html">

            Using the Backup API

          </a>

          </li>