Fazer backup dos dados de usuários com o Backup automático

O Backup automático para apps salva os dados do usuário automaticamente de apps para Android 6.0 (nível 23 da API) ou mais recente. O Android preserva os dados do app fazendo upload deles para o Google Drive, onde ficam protegidos pelas credenciais da Conta do Google do usuário. O backup tem criptografia de ponta a ponta em dispositivos com Android 9 ou versões mais recentes usando PIN, padrão ou senha. Cada app pode alocar até 25 MB de dados de backup por usuário. Não há custos para armazenar dados de backup. Os apps podem personalizar o processo de backup ou cancelar o uso dele desativando os backups.

Para ter uma visão geral das opções de backup do Android e conferir uma orientação sobre quais dados armazenar em backup e restaurar, consulte a Visão geral do backup de dados.

Arquivos que são salvos em backup

Por padrão, o Backup automático inclui arquivos da maioria dos diretórios atribuídos ao seu app pelo sistema:

O Backup Automático exclui os arquivos nos diretórios retornados por getCacheDir(), getCodeCacheDir() e getNoBackupFilesDir(). Os arquivos salvos nesses locais são necessários apenas temporariamente e são excluídos intencionalmente das operações de backup.

É possível configurar seu app para incluir e excluir arquivos específicos. Para mais informações, consulte a seção Incluir e excluir arquivos.

Local do backup

Os dados de backup são armazenados em uma pasta particular na conta do Google Drive do usuário, com o limite de 25 MB por app. Os dados salvos não contam para a cota pessoal do usuário no Google Drive. Apenas o backup mais recente é armazenado. Quando um backup é feito, todos os backups anteriores são excluídos. Os dados de backup não podem ser lidos pelo usuário ou por outros apps do dispositivo.

O usuário pode conferir uma lista dos apps que foram armazenados em backup no app Android Google Drive. Em um dispositivo com Android, o usuário pode acessar essa lista na gaveta de navegação do app Drive em Configurações > Fazer backup e redefinir.

Os backups de cada ciclo de vida de configuração do dispositivo são armazenados em conjuntos de dados separados, conforme descrito nos exemplos abaixo:

  • Se o usuário tiver dois dispositivos, haverá um conjunto de dados de backup para cada dispositivo.

  • Se o usuário redefinir um dispositivo para a configuração original e, em seguida, configurar o dispositivo usando a mesma conta, o backup será armazenado em um novo conjunto de dados. Os conjuntos de dados obsoletos serão automaticamente excluídos após um período de inatividade.

Programação de backup

Os backups ocorrem automaticamente quando todas as condições a seguir são atendidas:

  • O usuário ativou o backup no dispositivo. No Android 9, essa configuração está em Configurações > Sistema > Backup.
  • Pelo menos 24 horas se passaram desde o último backup.
  • O dispositivo está ocioso.
  • O dispositivo está conectado a uma rede Wi-Fi (se o usuário do dispositivo não tiver ativado os backups com dados móveis).

Na prática, essas condições ocorrem quase todas as noites, mas um dispositivo pode nunca fazer backup (por exemplo, se ele nunca se conectar a uma rede). Para preservar a largura de banda da rede, o upload acontecerá somente se os dados do app forem alterados.

Durante o Backup Automático, o sistema encerra o app para garantir que ele não esteja mais gravando no sistema de arquivos. Por padrão, o sistema de backup ignora os apps em execução em primeiro plano para evitar uma experiência ruim do usuário. É possível substituir o comportamento padrão definindo o atributo android:backupInForeground como verdadeiro.

Para simplificar os testes, o Android inclui ferramentas que permitem iniciar manualmente um backup do app. Para mais informações, consulte Testar backup e restauração.

Programação de restauração

Os dados são restaurados sempre que o app é instalado, seja pela Google Play Store, durante a configuração do dispositivo (quando o sistema instala apps instalados anteriormente) ou executando a instalação de adb. A operação de restauração ocorre depois que o APK é instalado, mas antes que o app esteja disponível para ser iniciado pelo usuário.

