Cette page explique comment tester les sauvegardes dans le cloud et le processus de transfert d'appareil à appareil (D2D) pour votre application. Il est important de tester ces deux méthodes avec chaque version majeure de votre application pour vous assurer qu'elle continuera à fonctionner sur un nouvel appareil. Bien que la sauvegarde et le transfert soient similaires, il existe des différences importantes entre les deux sous Android 12 (niveau d'API 31) ou version ultérieure. En particulier, la taille de transfert des données, qui est de 2 Go, est bien plus élevée que celle de la sauvegarde dans le cloud, qui est de 25 Mo.
Ce guide vous explique comment tester efficacement la sauvegarde dans le cloud et la restauration ainsi que le transfert D2D tout au long du cycle de développement.
Fonctionnement du test des sauvegardes
Cette section décrit plusieurs éléments du framework de sauvegarde Android et la manière dont ils interagissent avec les applications compatibles avec la sauvegarde automatique et la sauvegarde de clé-valeur. Pendant la phase de développement de l'application, la plupart des opérations internes du framework ont été extraites. Vous n'aviez donc pas besoin de connaître ces informations. Cependant, pendant la phase de test, il est plus important de comprendre ces concepts.
Le schéma suivant illustre le flux de données pendant la sauvegarde dans le cloud et la restauration : À des fins de test, un même appareil peut être utilisé pour la sauvegarde dans le cloud et la restauration.
Le schéma suivant illustre le flux de données lors d'un transfert D2D.
Contrairement aux tests de sauvegarde dans le cloud et de restauration, les tests D2D nécessitent un appareil source et un appareil cible entre lesquels les données seront copiées.
Le gestionnaire de sauvegarde est un service du système Android qui orchestre et lance des opérations de sauvegarde et de restauration. Ce service est accessible via l'API Backup Manager.
Lors d'une opération de sauvegarde, il interroge votre application pour récupérer les données de sauvegarde, puis les transmet au transfert de sauvegarde, qui les archive ensuite dans le cloud. Lors d'une opération de restauration, le gestionnaire de sauvegarde récupère les données de sauvegarde du transfert de sauvegarde et les restaure sur l'appareil. Dans le cas d'un transfert D2D, le service du gestionnaire de sauvegarde interroge votre application pour récupérer les données de sauvegarde et les transmet directement au service du gestionnaire de sauvegarde sur le nouvel appareil, qui les charge ensuite dans votre application.
Les transferts de sauvegarde sont des composants Android chargés de stocker et de récupérer les données de vos applications. Un appareil Android peut avoir aucun, un ou plusieurs transferts de sauvegarde, mais un seul de ces transferts peut être marqué comme actif. Les transferts de sauvegarde disponibles varient d'un appareil à l'autre (en raison des personnalisations apportées par les fabricants d'appareils et les fournisseurs de services), mais la plupart des appareils compatibles avec Google Play sont livrés avec les modes de transfert suivants :
- Transfert GMS : transfert de sauvegarde actif dans le cloud qui a lieu sur la plupart des appareils, dans le cadre des services Google Mobile. Ce transfert stocke des données dans l'Android Backup Service.
- Transfert D2D : ce transfert est employé par le système de migration D2D pour transférer les données directement d'un appareil à un autre.
Outils
Pour tester vos opérations de sauvegarde et de restauration, vous devez connaître les outils suivants.
adb: permet d'exécuter des commandes sur l'appareil ou l'émulateur.bmgr: permet d'effectuer diverses opérations de sauvegarde et de restauration.logcat: permet d'afficher les résultats des opérations de sauvegarde et de restauration.
Tester la sauvegarde dans le cloud
La sauvegarde dans le cloud et la restauration peuvent être effectuées avec un seul appareil en suivant les étapes de cette section.
Préparer votre appareil ou votre émulateur pour les sauvegardes dans le cloud
Préparez votre appareil ou votre émulateur pour les tests de sauvegarde en respectant la checklist suivante :
- Pour la sauvegarde automatique, assurez-vous d'utiliser un appareil ou un émulateur sous Android version 6.0 (niveau d'API 23) ou ultérieure.
- Pour la sauvegarde de clé-valeur, assurez-vous d'utiliser un appareil ou un émulateur sous Android version 2.2 (niveau d'API 8) ou ultérieure.
- Vous devez disposer d'un accès à Internet pour tester la sauvegarde dans le cloud.
- Connectez-vous à l'appareil avec un compte Google et définissez-le comme compte de sauvegarde sous Settings -> Google -> Backup (Paramètres -> Google -> Sauvegarde).
Pour effectuer un test, déclenchez une sauvegarde dans le cloud, puis désinstallez et réinstallez l'application. Pour reproduire ce scénario, vous pouvez utiliser le script suivant, test_cloud_backup.sh, qui sauvegarde votre application, télécharge l'APK en local, le désinstalle et le réinstalle :
#!/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"
Étapes du test
- Ouvrez votre application, connectez-vous et modifiez tous les paramètres.
- Exécutez le script en transmettant le nom du package, par exemple
test_cloud_backup.sh com.example.myapp. - Rouvrez l'application et vérifiez qu'elle fonctionne correctement et que toutes les données ont été conservées.
Il est préférable que vos utilisateurs n'aient pas à se connecter. De plus, leurs paramètres, leur progression et leurs données d'application doivent rester les mêmes d'une session à une autre. Si les résultats de votre test ne répondent pas à ces critères, assurez-vous d'avoir correctement configuré les sauvegardes, sans omettre de données clés, et vérifiez que vous gérez également la recréation des données mises en cache que vous avez exclues de la sauvegarde. Répétez les étapes 1 à 3 pour chaque itération de test.
Tester le transfert D2D
Le moyen le plus complet de tester le transfert D2D consiste à transférer tout le contenu du téléphone vers un nouvel appareil et à vérifier qu'il fonctionne comme prévu. Cependant, répéter ce processus plusieurs fois peut s'avérer complexe et long. Cette procédure vous explique comment simuler un transfert avec un seul appareil sans avoir à rétablir la configuration d'usine à plusieurs reprises.
Préparer votre appareil pour les tests D2D
Pour tester le transfert D2D sur un seul appareil, suivez les étapes préparatoires ci-dessous :
- Votre appareil doit être équipé d'Android 12 (niveau d'API 31) ou version ultérieure.
- Pour tester la dernière version de D2D, ciblez Android 12 (niveau d'API 31) ou version ultérieure dans votre application.
- Créez le script suivant,
test_d2d.sh, pour autoriser la répétition du test :
#!/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"
Étapes du test
- Installez l'application que vous souhaitez tester sur l'appareil.
- Ouvrez votre application, connectez-vous et modifiez ses paramètres.
- Exécutez le script sur votre appareil en transmettant le nom du package, par exemple
test_d2d.sh com.example.myapp. - Une fois le script terminé, ouvrez l'application sur l'appareil, puis vérifiez que tout fonctionne comme prévu et que toutes les données ont été conservées.
Il est préférable que vos utilisateurs n'aient pas à se connecter. De plus, tous leurs paramètres, leur progression et les données de l'application doivent être visibles avant l'exécution du script. Si les résultats de vos tests ne répondent pas à ces critères, assurez-vous d'avoir correctement configuré le transfert, sans omettre d'éléments clés de données, et vérifiez que vous gérez également la recréation des données mises en cache que vous avez exclues du transfert. Répétez les étapes 2 à 4 pour chaque itération de test.
Résoudre les problèmes de sauvegarde et de restauration
Cette section vous permet de résoudre certains problèmes courants.
Quota de transfert dépassé
Les messages suivants dans Logcat indiquent que votre application a dépassé le quota de transfert :
I/PFTBT: Transport rejected backup of <PACKAGE>, skipping
--- or ---
I/PFTBT: Transport quota exceeded for package: <PACKAGE>
Réduisez la quantité de données de sauvegarde, puis réessayez. Par exemple, vérifiez que vous ne mettez en cache des données que dans le répertoire de mise en cache de votre application. Le répertoire de mise en cache n'est pas inclus dans les sauvegardes.
Sauvegarde complète impossible
Le message suivant dans Logcat indique que l'opération de sauvegarde complète a échoué, car aucune opération de sauvegarde de clé-valeur n'a encore été effectuée sur l'appareil :
I/BackupManagerService: Full backup not currently possible -- key/value backup
not yet run?
Déclenchez une sauvegarde de clé-valeur à l'aide de la commande bmgr run, puis réessayez.
Délai d'inactivité en attente de l'agent
Le message suivant dans Logcat indique que le lancement de votre application prend plus de 10 secondes pour la sauvegarde :
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
Notez la différence de code temporel dans la sortie du journal. Cette erreur se produit en général lorsque votre application utilise une configuration multidex sans ProGuard.
Compte de sauvegarde non initialisé
Les messages suivants dans Logcat indiquent que la sauvegarde a été interrompue, car l'ensemble de données n'a pas été initialisé :
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
Exécutez le gestionnaire de sauvegarde à l'aide de la commande adb shell bmgr run, puis réessayez d'effectuer la sauvegarde.
Méthodes de l'application non appelées
Étant donné que la sauvegarde automatique lance votre application avec une classe de base Application, il est possible que les méthodes de configuration de votre application ne soient pas appelées. La sauvegarde automatique ne lance aucune des activités de votre application. Des erreurs peuvent donc se produire si votre application est configurée dans une activité. Pour en savoir plus, consultez la section Implémenter BackupAgent.
En revanche, la sauvegarde de clé-valeur lance votre application avec n'importe quelle sous-classe Application que vous déclarez dans le fichier manifeste de votre application.
Aucune donnée à sauvegarder
Les messages suivants dans Logcat indiquent que votre application ne dispose d'aucunes données à sauvegarder :
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.
Si vous avez implémenté votre propre BackupAgent, cela signifie probablement que vous n'avez ajouté aucunes données ni aucun fichier à la sauvegarde.