Как настроить автоматическое резервное копирование пользовательских данных

Автоматическое копирование в облако для приложений автоматически создает резервные копии данных пользователей из приложений, предназначенных для Android 6.0 (уровень API 23) или более поздней версии и работающих на устройствах с этой ОС. Android сохраняет данные приложений, загружая их на Google Диск пользователя, где они защищены учетными данными аккаунта Google. На устройствах с Android 9 или более поздней версии резервная копия защищена сквозным шифрованием с использованием PIN-кода, графического ключа или пароля. Каждое приложение может выделить до 25 МБ данных резервной копии на пользователя. Плата за хранение резервных копий не взимается. Вы можете настроить процесс резервного копирования или отключить его.

Обзор вариантов резервного копирования в Android и рекомендации по выбору данных для резервного копирования и восстановления приведены в обзоре резервного копирования данных.

файлы, для которых созданы резервные копии;

По умолчанию автоматическое резервное копирование включает файлы в большинстве каталогов, назначенных вашему приложению системой:

  • Файлы общих настроек

  • Файлы, сохраненные во внутреннем хранилище приложения, к которым можно получить доступ с помощью getFilesDir() или getDir(String, int).

  • Файлы в каталоге, возвращенном методом getDatabasePath(String), в том числе файлы, созданные с помощью класса SQLiteOpenHelper.

  • Файлы во внешнем хранилище в каталоге, возвращенном методом getExternalFilesDir(String).

Автозагрузка не распространяется на файлы в каталогах, возвращаемых методами getCacheDir(), getCodeCacheDir() и getNoBackupFilesDir(). Файлы, сохраненные в этих папках, нужны только временно и намеренно исключены из резервного копирования.

Вы можете настроить приложение так, чтобы оно включало или исключало определенные файлы. Подробнее об этом рассказывается в разделе Включение и исключение файлов.

Местоположение резервной копии

Резервные копии хранятся в личной папке в аккаунте Google Диска пользователя. На каждое приложение выделяется не более 25 МБ. Сохраненные данные не учитываются в квоте на хранение в Google Диске. Хранится только последняя резервная копия. При создании новой резервной копии предыдущая удаляется. Резервные копии данных недоступны для чтения пользователю и другим приложениям на устройстве.

Пользователи могут посмотреть список приложений, для которых созданы резервные копии, в приложении "Google Диск" для Android. На устройстве Android этот список можно найти на панели навигации приложения "Диск" в разделе Настройки > Резервное копирование и сброс.

Резервные копии, созданные в течение каждого периода настройки устройства, хранятся в отдельных наборах данных, как описано в следующих примерах:

  • Если у пользователя два устройства, то для каждого из них существует набор данных резервной копии.

  • Если пользователь сбросит настройки устройства, а затем настроит его с тем же аккаунтом, резервная копия будет сохранена в новом наборе данных. Устаревшие наборы данных автоматически удаляются после периода бездействия.

Расписание резервного копирования

Резервное копирование выполняется автоматически, если соблюдены все следующие условия:

  • Пользователь включил резервное копирование на устройстве. В Android 9 этот параметр находится в разделе Настройки > Система > Резервное копирование.
  • С момента последнего резервного копирования прошло не менее 24 часов.
  • Устройство бездействует.
  • Устройство подключено к сети Wi-Fi (если пользователь не разрешил резервное копирование через мобильный интернет).

На практике эти условия выполняются примерно каждую ночь, но устройство может никогда не создавать резервные копии (например, если оно никогда не подключается к сети). Чтобы не перегружать сеть, загрузка выполняется, только если данные приложения изменились.

Во время автоматического резервного копирования система закрывает приложение, чтобы оно не записывало данные в файловую систему. По умолчанию система резервного копирования игнорирует приложения, работающие в активном режиме, чтобы не мешать пользователю. Вы можете переопределить режим работы по умолчанию, задав для атрибута android:backupInForeground значение true.

Чтобы упростить тестирование, в Android есть инструменты, позволяющие вручную запустить резервное копирование приложения. Подробнее о том, как протестировать резервное копирование и восстановление…

Восстановить расписание

Данные восстанавливаются при установке приложения из Google Play, во время настройки устройства (когда система устанавливает ранее установленные приложения) или при запуске adb install. Восстановление происходит после установки APK-файла, но до того, как пользователь сможет запустить приложение.