Durante a execução do assistente de configuração inicial do dispositivo, o usuário encontrará uma lista de conjuntos de dados de backup disponíveis pedindo que ele escolha qual deles será usado para restaurar os dados. O conjunto de dados de backup selecionado se tornará o conjunto de dados ancestral do dispositivo. O dispositivo pode ser restaurado usando os próprios backups ou o conjunto de dados ancestral. Se os backups das duas fontes estiverem disponíveis, o dispositivo vai priorizar o próprio backup. Se o usuário não tiver passado pelo assistente de configuração, o dispositivo só poderá ser restaurado usando os próprios backups.

Para simplificar o teste, o Android inclui ferramentas que permitem iniciar manualmente uma restauração do app. Para ver mais informações, consulte Testar backup e restauração.

Ativar e desativar o backup

Os apps voltados para o Android 6.0 (API de nível 23) ou versão mais recente são incluídos automaticamente no Backup automático. No arquivo de manifesto do app, defina o valor booleano android:allowBackup para ativar ou desativar o backup. O valor padrão é true, mas recomendamos definir explicitamente o atributo no manifesto, como mostrado no exemplo a seguir:

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

Você pode desativar os backups definindo android:allowBackup como false. Faça isso se o app puder recriar o próprio estado usando outro mecanismo ou se ele processar informações sensíveis.

Incluir e excluir arquivos

Por padrão, o sistema faz backup de quase todos os dados dos apps. Para mais informações, consulte a seção sobre arquivos que são salvos em backup.

Você pode controlar quais dados são incluídos no backup com base no tipo de transferência. O Backup Automático é compatível com backups na nuvem para o Google Drive e transferências diretas de dispositivo para dispositivo (D2D). Os métodos de configuração variam de acordo com a versão do Android e o targetSdkVersion do app.

Controlar o backup no Android 11 e em versões anteriores

Siga as etapas desta seção para controlar quais arquivos são salvos em backup em dispositivos com o Android 11 (nível 30 da API) ou versões anteriores.

  1. No arquivo AndroidManifest.xml, adicione o atributo android:fullBackupContent ao elemento <application>, conforme mostrado no exemplo abaixo. Esse atributo aponta para um arquivo XML que contém regras de backup.

    <application ...
    android:fullBackupContent="@xml/backup_rules">
</application>

  2. Crie um arquivo XML com o nome @xml/backup_rules no diretório res/xml/. Nesse arquivo, adicione regras com os elementos <include> e <exclude>. O exemplo abaixo faz backup de todas as preferências compartilhadas, exceto 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>

Definir as condições do dispositivo necessárias para backup

Se o app salvar informações sensíveis no dispositivo, você poderá especificar as condições em que os dados do app serão incluídos no backup do usuário. Você pode adicionar as condições abaixo no Android 9 (nível 28 da API) ou versão mais recente:

Se você fez upgrade dos seus dispositivos de desenvolvimento para o Android 9, será necessário desativar e reativar o backup de dados depois do upgrade. Isso ocorre porque o Android só criptografa os backups com um segredo do lado do cliente depois de informar os usuários nas configurações ou no assistente de configuração.

Para declarar as condições de inclusão, defina o atributo requireFlags com os valores que você quer usar ou os valores nos elementos <include> dentro do conjunto de regras de backup:

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>

Se o app implementar um sistema de backup de chave-valor ou se você implementar BackupAgent por conta própria, também será possível aplicar esses requisitos condicionais à lógica de backup realizando uma comparação bit a bit entre o conjunto de flags de transporte de um objeto BackupDataOutput e as flags FLAG_CLIENT_SIDE_ENCRYPTION_ENABLED ou FLAG_DEVICE_TO_DEVICE_TRANSFER do agente de backup personalizado.

O snippet de código a seguir mostra um exemplo de uso desse método:

