Esta página mostra como testar os backups na nuvem e o processo de transferência de dispositivo para dispositivo (D2D) do app. É importante testar esses dois com cada versão 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 principal delas é que a transferência tem um limite de tamanho de dados muito maior de 2 GB, em comparação com 25 MB para backup na nuvem.
Neste guia, mostramos como testar o backup e a restauração na nuvem e a transferência D2D 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 eles 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 fica abstraída. Portanto, você não precisa conhecer essas informações. No entanto, durante a fase de teste, uma compreensão desses conceitos se torna mais importante.
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 dos testes de backup e restauração na nuvem, os testes D2D exigem um dispositivo de origem e um dispositivo de destino para copiar e colar.
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 ao transporte de backup, que arquiva os dados na nuvem. Durante uma operação de restauração, o Backup Manager Service recupera os dados de backup da transferência de backup e os restaura no dispositivo. Em uma transferência D2D, o Serviço Backup Manager consulta o app em busca de dados de backup e os transmite diretamente ao serviço do Backup Manager 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 dessas transferências 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 maioria dos dispositivos com o Google Play vem com as seguintes transferências:
- Transporte do GMS:o transporte de backup em nuvem ativo na maioria dos dispositivos, parte dos Serviços do Google Mobile. Esse transporte armazena dados no Android Backup Service.
- Transporte D2D:esse transporte é 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 seguintes ferramentas.
adb: para executar comandos no dispositivo ou emulador.bmgr: para realizar várias operações de backup e restauração.logcat: para conferir a saída das operações de backup e restauração.
Testar backup na nuvem
O backup e a restauração na nuvem podem ser realizados 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:
- Para o Backup automático, verifique se você está usando um dispositivo ou emulador com o Android 6.0 (nível 23 da API) ou mais recente.
- Para o backup de chave-valor, verifique se você está usando um dispositivo ou emulador com o Android 2.2 (nível 8 da API) ou mais recente.
- É necessário ter acesso à Internet para testar o backup na nuvem.
- Faça login no dispositivo com uma Conta do Google e defina-a como a conta 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 repetir essas etapas, use o seguinte script,
test_cloud_backup.sh, que faz backup do app, faz o download do 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
- Abra o app, faça login e modifique todas as configurações.
- Execute o script, transmitindo o nome do pacote, como
test_cloud_backup.sh com.example.myapp - Abra o app novamente e confirme 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 ser como antes. Se os resultados do teste não atenderem a esses critérios, verifique se você configurou os backups corretamente, sem omitir partes importantes dos dados, e se também está lidando com a recriação de todos os dados armazenados em cache que você excluiu do backup. Repita as etapas 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 dispositivo novo e redefinido para as configurações originais 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 redefinir o dispositivo para a configuração original várias vezes.
Preparar seu dispositivo para testes D2D
Para testar a transferência D2D em um único dispositivo, prepare-o da seguinte maneira:
- Seu dispositivo precisa ter o Android 12 (nível 31 da API) ou mais recente.
- Para testar a versão mais recente do D2D, direcione o app ao Android 12 (nível 31 da API) ou mais recente.
- Crie o seguinte script,
test_d2d.sh, para repetir o 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
- Instale o app que você quer testar no dispositivo.
- Abra o app, faça login e modifique as configurações.
- Execute o script no dispositivo, transmitindo o nome do pacote, como
test_d2d.sh com.example.myapp. - Quando o script for concluído, abra o app no dispositivo e verifique se ele funciona corretamente, com todos os dados mantidos.
Não é necessário que os usuários façam login, e todas as configurações, o progresso e os dados do app precisam aparecer como 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 partes importantes dos dados, e se também está processando a recriação de todos os dados em cache excluídos da transferência. Repita as etapas 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 mensagens a seguir 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 abaixo no Logcat indica que a operação de backup completo falhou, porque nenhuma operação de backup de chave-valor ocorreu ainda 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 novamente.
Tempo limite atingido na espera pelo agente
A mensagem a seguir no Logcat indica que o app está demorando 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 o app usa uma configuração multidex sem o ProGuard.
Conta de backup não inicializada
As mensagens a seguir no Logcat indicam que o backup foi interrompido porque o conjunto de dados de backup 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
gerenciador de backup com o comando adb shell bmgr run e tente
realizar o backup novamente.
Métodos não chamados do app
Como o Backup automático inicia o app com uma classe de base de
Application, é possível que os métodos de configuração
do app não sejam chamados. O backup automático também não inicia nenhuma das atividades
do 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.
Nenhum dado para fazer backup
As mensagens abaixo 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, provavelmente não adicionou dados ou arquivos ao backup.