Во время первоначального мастера настройки устройства пользователю показывается список доступных наборов данных резервных копий и предлагается выбрать, из какого набора восстановить данные. Выбранный набор данных резервной копии становится исходным набором данных для устройства. Устройство может восстанавливать данные из собственных резервных копий или из набора данных предка. Если доступны резервные копии из обоих источников, устройство отдает приоритет собственной резервной копии. Если пользователь не прошел мастер настройки устройства, то устройство можно восстановить только из его собственных резервных копий.

Чтобы упростить тестирование, в Android есть инструменты, позволяющие вручную запустить восстановление приложения. Подробнее о тестировании резервного копирования и восстановления…

Как включить или отключить копирование в облако

Приложения, предназначенные для Android 6.0 (API уровня 23) или более поздней версии, автоматически участвуют в автоматическом резервном копировании. В файле манифеста приложения задайте логическое значение android:allowBackup, чтобы включить или отключить резервное копирование. Значение по умолчанию – true, но мы рекомендуем явно задать атрибут в манифесте, как показано в примере ниже.

<manifest ... >
    ...
    <application android:allowBackup="true" ... >
        ...
    </application>
</manifest>

Чтобы отключить резервное копирование, задайте для правила android:allowBackup значение false. Это может быть полезно, если ваше приложение может воссоздать свое состояние с помощью какого-либо другого механизма или если ваше приложение работает с конфиденциальной информацией.

Как включить или исключить файлы

По умолчанию система создает резервные копии почти всех данных приложений. Подробнее о файлах, для которых создаются резервные копии…

Вы можете выбрать, какие данные будут включены в резервную копию, в зависимости от типа переноса. Автоматическое резервное копирование поддерживает облачное резервное копирование на Google Диск и прямую передачу данных с устройства на устройство. Способы настройки зависят от версии Android и значения targetSdkVersion вашего приложения.

Как управлять резервным копированием на устройствах с Android 11 и более ранними версиями ОС

Выполните действия, описанные в этом разделе, чтобы указать, какие файлы будут копироваться в облако на устройствах с Android 11 (уровень API 30) или более ранней версии.

  1. В файле AndroidManifest.xml добавьте атрибут android:fullBackupContent в элемент <application>, как показано в примере ниже. Этот атрибут указывает на XML-файл, содержащий правила резервного копирования.

    <application ...
        android:fullBackupContent="@xml/backup_rules">
    </application>
    
  2. Создайте XML-файл с названием @xml/backup_rules в каталоге res/xml/. Добавьте в этот файл правила с элементами <include> и <exclude>. В следующем примере создается резервная копия всех общих настроек, кроме device.xml:

    <?xml version="1.0" encoding="utf-8"?>
    <full-backup-content>
      <include domain="sharedpref" path="."/>
      <exclude domain="sharedpref" path="device.xml"/>
    </full-backup-content>
    

Задайте условия, необходимые для резервного копирования

Если ваше приложение сохраняет на устройстве конфиденциальную информацию, вы можете указать условия, при которых данные приложения будут включены в резервную копию пользователя. В Android 9 (уровень API 28) или более поздней версии можно добавить следующие условия:

Если вы обновили устройства для разработки до Android 9, вам нужно отключить, а затем снова включить резервное копирование данных. Это связано с тем, что Android шифрует резервные копии с помощью секрета на стороне клиента только после того, как пользователь будет проинформирован об этом в настройках или мастере настройки.

Чтобы объявить условия включения, задайте для атрибута requireFlags одно или несколько значений в элементах <include> в наборе резервных правил:

backup_rules.xml

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    <!-- App data isn't included in user's backup
         unless client-side encryption is enabled. -->
    <include domain="file" path="."
             requireFlags="clientSideEncryption" />
</full-backup-content>

Если в вашем приложении реализована система резервного копирования пар "ключ-значение" или вы самостоятельно реализуете BackupAgent, вы также можете применить эти условные требования к логике резервного копирования, выполнив побитовое сравнение набора флагов транспорта объекта BackupDataOutput и флагов FLAG_CLIENT_SIDE_ENCRYPTION_ENABLED или FLAG_DEVICE_TO_DEVICE_TRANSFER вашего пользовательского агента резервного копирования.