Kotlin

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

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

    // Implementation of onRestore() here.
}

Java

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

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

    // Implementation of onRestore() here.
}

Controlar o backup no Android 12 ou mais recente

Caso o app seja destinado ao Android 12 (nível 31 da API) ou versões mais recentes, siga as etapas desta seção para controlar quais arquivos são salvos em backup em dispositivos com essas versões.

.

  1. No arquivo AndroidManifest.xml, adicione o atributo android:dataExtractionRules ao elemento <application>, conforme mostrado no exemplo abaixo. Esse atributo aponta para um arquivo XML que contém regras de backup.

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

  2. Crie um arquivo XML com o nome backup_rules.xml no diretório res/xml/. Nesse arquivo, adicione regras com os elementos <include> e <exclude>. O exemplo abaixo faz backup de todas as preferências compartilhadas, exceto 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>

Sintaxe de configuração XML

A sintaxe XML para o arquivo de configuração varia de acordo com a versão do Android em que o app é direcionado e está sendo executado.

Android 11 ou versão anterior

Use a seguinte sintaxe XML para o arquivo de configuração que controla o backup para dispositivos com o Android 11 ou versões anteriores.

<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 ou versão mais recente

Caso o app seja direcionado ao Android 12 (API de nível 31) ou versões mais recentes, use a seguinte sintaxe XML para o arquivo de configuração que controla o backup em dispositivos com o Android 12 ou versões mais recentes.

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

Cada seção da configuração (<cloud-backup>, <device-transfer>, <cross-platform-transfer>) contém regras que se aplicam apenas a esse tipo de transferência. Essa separação permite, por exemplo, excluir um arquivo ou diretório dos backups do Google Drive enquanto ele ainda estiver sendo enviado em uma transferência entre dispositivos (D2D) ou multiplataforma. Isso é útil se você tem arquivos muito grandes para fazer backup na nuvem, mas que podem ser transferidos entre dispositivos sem problemas.

Se não houver regras para um modo de backup específico, por exemplo, se a seção <device-transfer> estiver vazia, esse modo será totalmente ativado para todo o conteúdo, exceto para os diretórios no-backup e cache, conforme descrito em Arquivos armazenados em backup.

O app pode definir a sinalização disableIfNoEncryptionCapabilities na seção <cloud-backup> para garantir que o backup aconteça apenas se puder ser criptografado, como quando o usuário tem uma tela de bloqueio. A definição dessa restrição impedirá que os backups sejam enviados à nuvem se o dispositivo do usuário não oferecer suporte à criptografia. Porém, como as transferências D2D não são enviadas ao servidor, elas continuam funcionando até mesmo em dispositivos sem suporte à criptografia.

Sintaxe para os elementos "incluir" e "excluir"

Dentro das tags <full-backup-content>, <cloud-backup> e <device-transfer>, dependendo da versão do Android do dispositivo e da targetSDKVersion do app, é possível definir os elementos <include> e <exclude>:

<include>

Especifica um arquivo ou uma pasta para ser salva em backup. Por padrão, o Backup automático inclui quase todos os arquivos dos apps. Se você especificar um elemento <include>, o sistema não incluirá mais arquivos por padrão e fará o backup somente dos arquivos especificados. Para incluir vários arquivos, use vários elementos <include>.

No Android 11 e versões anteriores, esse elemento também pode conter o atributo requireFlags, discutido em mais detalhes na seção que descreve como definir requisitos condicionais para backup.

Os arquivos nos diretórios retornados por getCacheDir(), getCodeCacheDir() ou getNoBackupFilesDir() serão sempre excluídos, mesmo que você tente incluí-los.

<exclude>

