Резервное копирование пользовательских данных с помощью Auto Backup

Автоматическое резервное копирование приложений автоматически создает резервные копии данных пользователя из приложений, предназначенных для 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() . Файлы, сохраненные в этих местах, нужны только временно и намеренно исключены из операций резервного копирования.

Вы можете настроить свое приложение для включения и исключения определенных файлов. Дополнительные сведения см. в разделе «Включение и исключение файлов» .

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

Расположение резервной копии

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

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

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

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

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

Внимание: если объем данных превышает 25 МБ, система вызывает onQuotaExceeded() и не выполняет резервное копирование данных в облако. Система периодически проверяет, не упадет ли объем данных в дальнейшем ниже порога в 25 МБ, и при этом продолжает автоматическое резервное копирование.

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

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

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

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

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

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

Расписание восстановления

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

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

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

Включить и отключить резервное копирование

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

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

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

Примечание. Для приложений, предназначенных для Android 12 (уровень API 31) или выше, такое поведение может быть разным. На устройствах некоторых производителей указание android:allowBackup="false" отключает облачное резервное копирование и восстановление (например, резервные копии Google Диска), но не отключает передачу данных с устройства на устройство для приложения. Подробнее см. информацию об изменениях в резервном копировании и восстановлении .

Включение и исключение файлов

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

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

Управление резервным копированием на Android 11 и более ранних версиях

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

Важно! Эти правила резервного копирования XML также используются для устройств под управлением Android 12 или более поздней версии, если ваше приложение предназначено для Android 11 или более ранней версии. В следующем разделе представлен дополнительный набор правил резервного копирования XML для поддержки изменений в восстановлении из резервной копии , которые были введены для устройств под управлением Android 12 или более поздней версии.

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) или выше:

• clientSideEncryption : резервная копия пользователя шифруется с помощью секрета на стороне клиента. Эта форма шифрования включена на устройствах под управлением Android 9 или более поздней версии, если пользователь включил резервное копирование в Android 9 или более поздней версии и установил блокировку экрана (PIN-код, шаблон или пароль) для своего устройства.
• deviceToDeviceTransfer : пользователь переносит свою резервную копию на другое устройство, поддерживающее локальную передачу между устройствами (например, Google Pixel).

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

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

резервная копия_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>

Примечание. Поскольку добавление требований в XML препятствует работе резервного копирования в предыдущих версиях Android, предоставьте альтернативные ресурсы для резервного копирования, используемого на устройствах под управлением Android 8.1 (уровень API 27) или ниже.

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

В следующем фрагменте кода показан пример использования этого метода:

Котлин

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.
}

Ява

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 или более поздней версии.

Важно! Даже если ваше приложение предназначено для Android 12 или более поздней версии, вам также необходимо указать другой набор правил резервного копирования XML для поддержки устройств под управлением Android 11 (уровень API 30) или более ранней версии.

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>

Андроид 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>
</data-extraction-rules>

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

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

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

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

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

<include>

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

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

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

Совет: Чтобы создать резервную копию учетных данных пользователя и токенов аутентификации, не храните их в общих настройках или файле. Вместо этого используйте API Block Store для хранения учетных данных и управления ими. Это помогает гарантировать их безопасное хранение, а также возможность резервного копирования и восстановления вместе с другими данными приложений.

<exclude>

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

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

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

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

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

Каждый элемент <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

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

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

Внедрить агент резервного копирования

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

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

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

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

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

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

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

Дополнительные сведения см. в разделе Расширение BackupAgent .

,

Автоматическое резервное копирование для приложений автоматически создает резервные копии данных пользователя из приложений, предназначенных для 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() . Файлы, сохраненные в этих местах, нужны только временно и намеренно исключены из операций резервного копирования.

Вы можете настроить свое приложение для включения и исключения определенных файлов. Дополнительные сведения см. в разделе «Включение и исключение файлов» .

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