Ниже приведен пример использования этого метода.

Kotlin

class CustomBackupAgent : BackupAgent() {
    override fun onBackup(
        oldState: ParcelFileDescriptor?,
        data: BackupDataOutput?,
        newState: ParcelFileDescriptor?
    ) {
        if (data != null) {
            if ((data.transportFlags and
                    FLAG_CLIENT_SIDE_ENCRYPTION_ENABLED) != 0) {
                // Client-side backup encryption is enabled.
            }

            if ((data.transportFlags and FLAG_DEVICE_TO_DEVICE_TRANSFER) != 0) {
                // Local device-to-device transfer is enabled.
            }
        }
    }

    // Implementation of onRestore() here.
}

Java

public class CustomBackupAgent extends BackupAgent {
    @Override
    public void onBackup(
        ParcelFileDescriptor oldState,
        BackupDataOutput data,
        ParcelFileDescriptor newState
    ) throws IOException {
        if ((data.getTransportFlags() &
                FLAG_CLIENT_SIDE_ENCRYPTION_ENABLED) != 0) {
            // Client-side backup encryption is enabled.
        }

        if ((data.getTransportFlags() &
                FLAG_DEVICE_TO_DEVICE_TRANSFER) != 0) {
            // Local device-to-device transfer is enabled.
        }
    }

    // Implementation of onRestore() here.
}

Как управлять резервным копированием на устройствах с Android 12 или более поздней версии

Если ваше приложение предназначено для Android 12 (уровень API 31) или более поздней версии, следуйте инструкциям в этом разделе, чтобы указать, какие файлы будут копироваться на устройствах с Android 12 или более поздней версии.

  1. В файле AndroidManifest.xml добавьте атрибут android:dataExtractionRules в элемент <application>, как показано в примере ниже. Этот атрибут указывает на XML-файл, содержащий правила резервного копирования.

    <application ...
        android:dataExtractionRules="backup_rules.xml">
    </application>
    
  2. Создайте XML-файл с названием backup_rules.xml в каталоге res/xml/. Добавьте в этот файл правила с элементами <include> и <exclude>. В следующем примере создается резервная копия всех общих настроек, кроме device.xml:

    <?xml version="1.0" encoding="utf-8"?>
    <data-extraction-rules>
      <cloud-backup [disableIfNoEncryptionCapabilities="true|false"]>
        <include domain="sharedpref" path="."/>
        <exclude domain="sharedpref" path="device.xml"/>
      </cloud-backup>
    </data-extraction-rules>
    

Синтаксис XML-файла конфигурации

Синтаксис XML для файла конфигурации зависит от версии Android, для которой предназначено и на которой работает ваше приложение.

Android 11 или более ранней версии

Используйте следующий синтаксис XML для файла конфигурации, который управляет резервным копированием для устройств с Android 11 или более ранней версии.

<full-backup-content>
    <include domain=["file" | "database" | "sharedpref" | "external" |
                     "root" | "device_file" | "device_database" |
                     "device_sharedpref" | "device_root" ] path="string"
    requireFlags=["clientSideEncryption" | "deviceToDeviceTransfer"] />
    <exclude domain=["file" | "database" | "sharedpref" | "external" |
                     "root" | "device_file" | "device_database" |
                     "device_sharedpref" | "device_root" ] path="string" />
</full-backup-content>

Android 12 или более поздней версии;

Если ваше приложение поддерживает Android 12 (уровень API 31) или более позднюю версию, используйте следующий синтаксис XML для файла конфигурации, который управляет резервным копированием для устройств с Android 12 или более поздней версией.