Especifica um arquivo ou uma pasta a serem excluídos do backup. Confira alguns arquivos que costumam ser excluídos do backup:

  • Arquivos que têm identificadores específicos ao dispositivo, emitidos por um servidor ou gerados no dispositivo. Por exemplo, o Firebase Cloud Messaging (FCM) precisa gerar um token de registro toda vez que um usuário instalar o app em um novo dispositivo. Se o token de registro antigo for restaurado, o app poderá ter um comportamento inesperado.

  • Arquivos relacionados à depuração do app.

  • Arquivos grandes que fazem com que o app exceda a cota de backup de 25 MB.

Cada elemento <include> e <exclude> precisa incluir os dois atributos a seguir:

domain

Especifica o local do recurso. Os valores válidos para esse atributo incluem:

  • root: o diretório no sistema de arquivos em que todos os arquivos particulares pertencentes ao app são armazenados.
  • file: diretórios retornados por getFilesDir().
  • database: diretórios retornados por getDatabasePath(). Os bancos de dados criados pelo SQLiteOpenHelper são armazenados neste elemento.
  • sharedpref: o diretório onde as SharedPreferences são armazenadas.
  • external: o diretório retornado por getExternalFilesDir().
  • device_root: semelhante a root, mas para o armazenamento protegido pelo dispositivo.
  • device_file: semelhante a file, mas para o armazenamento protegido pelo dispositivo.
  • device_database: semelhante a database, mas para o armazenamento protegido pelo dispositivo.
  • device_sharedpref: semelhante a sharedpref, mas para o armazenamento protegido pelo dispositivo.
path

Especifica um arquivo ou uma pasta a serem incluídos ou excluídos do backup. Observe o seguinte:

  • Esse atributo não é compatível com a sintaxe de caractere curinga ou expressão regular.
  • É possível referenciar o diretório atual usando ./, mas não é possível referenciar o diretório pai, usando .., por motivos de segurança.
  • Se você especificar um diretório, a regra se aplicará a todos os arquivos que estiverem nele e nos subdiretórios recursivos.

Configurar transferências multiplataforma

A partir do Android 16 QPR2 (nível 36.1 da API), é possível configurar o Backup Automático para transferências de dados de e para dispositivos que não são Android. Para fazer isso, adicione o elemento <cross-platform-transfer> à configuração <data-extraction-rules>, conforme mostrado na sintaxe do Android 12 ou versões mais recentes. É necessário especificar a plataforma de destino usando o atributo platform obrigatório. O único valor compatível é ios.

Nessa seção, é possível usar os elementos padrão <include> e <exclude>, conforme descrito em Sintaxe para os elementos "include" e "exclude", para especificar quais dados serão transferidos.

Além disso, é necessário incluir o elemento <platform-specific-params> para ajudar o sistema a associar seu app ao correspondente na plataforma de destino. Este elemento tem os seguintes atributos obrigatórios:

  • bundleId: o ID do pacote do app na outra plataforma (por exemplo, o ID do pacote do seu app iOS).
  • teamId: o ID da equipe do app na outra plataforma (por exemplo, o ID da equipe do seu app iOS).
  • contentVersion: uma string de versão definida por você, associada ao formato de dados que está sendo exportado.

Os atributos bundleId e teamId são usados para ajudar a verificar a integridade dos dados e a correspondência adequada entre apps. Eles garantem que os dados sejam transferidos apenas para o app especificado na outra plataforma durante uma exportação e que esse app Android importe dados apenas desse app específico durante uma importação.

Para ter um controle mais refinado sobre o processo de transformação e transferência de dados além do que as regras XML oferecem, implemente um BackupAgent personalizado e use as APIs de transferência multiplataforma.

Mapeamento de arquivos para transferências do iOS

Ao transferir arquivos para o iOS, os domain e path do Android especificados nas regras <include> são mapeados para uma estrutura de diretório específica. A tabela a seguir mostra os caminhos de destino no iOS em relação à raiz de destino da transferência, com base no domain do Android:

Android domain Caminho no iOS (em relação à raiz da transferência)
root app/
file app/files/
database app/databases/
sharedpref app/shared_prefs/
external external/files/
device_root device/app/
device_file device/app/files/
device_database device/app/databases/
device_sharedpref device/app/shared_prefs/

