Testar o backup e restaurar

Esta página mostra como testar os backups na nuvem e o processo de transferência de dispositivo para dispositivo (D2D) do seu app. É importante testar os dois com cada lançamento principal do app para garantir que os usuários possam continuar usando o app em um novo dispositivo. Embora o backup e a transferência sejam semelhantes, há diferenças importantes entre os dois no Android 12 (nível 31 da API) e versões mais recentes. A mais notável é que a transferência tem um limite de tamanho de dados muito maior, de 2 GB, em comparação com 25 MB para o backup na nuvem.

Este guia mostra como testar o backup e a restauração na nuvem e a transferência de dispositivo para dispositivo de maneira eficiente durante todo o ciclo de desenvolvimento.

Como funciona o teste de backups

Esta seção descreve várias partes do framework de backup do Android e como elas interagem com apps compatíveis com o backup automático e o backup de chave-valor. Durante a fase de desenvolvimento do app, a maior parte do funcionamento interno do framework é abstraída. Por isso, você não precisa dessas informações. No entanto, durante a fase de teste, é importante entender esses conceitos.

O diagrama a seguir ilustra como os dados fluem durante o backup e a restauração na nuvem. Para fins de teste, o mesmo dispositivo pode ser usado para backup e restauração na nuvem.

O diagrama a seguir ilustra como os dados fluem durante uma transferência D2D:

Ao contrário do teste de backup e restauração na nuvem, o teste D2D exige um dispositivo de origem e um de destino para copiar.

O Backup Manager Service é um serviço do sistema Android que orquestra e inicia operações de backup e restauração. O serviço pode ser acessado pela API Backup Manager.

Durante uma operação de backup, o serviço consulta seu app em busca de dados de backup e os entrega à transferência de backup, que arquiva os dados na nuvem. Durante uma operação de restauração, o Backup Manager Service recupera os dados da transferência de backup e os restaura no dispositivo. Para uma transferência D2D, o Backup Manager Service consulta seu app em busca de dados de backup e os transmite diretamente para o Backup Manager Service no novo dispositivo, que os carrega no app.

Os Backup Transports são componentes do Android responsáveis por armazenar e recuperar os dados do app. Um dispositivo Android pode ter zero ou mais transferências de backup, mas apenas uma delas pode ser marcada como ativa. As transferências de backup disponíveis variam de acordo com o dispositivo devido a personalizações feitas por fabricantes e provedores de serviços, mas a maior parte dos dispositivos com o Google Play vem com as seguintes transferências:

• Transferência do GMS:a transferência de backup na nuvem ativa na maioria dos dispositivos, parte dos Serviços do Google Mobile. Essa transferência armazena dados no Android Backup Service.
• Transporte D2D:usado na migração D2D para transferir dados diretamente de um dispositivo para outro.

Ferramentas

Para testar suas operações de backup e restauração, é necessário saber um pouco sobre as ferramentas a seguir.

• adb: para executar comandos no dispositivo ou emulador.
• bmgr: para realizar várias operações de backup e restauração.
• logcat: para ver a saída das operações de backup e restauração.

Testar o backup na nuvem

É possível fazer backup e restauração na nuvem usando um único dispositivo seguindo as etapas desta seção.

Preparar seu dispositivo ou emulador para backups na nuvem

Prepare seu dispositivo ou emulador para testes de backup trabalhando na seguinte lista de verificação:

1. Para o backup automático, verifique se você está usando um dispositivo ou emulador com o Android 6.0 (nível da API 23) ou mais recente.
2. Para o backup de chave-valor, verifique se você está usando um dispositivo ou emulador com o Android 2.2 (nível da API 8) ou mais recente.
3. Você precisa ter acesso à Internet para testar o backup na nuvem.
4. Faça login no dispositivo com uma Conta do Google e defina essa conta como a de backup em Configurações -> Google -> Backup.

Para testar o backup na nuvem, acione um backup na nuvem e desinstale e reinstale o app. Para tornar essas etapas repetíveis, use o seguinte script, test_cloud_backup.sh, que faz backup do app, baixa o APK localmente, desinstala e reinstala o APK:

#!/bin/bash -eu
: "${1?"Usage: $0 package name"}"

# Initialize and create a backup
adb shell bmgr enable true
adb shell bmgr transport com.android.localtransport/.LocalTransport | grep -q "Selected transport" || (echo "Error: error selecting local transport"; exit 1)
adb shell settings put secure backup_local_transport_parameters 'is_encrypted=true'
adb shell bmgr backupnow "$1" | grep -F "Package $1 with result: Success" || (echo "Backup failed"; exit 1)

# Uninstall and reinstall the app to clear the data and trigger a restore
apk_path_list=$(adb shell pm path "$1")
OIFS=$IFS
IFS=$'\n'
apk_number=0
for apk_line in $apk_path_list
do
    (( ++apk_number ))
    apk_path=${apk_line:8:1000}
    adb pull "$apk_path" "myapk${apk_number}.apk"
done
IFS=$OIFS
adb shell pm uninstall --user 0 "$1"
apks=$(seq -f 'myapk%.f.apk' 1 $apk_number)
adb install-multiple -t --user 0 $apks

# Clean up
adb shell bmgr transport com.google.android.gms/.backup.BackupTransportService
rm $apks

echo "Done"

Etapas de teste

1. Abra o app, faça login e modifique todas as configurações.
2. Execute o script, transmitindo o nome do pacote, como test_cloud_backup.sh com.example.myapp
3. Reabra o app e valide se ele funciona corretamente, com todos os dados mantidos.

Você não quer que os usuários precisem fazer login, e todas as configurações, o progresso e os dados do app precisam ser mantidos como estavam antes. Se os resultados do teste não atenderem a esses critérios, verifique se você configurou os backups corretamente, sem omitir dados importantes, e se está processando a recriação de dados armazenados em cache que foram excluídos do backup. Repita as etapas de 1 a 3 para cada iteração de teste.

Testar a transferência D2D

A maneira mais abrangente de testar a transferência D2D é transferir todo o conteúdo do smartphone para um novo dispositivo redefinido para as configurações de fábrica e validar se ele funciona corretamente. No entanto, isso pode ser inconveniente e demorado se você precisar repetir o processo várias vezes. Estas etapas mostram como simular uma transferência com um único dispositivo sem fazer uma redefinição de fábrica repetidamente.

Preparar o dispositivo para testes D2D

Para testar a transferência D2D em um único dispositivo, prepare-o da seguinte maneira:

1. O dispositivo precisa ter o Android 12 (nível 31 da API) ou uma versão mais recente.
2. Para testar a versão mais recente do D2D, direcione o Android 12 (nível 31 da API) ou mais recente no seu app.
3. Crie o seguinte script, test_d2d.sh, para oferecer suporte à repetição do teste:

#!/bin/bash -eu
: "${1?"Usage: $0 package name"}"

# Initialize and create a backup
adb shell bmgr enable true
adb shell settings put secure backup_enable_d2d_test_mode 1
adb shell bmgr transport com.google.android.gms/.backup.migrate.service.D2dTransport
adb shell bmgr init com.google.android.gms/.backup.migrate.service.D2dTransport
adb shell bmgr list transports | grep -q -F "  * com.google.android.gms/.backup.migrate.service.D2dTransport" || (echo "Failed to select and initialize backup transport"; exit 1)
adb shell bmgr backupnow "$1" | grep -F "Package $1 with result: Success" || (echo "Backup failed"; exit 1)

# Uninstall and reinstall the app to clear the data and trigger a restore
apk_path_list=$(adb shell pm path "$1")
OIFS=$IFS
IFS=$'\n'
apk_number=0
for apk_line in $apk_path_list
do
    (( ++apk_number ))
    apk_path=${apk_line:8:1000}
    adb pull "$apk_path" "myapk${apk_number}.apk"
done
IFS=$OIFS
adb shell pm uninstall --user 0 "$1"
adb shell bmgr transport com.google.android.gms/.backup.BackupTransportService
apks=$(seq -f 'myapk%.f.apk' 1 $apk_number)
adb install-multiple -t --user 0 $apks