Расположение резервной копии

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

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

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

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

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

Внимание: если объем данных превышает 25 МБ, система вызывает onQuotaExceeded() и не выполняет резервное копирование данных в облако. Система периодически проверяет, не упадет ли объем данных в дальнейшем ниже порога в 25 МБ, и при этом продолжает автоматическое резервное копирование.

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

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

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

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

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

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

Расписание восстановления

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

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

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

Включить и отключить резервное копирование

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

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

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

Примечание. Для приложений, предназначенных для Android 12 (уровень API 31) или выше, такое поведение может быть разным. На устройствах некоторых производителей указание android:allowBackup="false" отключает облачное резервное копирование и восстановление (например, резервные копии Google Диска), но не отключает передачу данных с устройства на устройство для приложения. Подробнее см. информацию об изменениях в резервном копировании и восстановлении .

Включение и исключение файлов

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

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

Управление резервным копированием на Android 11 и более ранних версиях

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

Важно! Эти правила резервного копирования XML также используются для устройств под управлением Android 12 или более поздней версии, если ваше приложение предназначено для Android 11 или более ранней версии. В следующем разделе представлен дополнительный набор правил резервного копирования XML для поддержки изменений в восстановлении из резервной копии , которые были введены для устройств под управлением Android 12 или более поздней версии.

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) или выше:

• clientSideEncryption : резервная копия пользователя зашифрована секретом на стороне клиента. Эта форма шифрования включена на устройствах под управлением Android 9 или более поздней версии, если пользователь включил резервное копирование в Android 9 или более поздней версии и установил блокировку экрана (PIN-код, шаблон или пароль) для своего устройства.
• deviceToDeviceTransfer : пользователь переносит свою резервную копию на другое устройство, поддерживающее локальную передачу между устройствами (например, Google Pixel).

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

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

резервная копия_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>

Примечание. Поскольку добавление требований в XML препятствует работе резервного копирования в предыдущих версиях Android, предоставьте альтернативные ресурсы для резервного копирования, используемого на устройствах под управлением Android 8.1 (уровень API 27) или ниже.

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

В следующем фрагменте кода показан пример использования этого метода:

Котлин

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.
}

Ява

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 или более поздней версии.

Важно! Даже если ваше приложение предназначено для Android 12 или более поздней версии, вам также необходимо указать другой набор правил резервного копирования XML для поддержки устройств под управлением Android 11 (уровень API 30) или более ранней версии.

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>

Андроид 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>
</data-extraction-rules>

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

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

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

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

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

<include>

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

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

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

Совет: Чтобы создать резервную копию учетных данных пользователя и токенов аутентификации, не храните их в общих настройках или файле. Вместо этого используйте API Block Store для хранения учетных данных и управления ими. Это помогает гарантировать их безопасное хранение, а также возможность резервного копирования и восстановления вместе с другими данными приложения.

<exclude>

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

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

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

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

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

Каждый элемент <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

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

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

Реализовать резервную копию

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

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

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

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

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

Осторожно: чтобы избежать ошибок, убедитесь, что части вашего приложения, которые выполняются в ограниченном режиме (в основном вашего BackupAgent ), не получают доступа к поставщикам контента в одном и том же приложении и не пытаются отменить объект Application . Если вы не можете избежать этих шаблонов, подумайте о том, чтобы реализовать резервную копию ключей или полностью отключить резервное копирование.

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

Для получения дополнительной информации см. Extend Backupagent .

,

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

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

Файлы, которые резервированы

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

• Файлы общих предпочтений

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

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

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

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

Вы можете настроить свое приложение для включения и исключения конкретных файлов. Для получения дополнительной информации см. Раздел «Включить и исключить файлы» .

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

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

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

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

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

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

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

