Back up user data with Auto Backup

Auto Backup para Apps faz backup automático dos dados de um usuário a partir de aplicativos que são alvo e executados no Android 6.0 (API nível 23) ou posterior. O Android preserva os dados do aplicativo carregando-o no Google Drive do usuário – onde ele é protegido pelas credenciais da Conta Google do usuário. A quantidade de dados é limitada a 25MB por usuário do seu aplicativo e não há nenhum custo para armazenar dados de backup. Seu aplicativo pode personalizar o processo de backup ou optar por desativar o backups.

Para uma visão geral das opções de backup do Android e orientações sobre quais dados você deve fazer backup e restaurar, veja o backupoverview.

Arquivos com backup

Por padrão, o Backup automático inclui arquivos na maioria dos diretórios que são atribuídos ao seu aplicativo pelo sistema:

• Arquivos de preferências compartilhadas.
• Arquivos salvos no armazenamento interno do seu aplicativo, acessados por getFilesDir() ou getDir(String, int).
• Arquivos no diretório retornado por getDatabasePath(String), que também inclui arquivos criados com a classe SQLiteOpenHelper.
• Arquivos sobre armazenamento externo no diretório retornado por getExternalFilesDir(String).

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

Você pode configurar sua aplicação para incluir e excluir arquivos particulares. Para mais informações, consulte a secção Incluir e excluir ficheiros.

Nota: O Android não trata a configuração de componentes como dados de utilizador. Se o seu aplicativo habilitar ou desabilitar componentes específicos em seu manifesto enquanto estiver sendo executado, não espere que o AutoBackup salve e restaure a configuração. Para preservar o estado da configuração, salve-a em Preferências Compartilhadas e recupere as Preferências Compartilhadas na restauração. Se você quiser que seu aplicativo salve seu estado, armazene o estado em Preferências Compartilhadas e recupere as Preferências Compartilhadas na restauração.

Localização do Backup

Os dados do Backup são armazenados em uma pasta privada na conta do usuário no Google Drive, limitada a 25MB por aplicativo. Os dados salvos não contam para a quota do usuário do Google Drive. Apenas o backup mais recente é armazenado. Quando o abackup é feito, o backup anterior (se existir) é apagado. O backup de dados não pode ser lido pelo usuário ou por outros aplicativos no dispositivo.

Os usuários podem ver uma lista de aplicativos que foram copiados no aplicativo Google DriveAndroid. Em um dispositivo com Android, os usuários podem encontrar essa lista na gaveta de navegação do Driveapp em Configurações > Backup e reset > App data.

Backups do tempo de vida útil de cada dispositivo são armazenados em conjuntos de dados separados, como mostrado nos exemplos a seguir:

• Se o usuário possui dois dispositivos, então existe um conjunto de dados de backup para cada dispositivo.
• Se o usuário redefinir um dispositivo de fábrica e depois configurar o dispositivo com a mesma conta, o backup será armazenado em um novo conjunto de dados. Os conjuntos de dados obsoletos são automaticamente excluídos após um período de inatividade.

Backup schedule

Backups ocorrem automaticamente quando todas as seguintes condições são satisfeitas:

• O usuário ativou o backup no dispositivo. No Android 9, esta configuração está emSettings > System > Backup.
• Em pelo menos 24 horas desde o último backup.
• O dispositivo está ocioso.
• O dispositivo está ligado a uma rede Wi-Fi (se o utilizador do dispositivo não tiver optado por fazer backups de dados móveis).

Na prática, estas condições ocorrem aproximadamente todas as noites mas um dispositivo pode nunca fazer backup (por exemplo, se nunca se ligar a uma rede). Para conservar a largura de banda da rede, o upload só ocorre se os dados do aplicativo forem alterados.