# Clean up
adb shell bmgr init com.google.android.gms/.backup.migrate.service.D2dTransport
adb shell settings put secure backup_enable_d2d_test_mode 0
adb shell bmgr transport com.google.android.gms/.backup.BackupTransportService
rm $apks

echo "Done"

Etapas de teste

1. Instale o app que você quer testar no dispositivo.
2. Abra o app, faça login e modifique as configurações dele.
3. Execute o script no seu dispositivo, transmitindo o nome do pacote, como test_d2d.sh com.example.myapp.
4. Quando o script for concluído, abra o app no dispositivo e valide se ele funciona corretamente, com todos os dados retidos.

Você não quer que os usuários precisem fazer login, e todas as configurações, o progresso e os dados do app precisam aparecer como estavam antes da execução do script. Se os resultados do teste não atenderem a esses critérios, verifique se você configurou a transferência corretamente, sem omitir dados importantes, e se também está processando a recriação de dados em cache excluídos da transferência. Repita as etapas de 2 a 4 para cada iteração de teste.

Resolver problemas de backup e restauração

Esta seção ajuda a resolver alguns problemas comuns.

Cota de transferências excedida

As seguintes mensagens no Logcat indicam que o app excedeu a cota de transporte:

I/PFTBT: Transport rejected backup of <PACKAGE>, skipping

--- or ---

I/PFTBT: Transport quota exceeded for package: <PACKAGE>

Reduza a quantidade de dados de backup e tente de novo. Por exemplo, verifique se você está armazenando dados em cache somente no diretório de cache do app. O diretório de cache não está incluído nos backups.

Não é possível fazer backup completo

A mensagem a seguir no Logcat indica que a operação de backup completo falhou porque nenhuma operação de backup de chave-valor ocorreu no dispositivo:

I/BackupManagerService: Full backup not currently possible -- key/value backup
not yet run?

Acione um backup de chave-valor com o comando bmgr run e tente de novo.

Tempo limite atingido na espera pelo agente

A seguinte mensagem no Logcat indica que o app está levando mais de 10 segundos para iniciar o backup:

12-05 18:59:02.033  1910  2251 D BackupManagerService:
    awaiting agent for ApplicationInfo{5c7cde0 com.your.app.package}
12-05 18:59:12.117  1910  2251 W BackupManagerService:
    Timeout waiting for agent ApplicationInfo{5c7cde0 com.your.app.package}
12-05 18:59:12.117  1910  2251 W BackupManagerService:
    Can't find backup agent for com.your.app.package

Observe a diferença do carimbo de data/hora na saída do registro. Esse erro geralmente ocorre quando seu app usa uma configuração multidex sem o ProGuard.

Conta de backup não inicializada

As seguintes mensagens no Logcat indicam que o backup foi interrompido porque o conjunto de dados não foi inicializado:

01-31 14:32:45.698 17280 17292 I Backup: [GmsBackupTransport] Try to backup for
an uninitialized backup account.
01-31 14:32:45.699  1043 18255 W PFTBT: Transport failed; aborting backup: -1001
01-31 14:32:45.699  1043 18255 I PFTBT: Full backup completed with status: -1000

Execute o Backup Manager com o comando adb shell bmgr run e tente fazer o backup novamente.

Métodos não chamados do app

Como o backup automático inicia seu app com uma classe básica de Application, os métodos de configuração do app podem não ser chamados. O backup automático também não inicia nenhuma das atividades do seu app. Por isso, você poderá encontrar erros se o app for configurado em uma atividade. Para saber mais, leia Implementar o BackupAgent.

Por outro lado, o backup de chave-valor inicia o app com qualquer subclasse Application declarada no arquivo de manifesto do app.

Não há dados para fazer backup

As seguintes mensagens no Logcat indicam que o app não tem dados para fazer backup:

I Backup  : [FullBackupSession] Package com.your.app.package doesn't have any backup data.

--- or ---

I Backup  : [D2dTransport] Package com.your.app.package doesn't have any backup data.

Se você implementou seu próprio BackupAgent, isso provavelmente significa que você não adicionou dados ou arquivos ao backup.