<data-extraction-rules>
  <cloud-backup [disableIfNoEncryptionCapabilities="true|false"]>
    ...
    <include domain=["file" | "database" | "sharedpref" | "external" |
                     "root" | "device_file" | "device_database" |
                     "device_sharedpref" | "device_root" ] path="string"/>
    ...
    <exclude domain=["file" | "database" | "sharedpref" | "external" |
                     "root" | "device_file" | "device_database" |
                     "device_sharedpref" | "device_root" ] path="string"/>
    ...
  </cloud-backup>
  <device-transfer>
    ...
    <include domain=["file" | "database" | "sharedpref" | "external" |
                     "root" | "device_file" | "device_database" |
                     "device_sharedpref" | "device_root" ] path="string"/>
    ...
    <exclude domain=["file" | "database" | "sharedpref" | "external" |
                     "root" | "device_file" | "device_database" |
                     "device_sharedpref" | "device_root" ] path="string"/>
    ...
  </device-transfer>
  <cross-platform-transfer platform="ios">
    ...
    <include domain=["file" | "database" | "sharedpref" | "external" |
                     "root" | "device_file" | "device_database" |
                     "device_sharedpref" | "device_root" ] path="string"/>
    ...
    <exclude domain=["file" | "database" | "sharedpref" | "external" |
                     "root" | "device_file" | "device_database" |
                     "device_sharedpref" | "device_root" ] path="string"/>
    ...
    <platform-specific-params bundleId="string" teamId="string" contentVersion="string"/>
    ...
  </cross-platform-transfer>
</data-extraction-rules>

Каждый раздел конфигурации (<cloud-backup>, <device-transfer>, <cross-platform-transfer>) содержит правила, которые применяются только к этому типу переноса. Это позволяет, например, исключить файл или каталог из резервных копий Google Диска, но при этом передавать его во время передачи с устройства на устройство (D2D) или межплатформенной передачи. Это удобно, если у вас есть файлы, которые слишком велики для резервного копирования в облако, но могут быть без проблем перенесены между устройствами.

Если для определенного режима резервного копирования нет правил, например отсутствует раздел <device-transfer>, этот режим полностью включен для всего контента, кроме каталогов no-backup и cache, как описано в разделе Файлы, для которых создаются резервные копии.

Чтобы резервное копирование выполнялось только при наличии шифрования, например когда у пользователя заблокирован экран, в разделе <cloud-backup> можно установить флажок disableIfNoEncryptionCapabilities. Если задать это ограничение, резервные копии не будут отправляться в облако, если устройство пользователя не поддерживает шифрование. Однако, поскольку при переносе с устройства на устройство данные не отправляются на сервер, он будет работать даже на устройствах, которые не поддерживают шифрование.

Синтаксис для включения и исключения элементов

Внутри тегов <full-backup-content>, <cloud-backup> и <device-transfer> (в зависимости от версии Android на устройстве и targetSDKVersion вашего приложения) можно определить элементы <include> и <exclude>:

<include>

Указывает файл или папку для резервного копирования. По умолчанию автоматическое копирование в облако включает почти все файлы приложений. Если вы укажете элемент <include>, система больше не будет включать файлы по умолчанию и создаст резервную копию только указанных файлов. Чтобы добавить несколько файлов, используйте несколько элементов <include>.

В Android 11 и более ранних версиях этот элемент также может содержать атрибут requireFlags, который подробно описан в разделе Как задать условные требования для резервного копирования.

Файлы в каталогах, возвращаемых getCacheDir(), getCodeCacheDir() или getNoBackupFilesDir(), всегда исключаются, даже если вы попытаетесь их включить.

<exclude>

Указывает файл или папку, которые нужно исключить из резервного копирования. Вот некоторые файлы, которые обычно исключаются из резервной копии:

  • Файлы, содержащие идентификаторы устройств, которые выданы сервером или сгенерированы на устройстве. Например, Firebase Cloud Messaging (FCM) генерирует токен регистрации каждый раз, когда пользователь устанавливает ваше приложение на новое устройство. Если восстановить старый токен регистрации, приложение может работать некорректно.

  • Файлы, связанные с отладкой приложения.

  • Большие файлы, из-за которых приложение превышает квоту на резервное копирование в 25 МБ.

Каждый элемент <include> и <exclude> должен включать следующие два атрибута:

domain

Указывает местоположение ресурса. Допустимые значения для этого атрибута:

  • root – каталог в файловой системе, где хранятся все личные файлы, принадлежащие этому приложению.
  • file: каталоги, возвращенные getFilesDir().
  • database: каталоги, возвращенные getDatabasePath(). Здесь хранятся базы данных, созданные с помощью SQLiteOpenHelper.
  • sharedpref – каталог, в котором хранятся SharedPreferences.
  • external – каталог, возвращаемый getExternalFilesDir().
  • device_root: аналогично root, но для хранилища, защищенного устройством.
  • device_file: аналогично file, но для хранилища, защищенного устройством.
  • device_database: аналогично database, но для хранилища, защищенного устройством.
  • device_sharedpref – аналогично sharedpref, но для хранилища, защищенного устройством.