Внимание: если объем данных превышает 25 МБ, система вызывает onQuotaExceeded() и не поддерживает данные в облаке. Система периодически проверяет, подпадает ли впоследствии объем данных под порогом 25 МБ и продолжает автоматическое резервное копирование, когда это происходит.

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

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

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

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

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

Чтобы упростить тестирование, Android включает в себя инструменты, которые позволяют вам вручную инициировать резервную копию вашего приложения. Для получения дополнительной информации см. Резервное копирование тестирования и восстановить .

Восстановить график

Данные восстанавливаются всякий раз, когда установлено приложение, будь то в магазине Play, во время настройки устройства (когда система устанавливает ранее установленные приложения) или с помощью установки adb . Операция восстановления происходит после установки APK, но до того, как приложение будет запущено пользователем.

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

Чтобы упростить тестирование, Android включает в себя инструменты, которые позволяют вам вручную инициировать восстановление вашего приложения. Для получения дополнительной информации см. Резервное копирование тестирования и восстановить .

Включить и отключить резервную копию

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

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

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

ПРИМЕЧАНИЕ. Для приложений, нацеленных на Android 12 (API -уровень 31) или выше, это поведение варьируется. На устройствах от некоторых производителей устройств указание android:allowBackup="false" отключает облачное резервное копирование и восстановление (например, резервное копирование Google Drive), но не отключает передачи устройства в приложение. Для получения более подробной информации см. Информацию об изменениях в резервном копировании и восстановлении .

Включите и исключают файлы

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

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

Резервное копирование управления на Android 11 и ниже

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

Важно: эти правила резервного копирования XML также используются для устройств, работающих на Android 12 или выше, если ваше приложение нацелен на Android 11 или ниже. См. Следующий раздел для дополнительного набора правил резервного копирования XML для поддержки изменений в восстановлении резервного копирования , которые были введены для устройств, работающих на Android 12 или выше.

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) или выше:

• clientSideEncryption : резервная копия пользователя зашифрована с помощью секрета на стороне клиента. Эта форма шифрования включена на устройствах, работающих на Android 9 или выше, пока пользователь включает резервное копирование в Android 9 или выше и установила блокировку экрана (PIN -код, шаблон или пароль) для своего устройства.
• deviceToDeviceTransfer : пользователь передает свое резервное копирование на другое устройство, которое поддерживает локальную передачу устройства в установку (например, Google Pixel).

Если вы обновили свои устройства разработки до 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>

ПРИМЕЧАНИЕ. Поскольку добавление требований к XML предотвращает резервное копирование от работы над предыдущими версиями Android, предоставляйте альтернативные ресурсы для резервных копий, используемых на устройствах под управлением Android 8.1 (уровень API 27) или ниже.

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

В следующем фрагменте кода показан пример использования этого метода:

Котлин

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.
}

Ява

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 или выше.

ВАЖНО: Даже если ваше приложение предназначено для Android 12 или выше, вы также должны указать другой набор правил резервного копирования XML для поддержки устройств, которые запускают Android 11 (API -уровень 30) или ниже.

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

   <application ...
    android:dataExtractionRules="backup_rules.xml">
   </application>

2. Создайте XML -файл CANTER 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>
</data-extraction-rules>

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

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

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

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

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

<include>

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

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

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

Совет: чтобы резервное копирование учетных данных пользователя и токенов аутентификации не храните их в общих предпочтениях или в файле. Вместо этого используйте API Block Store API для хранения и управления учетными данными. Это помогает гарантировать, что они надежно хранятся и могут быть резервированы и восстановлены вместе с другими данными приложений.

<exclude>

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

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

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

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

ПРИМЕЧАНИЕ. Если ваш файл конфигурации указывает оба элемента, то резервное копирование содержит все, что захвачено элементами <include> за вычетом ресурсов, указанных в элементах <exclude> . Другими словами, <exclude> имеет приоритет.

Каждый <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

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

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

Реализовать резервную копию

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

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

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

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

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