Durante o Backup automático, o sistema desliga o aplicativo para ter certeza de que ele não está mais escrevendo no sistema de arquivos. Por padrão, o sistema de backup ignora aplicativos que estão rodando em primeiro plano porque os usuários notariam que seus aplicativos estão sendo desligados. Você pode ignorar o comportamento padrão definindo o atributo backupInForeground para true.

Para simplificar os testes, o Android inclui ferramentas que permitem iniciar manualmente um backup do seu aplicativo. Para mais informações, veja Test backup and restore.

Restore schedule

Os dados são restaurados sempre que o aplicativo é instalado, seja da loja Play, durante a configuração do dispositivo (quando o sistema instala aplicativos previamente instalados), ou da execução da instalação adb. A operação de restauração ocorre após a instalação do APK, mas antes do aplicativo estar disponível para ser iniciado pelo usuário.

Durante o assistente de configuração inicial do dispositivo, é mostrada ao usuário uma lista de conjuntos de dados de backup disponíveis e é perguntado a qual deles restaurar os dados. Qualquer conjunto de dados de backup selecionado torna-se o conjunto de dados ancestral para o dispositivo. O dispositivo pode restaurar a partir dos seus próprios backups ou do conjunto de dados ancestral. O dispositivo prioriza seu próprio backup se os backups de ambas as fontes estiverem disponíveis. Se o usuário não passar pelo assistente de configuração do dispositivo, então o dispositivo pode restaurar apenas a partir de seus próprios backups.

Para simplificar os testes, o Android inclui ferramentas que permitem iniciar manualmente uma restauração do seu aplicativo. Para mais informações, consulte Test backup and restore.

Enable and disable backup

Apps que visam o Android 6.0 (API nível 23) ou superior participam automaticamente do Auto Backup. No seu arquivo de manifesto de aplicativo, defina o valor booleanoandroid:allowBackup para ativar ou desativar o backup. O valor padrão é true mas para tornar suas intenções claras, nós recomendamos explicitamente definir o atributo em seus manifestos mostrados abaixo:

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

Você pode desabilitar backups definindo android:allowBackup para false. Você pode querer fazer isso se seu aplicativo puder recriar seu estado através de algum outro mecanismo ou se seu aplicativo lida com informações sensíveis que o Android não deve fazer backup.

Incluir e excluir arquivos

Por padrão, o sistema faz backup de quase todos os dados do aplicativo. Para mais informações, consulte Arquivos que fazem backup. Esta secção mostra-lhe como definir regras XML personalizadas para controlar o que é feito o backup.

1. In AndroidManifest.xml, adicione o atributo android:fullBackupContent ao elemento <application>. Este atributo aponta para um arquivo XML que contém regras de backup. For example:

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

2. Create an XML file called my_backup_rules.xml in theres/xml/ directory. Inside the file, add rules with the<include> and <exclude> elements.The following sample backs up all shared preferences exceptdevice.xml

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

XML config syntax

The XML syntax for the configuration file is shown below:

<full-backup-content> <include domain= path="string" requireFlags= /> <exclude domain= path="string" /></full-backup-content>

Inside the <full-backup-content> tag, you can define <include> and <exclude> 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. Para incluir múltiplos arquivos, use múltiplos <include> elementos.

  Nota: Os ficheiros em directórios devolvidos por getCacheDir()getCodeCacheDir(), ou getNoBackupFilesDir() são sempre excluídos, mesmo que tente incluí-los.

• <exclude> – Especifica um ficheiro ou pasta a excluir durante o backup. Aqui estão alguns ficheiros que são tipicamente excluídos do backup:
  • Arquivos que possuem identificadores específicos do dispositivo, emitidos por um servidor ou gerados no dispositivo. Por exemplo, o Google Cloud Messaging (GCM) precisa gerar um token de registro toda vez que um usuário instala seu aplicativo em um novo dispositivo. Se o token de registro antigo for restaurado, o aplicativo pode se comportar de forma inesperada.
  • Conta credenciais ou outras informações confidenciais. Considere pedir ao usuário para reautenticar a primeira vez que iniciar um aplicativo restaurado, em vez de permitir o armazenamento de tais informações no backup.
  • Arquivos relacionados à depuração da aplicação.
  • Large files that cause the app to exceed the 25MB 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 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 filesystem 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()