path

Указывает файл или папку, которые нужно включить в резервную копию или исключить из нее. Обратите внимание на следующее:

  • В этом атрибуте не поддерживаются подстановочные знаки и регулярные выражения.
  • Вы можете ссылаться на текущий каталог с помощью ./, но не можете ссылаться на родительский каталог, например с помощью .., из соображений безопасности.
  • Если указать каталог, правило будет применяться ко всем файлам в каталоге и рекурсивных подкаталогах.

Как настроить межплатформенную передачу данных

Начиная с Android 16 QPR2 (API уровня 36.1) вы можете настроить автоматическое резервное копирование для передачи данных на устройства, не работающие на Android, и с них. Для этого добавьте элемент <cross-platform-transfer> в конфигурацию <data-extraction-rules>, как показано в разделе Синтаксис для Android 12 и более поздних версий. Целевую платформу необходимо указать с помощью обязательного атрибута platform. Единственное допустимое значение – ios.

В этом разделе можно использовать стандартные элементы <include> и <exclude>, как описано в разделе Синтаксис элементов include и exclude, чтобы указать, какие данные нужно перенести.

Кроме того, необходимо добавить элемент <platform-specific-params>, чтобы система могла сопоставить ваше приложение с соответствующим приложением на целевой платформе. У этого элемента есть следующие обязательные атрибуты:

  • bundleId – идентификатор пакета приложения на другой платформе (например, идентификатор пакета приложения для iOS).
  • teamId – идентификатор команды приложения на другой платформе (например, идентификатор команды приложения для iOS).
  • contentVersion – строка версии, которую вы определяете и которая связана с экспортируемым форматом данных.

Атрибуты bundleId и teamId используются для проверки целостности данных и правильного сопоставления приложений. Они гарантируют, что при экспорте данные будут переданы только в указанное приложение на другой платформе, а при импорте приложение Android получит данные только из этого приложения.

Если вам нужен более точный контроль над преобразованием и передачей данных, чем обеспечивают правила XML, вы можете реализовать собственный класс BackupAgent и использовать межплатформенные API для передачи данных.

Сопоставление файлов для переноса данных iOS

При переносе файлов на iOS значения domain и path Android, указанные в правилах <include>, сопоставляются с определенной структурой каталогов. В таблице ниже показаны пути назначения на iOS относительно корневого каталога назначения переноса на основе domain Android.

Android-domain Путь на iOS (относительно корневой папки переноса)
root app/
file app/files/
database app/databases/
sharedpref app/shared_prefs/
external external/files/
device_root device/app/
device_file device/app/files/
device_database device/app/databases/
device_sharedpref device/app/shared_prefs/

Например, файл, включенный в <include domain="file" path="my_settings.txt"/>, будет доступен на устройстве iOS по пути app/files/my_settings.txt относительно корневой папки назначения.

Реализация BackupAgent

Приложениям, в которых реализовано автоматическое копирование в облако, не требуется BackupAgent. Однако вы можете реализовать собственный метод BackupAgent. Обычно это делается по двум причинам:

  • Вы хотите получать уведомления о событиях резервного копирования, таких как onRestoreFinished() и onQuotaExceeded(). Эти методы обратного вызова выполняются, даже если приложение не запущено.

  • Вы не можете легко выразить набор файлов, для которых хотите создать резервную копию, с помощью правил XML. В таких редких случаях вы можете реализовать BackupAgent, который переопределяет onFullBackup(FullBackupDataOutput), чтобы сохранять нужные вам данные. Чтобы сохранить реализацию системы по умолчанию, вызовите соответствующий метод в надклассе с помощью super.onFullBackup().

Если вы реализуете BackupAgent, по умолчанию система ожидает, что ваше приложение будет выполнять резервное копирование и восстановление пар "ключ-значение". Чтобы использовать автоматическое копирование в облако на основе файлов, задайте для атрибута android:fullBackupOnly значение true в файле манифеста приложения.

