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

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

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

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

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

  • Файлы SharedPreferences

  • Файлы, сохраненные во внутреннем хранилище приложения и доступные через 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 Диска, но при этом передавать его при переносе данных между устройствами или межплатформенном переносе. Это удобно, если у вас есть файлы, которые слишком велики для резервного копирования в облако, но могут быть без проблем переданы между устройствами.

Если для определенного режима резервного копирования нет правил, например отсутствует раздел <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();
}