Note: You cannot back up files outside of these locations.

• path: Specifies a file or folder to include in or exclude from backup. Note that:
  • This attribute does not support wildcard or regex syntax.
  • You can use . to reference the current directory, however, you cannot reference the parent directory .. for security reasons.
  • If you specify a directory, then the rule applies to all files in the directory and recursive sub-directories.

The include element can also contain the requireFlags attribute, which thesection describing how to define conditional requirements forbackup section discusses in more detail.

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

Se o seu aplicativo salva informações confidenciais no dispositivo, você pode especificar as condições sob as quais os dados do seu aplicativo são incluídos no backup do usuário. Você pode adicionar as seguintes condições no Android 9 (nível 28 da API) orhigher:

• clientSideEncryption: O backup do usuário é criptografado com um cliente-sidesecreto. Esta forma de criptografia é habilitada nos dispositivos rodando Android 9 orhigher desde que o usuário tenha habilitado o backup no Android 9 orhigher e tenha definido um bloqueio de tela (PIN, padrão ou senha) para o seu dispositivo.
• deviceToDeviceTransfer: O usuário está transferindo seu backup para outro dispositivo que suporte a transferência de dados entre dispositivos locais (por exemplo, Google Pixel).

Se você tiver atualizado seus dispositivos de desenvolvimento para o Android 9, você precisa desativar e, em seguida, reativar o backup de dados após a atualização. Isto é porque o Android somente criptografa backups com um segredo do lado do cliente após informar os usuários em Settings orthe Setup Wizard.

Para declarar as condições de inclusão, defina o atributo requireFlags para o valor ou valores desejados no seu em <include> elementos dentro do seu conjunto de regras debackup:

my_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 a sua aplicação implementa um sistema de backups de valor chave, ou se você mesmo implementaBackupAgent,você também pode aplicar estes requisitos condicionais à sua lógica de backup, fazendo uma comparação bitwise entre aBackupDataOutput object’sset of transport flags e o seu agente de backup personalizadoFLAG_CLIENT_SIDE_ENCRYPTION_ENABLEDou FLAG_DEVICE_TO_DEVICE_TRANSFERflags.

O seguinte trecho de código mostra um exemplo de uso deste método:

class MyCustomBackupAgent : 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 MyCustomBackupAgent 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.}

Implement BackupAgent

Apps that implement Auto Backup do not 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() or 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 backup 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. Para usar o backup automático baseado em arquivo, defina o atributo android:fullBackupOnly para true no manifesto do seu aplicativo.

Durante as operações de backup automático e restauração, o sistema inicia o aplicativo em modo restrito para evitar que o aplicativo acesse arquivos que possam causar conflitos e deixar o aplicativo executar métodos de callback em seu BackupAgent. Neste modo restrito, a atividade principal do aplicativo não é automaticamente iniciada, seus Provedores de Conteúdo não são inicializados e a classe base Application é instanciada ao invés de qualquer subclasse declarada no manifesto do aplicativo.

Cuidado: Para evitar erros, certifique-se de que as partes do seu aplicativo que executam no modo restrito (principalmente seu BackupAgent) não acessam provedores de conteúdo no mesmo aplicativo ou tentam lançar o objeto Application. Se você não puder evitar esses padrões, então considere implementar o backup chave/valor ou desabilitar o backup inteiramente.

Seu BackupAgent deve implementar os métodos abstratos onBackup() e onRestore(), que são usados para backup de valor chave. Mas se você não quiser realizar o backup do valor da chave, você pode simplesmente deixar sua implementação desses métodos em branco.

Para mais informações, veja Estendendo o BackupAgent.