Осторожно: чтобы избежать ошибок, убедитесь, что части вашего приложения, которые выполняются в ограниченном режиме (в основном вашего BackupAgent ), не получают доступа к поставщикам контента в одном и том же приложении и не пытаются отменить объект Application . Если вы не можете избежать этих шаблонов, подумайте о том, чтобы реализовать резервную копию ключей или полностью отключить резервное копирование.

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

Для получения дополнительной информации см. Extend Backupagent .

,

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

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

Файлы, которые резервированы

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

• Файлы общих предпочтений

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

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

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

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

Вы можете настроить свое приложение для включения и исключения конкретных файлов. Для получения дополнительной информации см. Раздел «Включить и исключить файлы» .

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

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

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

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

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

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

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

Внимание: если объем данных превышает 25 МБ, система вызывает onQuotaExceeded() и не поддерживает данные в облаке. Система периодически проверяет, подпадает ли впоследствии объем данных под порогом 25 МБ и продолжает автоматическое резервное копирование, когда это происходит.

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

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

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

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

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

Чтобы упростить тестирование, Android включает в себя инструменты, которые позволяют вам вручную инициировать резервную копию вашего приложения. Для получения дополнительной информации см. Резервное копирование тестирования и восстановить .

Восстановить график

Данные восстанавливаются всякий раз, когда установлено приложение, будь то в магазине Play, во время настройки устройства (когда система устанавливает ранее установленные приложения) или с помощью установки adb . Операция восстановления происходит после установки APK, но до того, как приложение будет запущено пользователем.

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

Чтобы упростить тестирование, Android включает в себя инструменты, которые позволяют вам вручную инициировать восстановление вашего приложения. Для получения дополнительной информации см. Резервное копирование тестирования и восстановить .

Включить и отключить резервную копию

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

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

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

ПРИМЕЧАНИЕ. Для приложений, нацеленных на Android 12 (API -уровень 31) или выше, это поведение варьируется. На устройствах от некоторых производителей устройств указание android:allowBackup="false" отключает облачное резервное копирование и восстановление (например, резервное копирование Google Drive), но не отключает передачи устройства в приложение. Для получения более подробной информации см. Информацию об изменениях в резервном копировании и восстановлении .

Включите и исключают файлы

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

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

Резервное копирование управления на Android 11 и ниже

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

Важно: эти правила резервного копирования XML также используются для устройств, работающих на Android 12 или выше, если ваше приложение нацелен на Android 11 или ниже. См. Следующий раздел для дополнительного набора правил резервного копирования XML для поддержки изменений в восстановлении резервного копирования , которые были введены для устройств, работающих на Android 12 или выше.

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) или выше:

• clientSideEncryption : резервная копия пользователя зашифрована с помощью секрета на стороне клиента. Эта форма шифрования включена на устройствах, работающих на Android 9 или выше, пока пользователь включает резервное копирование в Android 9 или выше и установила блокировку экрана (PIN -код, шаблон или пароль) для своего устройства.
• deviceToDeviceTransfer : пользователь передает свое резервное копирование на другое устройство, которое поддерживает локальную передачу устройства в установку (например, Google Pixel).

Если вы обновили свои устройства разработки до 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>

ПРИМЕЧАНИЕ. Поскольку добавление требований к XML предотвращает резервное копирование от работы над предыдущими версиями Android, предоставляйте альтернативные ресурсы для резервных копий, используемых на устройствах под управлением Android 8.1 (уровень API 27) или ниже.

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

В следующем фрагменте кода показан пример использования этого метода:

Котлин

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.
}

Ява

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 или выше.

ВАЖНО: Даже если ваше приложение предназначено для Android 12 или выше, вы также должны указать другой набор правил резервного копирования XML для поддержки устройств, которые запускают Android 11 (API -уровень 30) или ниже.

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

   <application ...
    android:dataExtractionRules="backup_rules.xml">
   </application>