Во время автоматического резервного копирования и восстановления система запускает приложение в ограниченном режиме, чтобы оно не могло получить доступ к файлам, которые могут вызвать конфликты, и могло выполнять методы обратного вызова в своем BackupAgent. В этом ограниченном режиме основное действие приложения не запускается автоматически, его поставщики контента не инициализируются, а вместо любого подкласса, объявленного в манифесте приложения, создается экземпляр базового класса Application.

Ваш класс BackupAgent должен реализовывать абстрактные методы onBackup() и onRestore(), которые используются для резервного копирования пар "ключ-значение". Если вы не хотите выполнять резервное копирование пар "ключ-значение", оставьте реализацию этих методов пустой.

Подробнее о расширении BackupAgent…

Как обрабатывать межплатформенные переносы в BackupAgent

Начиная с Android 16 QPR2 (уровень API 36.1) в BackupAgent доступно несколько новых API, которые улучшают поддержку межплатформенной передачи данных.

Новый флаг транспорта

  • FLAG_CROSS_PLATFORM_TRANSFER_IOS – этот флаг добавляется в transportFlags, который передается в BackupAgent.
    • В onFullBackup этот флаг устанавливается, если текущая операция резервного копирования является частью экспорта данных на iOS-устройство.
    • В новой перегрузке onRestoreFile этот флаг устанавливается, если данные импортируются с iOS-устройства.

Новый метод onRestoreFile:

Добавлена новая перегрузка onRestoreFile, которая принимает один параметр FullRestoreDataInput. Этот объект предоставляет дополнительный контекст об операции восстановления:

  • FullRestoreDataInput.getTransportFlags() – возвращает флаги транспорта для текущей операции восстановления, которые могут включать FLAG_CROSS_PLATFORM_TRANSFER_IOS.
  • FullRestoreDataInput.getContentVersion() – возвращает строку версии контента, предоставленную исходным приложением на другой платформе во время межплатформенного переноса. Если значение не указано в источнике, используется пустая строка.

Новый метод оценки размера:

  • onEstimateFullBackupBytes(): этот метод позволяет указать приблизительный размер данных, которые приложение планирует сохранить в резервной копии. Мы настоятельно рекомендуем реализовать этот метод, если ваше приложение выполняет значительные преобразования данных во время резервного копирования или обрабатывает большой объем данных. Это может повысить эффективность за счет отказа от пробного запуска системы по умолчанию. Для приложений с небольшими и простыми резервными копиями этот метод обычно не требуется.

Пример использования

Kotlin

// In your custom BackupAgent class

override fun onFullBackup(out: FullBackupDataOutput) {
    // Check if this is a cross-platform export to iOS
    if ((out.transportFlags and FLAG_CROSS_PLATFORM_TRANSFER_IOS) != 0) {
        Log.d(TAG, "onFullBackup for iOS transfer")
        // Your custom export logic here
        // Call fullBackupFile() for files to include
    }
}

override fun onRestoreFile(input: FullRestoreDataInput) {
    if ((input.transportFlags and FLAG_CROSS_PLATFORM_TRANSFER_IOS) != 0) {
        val sourceContentVersion = input.contentVersion
        Log.d(TAG, "onRestoreFile from iOS, content version: $sourceContentVersion")
        // Your custom import logic here, using input.data, input.destination, etc.
    }
}

// Optional: Provide an estimate of the backup size
override fun onEstimateFullBackupBytes(): Long {
    return calculateEstimatedBackupSize()
}

Java

// In your custom BackupAgent class

@Override
public void onFullBackup(FullBackupDataOutput out) throws IOException {
    // Check if this is a cross-platform export to iOS
    if ((out.getTransportFlags() & FLAG_CROSS_PLATFORM_TRANSFER_IOS) != 0) {
        Log.d(TAG, "onFullBackup for iOS transfer");
        // Your custom export logic here
        // Call fullBackupFile() for files to include
    }
}

@Override
public void onRestoreFile(FullRestoreDataInput input) {
    if ((input.getTransportFlags() & FLAG_CROSS_PLATFORM_TRANSFER_IOS) != 0) {
        String sourceContentVersion = input.getContentVersion();
        Log.d(TAG, "onRestoreFile from iOS, content version: " + sourceContentVersion);
        // Your custom import logic here, using input.getData(), input.getDestination(), etc.
    }
}

// Optional: Provide an estimate of the backup size
@Override
public long onEstimateFullBackupBytes() {
    return calculateEstimatedBackupSize();
}