Por exemplo, um arquivo incluído com <include domain="file" path="my_settings.txt"/> vai estar disponível no iOS em app/files/my_settings.txt em relação à raiz do destino da transferência.

Implementar o BackupAgent

Apps que implementam o Backup Automático não precisam implementar um BackupAgent. No entanto, você pode implementar um BackupAgent personalizado como uma opção. Normalmente, há duas razões para fazer isso:

  • Você quer receber notificações de eventos de backup, como onRestoreFinished() e onQuotaExceeded(). Esses métodos de callback são executados mesmo que o app não esteja em execução.

  • Você não consegue expressar com facilidade o conjunto de arquivos que quer armazenar em backup usando regras XML. Nesses casos raros, é possível implementar um BackupAgent que substitui o método onFullBackup(FullBackupDataOutput) para armazenar o que você quer. Para manter a implementação padrão do sistema, chame o método correspondente na superclasse usando super.onFullBackup().

Se você implementar um BackupAgent, o sistema esperará, por padrão, que o app faça o backup e a restauração de chave-valor. Para usar o Backup Automático com base em arquivos, defina o atributo android:fullBackupOnly como true no manifesto do app.

Durante as operações automáticas de backup e restauração, o sistema inicia o app em um modo restrito para evitar que ele acesse arquivos que possam causar conflitos e permitir que o app execute métodos de callback no BackupAgent. No modo restrito, a atividade principal do app não é iniciada automaticamente, os provedores de conteúdo não são inicializados e o Application de classe de base é instanciado, em vez de qualquer subclasse declarada no manifesto do app.

.

Seu BackupAgent precisa implementar os métodos abstratos onBackup() e onRestore(), que são usados para o backup de chave-valor. No entanto, se você não quiser fazer o backup de chave-valor, poderá deixar a implementação desses métodos em branco.

Para mais informações, consulte Estender o BackupAgent.

Processar transferências multiplataforma no BackupAgent

A partir do Android 16 QPR2 (nível 36.1 da API), várias novas APIs estão disponíveis em BackupAgent para oferecer melhor suporte a transferências de dados multiplataforma.

Nova flag de transporte:

  • FLAG_CROSS_PLATFORM_TRANSFER_IOS: essa flag é adicionada ao transportFlags fornecido ao BackupAgent.
    • Em onFullBackup, essa flag será definida se a operação de backup atual fizer parte de uma exportação de dados para um dispositivo iOS.
    • Na nova sobrecarga de onRestoreFile, essa flag será definida se os dados estiverem sendo importados de um dispositivo iOS.

Novo método onRestoreFile:

Uma nova sobrecarga de onRestoreFile foi introduzida, que usa um único parâmetro FullRestoreDataInput. Esse objeto fornece mais contexto sobre a operação de restauração:

  • FullRestoreDataInput.getTransportFlags(): retorna as flags de transporte para a operação de restauração atual, que podem incluir FLAG_CROSS_PLATFORM_TRANSFER_IOS.
  • FullRestoreDataInput.getContentVersion(): retorna a string da versão do conteúdo fornecida pelo aplicativo de origem na outra plataforma durante uma transferência multiplataforma. Esse valor será uma string vazia se não for fornecido pela origem.

Novo método de estimativa de tamanho:

  • onEstimateFullBackupBytes(): esse método permite que você forneça um tamanho estimado dos dados que o app pretende incluir no backup. A implementação é altamente recomendada se o app realiza transformações de dados significativas durante o backup ou processa um grande volume de dados, porque pode melhorar a eficiência evitando a simulação padrão do sistema. Para apps com backups pequenos e simples, esse método geralmente não é necessário.

Exemplo de uso:

Kotlin

// In your custom BackupAgent class

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

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

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

Java

// In your custom BackupAgent class

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

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

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