2. Создайте XML -файл CANTER 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>
</data-extraction-rules>

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

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

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

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

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

<include>

Specifies a file or folder to backup. By default, Auto Backup includes almost all app files. If you specify an <include> element, the system no longer includes any files by default and backs up only the files specified . To include multiple files, use multiple <include> elements.

On Android 11 and lower , this element can also contain the requireFlags attribute, which the section describing how to define conditional requirements for backup discusses in more detail.

Files in directories returned by getCacheDir() , getCodeCacheDir() , or getNoBackupFilesDir() are always excluded even if you try to include them.

Tip: To back up user credentials and authentication tokens, don't store them in shared preferences or a file. Instead use Block Store APIs to store and manage credentials. This helps ensure that they are securely stored and can be backed up and restored alongside other app data.

<exclude>

Specifies a file or folder to exclude during backup. Here are some files that are typically excluded from backup:

• Files that have device-specific identifiers, either issued by a server or generated on the device. For example, Firebase Cloud Messaging (FCM) needs to generate a registration token every time a user installs your app on a new device. If the old registration token is restored, the app might behave unexpectedly.

• Files related to app debugging.

• Large files that cause the app to exceed the 25 MB backup quota.

Note: If your configuration file specifies both elements, then the backup contains everything captured by the <include> elements minus the resources named in the <exclude> elements. In other words, <exclude> takes precedence.

Each <include> and <exclude> element must include the following two attributes:

domain

Specifies the location of resource. Valid values for this attribute include the following:

• root : the directory on the file system where all private files belonging to this app are stored.
• file : directories returned by getFilesDir() .
• database : directories returned by getDatabasePath() . Databases created with SQLiteOpenHelper are stored here.
• sharedpref : the directory where SharedPreferences are stored.
• external : the directory returned by getExternalFilesDir() .
• device_root : like root but for the device-protected storage.
• device_file : like file but for the device-protected storage.
• device_database : like database but for the device-protected storage.
• device_sharedpref : like sharedpref but for the device-protected storage.

Note: You can't back up files outside these locations.

path

Specifies a file or folder to include in or exclude from backup. Note the following:

• This attribute does not support wildcard or regular expression syntax.
• You can reference the current directory using ./ , but you can't reference the parent directory, such as using .. , for security reasons.
• If you specify a directory, then the rule applies to all files in the directory and recursive subdirectories.

Implement BackupAgent

Apps that implement Auto Backup don't need to implement a BackupAgent . However, you can optionally implement a custom BackupAgent . Typically, there are two reasons for doing this:

• You want to receive notification of backup events, such as onRestoreFinished() and onQuotaExceeded(long, long) . These callback methods are executed even if the app is not running.

• You can't easily express the set of files you want to back up with XML rules. In these rare cases, you can implement a BackupAgent that overrides onFullBackup(FullBackupDataOutput) to store what you want. To retain the system's default implementation, call the corresponding method on the superclass with super.onFullBackup() .

If you implement a BackupAgent , by default the system expects your app to perform key-value backup and restore . To use the file-based Auto Backup instead, set the android:fullBackupOnly attribute to true in your app's manifest.

During auto backup and restore operations, the system launches the app in a restricted mode to both prevent the app from accessing files that might cause conflicts and let the app execute callback methods in its BackupAgent . In this restricted mode, the app's main activity is not automatically launched, its content providers are not initialized, and the base-class Application is instantiated instead of any subclass declared in the app's manifest .

Caution: To avoid errors, make sure that the parts of your app that execute in the restricted mode (mostly your BackupAgent ) don't access content providers in the same app or attempt to cast the Application object. If you can't avoid those patterns, then consider implementing key-value backup or disabling backup entirely.

Your BackupAgent must implement the abstract methods onBackup() and onRestore() , which are used for key-value backup. If you don't want to perform key-value backup, you can leave your implementation of those methods blank.

For more information, see Extend BackupAgent .