Sauvegarder les données des utilisateurs avec Auto Backup

Auto Backup for Apps sauvegarde automatiquement les données d’un utilisateur à partir des apps qui ciblent et s’exécutent sur Android 6.0 (niveau 23 de l’API) ou plus. Android préserve les données des apps en les téléchargeant sur le Google Drive de l’utilisateur – où elles sont protégées par les informations d’identification du compte Google de l’utilisateur. La quantité de données est limitée à 25 Mo par utilisateur de votre application et le stockage des données de sauvegarde est gratuit. Votre application peut personnaliser le processus de sauvegarde ou se désengager en désactivant les sauvegardes.

Pour un aperçu des options de sauvegarde d’Android et des conseils sur les données que vous devriez sauvegarder et restaurer, consultez l’aperçu de la sauvegarde des données.

Fichiers qui sont sauvegardés

Par défaut, la sauvegarde automatique inclut les fichiers dans la plupart des répertoires qui sont attribués à votre application par le système :

• Fichiers de préférences partagées.
• Fichiers enregistrés sur le stockage interne de votre app, accessibles par getFilesDir() ou getDir(String, int).
• Fichiers du répertoire renvoyé par getDatabasePath(String), qui comprend également les fichiers créés avec la classe SQLiteOpenHelper.
• Fichiers sur un stockage externe dans le répertoire renvoyé par getExternalFilesDir(String).

La sauvegarde automatique exclut les fichiers dans les répertoires retournés par getCacheDir()getCodeCacheDir(), ou getNoBackupFilesDir(). Les fichiers enregistrés dans ces emplacements ne sont que temporairement nécessaires, ou sont intentionnellement exclus des opérations de sauvegarde.

Vous pouvez configurer votre app pour inclure et exclure des fichiers particuliers. Pour plus d’informations, consultez la section Inclure et exclure des fichiers.

Note : Android ne traite pas la configuration des composants comme des données utilisateur. Si votre app active ou désactive des composants spécifiques dans son manifeste pendant son exécution, ne vous attendez pas à ce qu’AutoBackup enregistre et restaure la configuration. Pour préserver l’état de la configuration, enregistrez-la dans les Préférences partagées et récupérez les Préférences partagées lors de la restauration. Si vous voulez que votre application enregistre son état, enregistrez l’état dans Préférences partagées et récupérez Préférences partagées lors de la restauration.

Emplacement de la sauvegarde

Les données sauvegardées sont stockées dans un dossier privé du compte Google Drive de l’utilisateur,limité à 25 Mo par application. Les données sauvegardées ne sont pas comptabilisées dans le quota Google Drive personnel de l’utilisateur. Seule la sauvegarde la plus récente est stockée. Lorsqu’une sauvegarde est effectuée, la sauvegarde précédente (si elle existe) est supprimée. Les données de sauvegarde ne peuvent pas être lues par l’utilisateur ou par d’autres apps sur l’appareil.

Les utilisateurs peuvent voir une liste des apps qui ont été sauvegardées dans l’app Google DriveAndroid. Sur un appareil fonctionnant sous Android, les utilisateurs peuvent trouver cette liste dans le tiroir de navigation de l’appli Drive sous Paramètres > Sauvegarde et réinitialisation > Données d’applications.

Les sauvegardes de chaque durée de vie de l’appareil sont stockées dans des ensembles de données distincts, comme le montrent les exemples suivants :

• Si l’utilisateur possède deux appareils, alors un ensemble de données de sauvegarde existe pour chaque appareil.
• Si l’utilisateur réinitialise un appareil en usine, puis configure l’appareil avec le même compte, la sauvegarde est stockée dans un nouveau jeu de données. Les ensembles de données obsolètes sont automatiquement supprimés après une période d’inactivité.

Planification de la sauvegarde

Les sauvegardes se produisent automatiquement lorsque toutes les conditions suivantes sont remplies :

• L’utilisateur a activé la sauvegarde sur l’appareil. Dans Android 9, ce paramètre se trouve dansSettings > System > Backup.
• Au moins 24 heures se sont écoulées depuis la dernière sauvegarde.
• L’appareil est inactif.
• L’appareil est connecté à un réseau Wi-Fi (si l’utilisateur de l’appareil n’a pas opté pour les sauvegardes de données mobiles).

En pratique, ces conditions se produisent à peu près toutes les nuits, mais un appareil peut ne jamais effectuer de sauvegarde (par exemple, s’il ne se connecte jamais à un réseau). Pour préserver la bande passante du réseau, le téléchargement n’a lieu que si les données de l’app ont changé.

Pendant la sauvegarde automatique, le système arrête l’app pour s’assurer qu’elle n’écrit plus sur le système de fichiers. Par défaut, le système de sauvegarde ignore les apps qui s’exécutent au premier plan car les utilisateurs remarqueraient que leurs apps sont arrêtées. Vous pouvez remplacer le comportement par défaut en définissant l’attribut backupInForeground à true.

Pour simplifier les tests, Android inclut des outils qui vous permettent de lancer manuellement une sauvegarde de votre application. Pour plus d’informations, consultez la section Tester la sauvegarde et la restauration.

Planification de la restauration

Les données sont restaurées chaque fois que l’app est installée, que ce soit à partir du Play store, pendant la configuration de l’appareil (lorsque le système installe les apps précédemment installées), ou en exécutant adb install. L’opération de restauration se produit après l’installation de l’APK, mais avant que l’app soit disponible pour être lancée par l’utilisateur.

Pendant l’assistant de configuration initiale de l’appareil, l’utilisateur voit une liste de jeux de données de sauvegarde disponibles et il lui est demandé à partir duquel restaurer les données. Quel que soit le jeu de données de sauvegarde sélectionné, il devient le jeu de données ancestral de l’appareil. Le dispositif peut restaurer à partir de ses propres sauvegardes ou du jeu de données ancestral. Le dispositif donne la priorité à sa propre sauvegarde si les sauvegardes des deux sources sont disponibles. Si l’utilisateur n’est pas passé par l’assistant de configuration de l’appareil, alors l’appareil peut restaurer uniquement à partir de ses propres sauvegardes.

Pour simplifier les tests, Android inclut des outils qui vous permettent de lancer manuellement une restauration de votre application. Pour plus d’informations, consultez la section Tester la sauvegarde et la restauration.

Activer et désactiver la sauvegarde

Les apps qui ciblent Android 6.0 (niveau API 23) ou supérieur participent automatiquement à la sauvegarde automatique. Dans le fichier manifeste de votre app, définissez la valeur booléenneandroid:allowBackuppour activer ou désactiver la sauvegarde. La valeur par défaut est true mais pour que vos intentions soient claires, nous vous recommandons de définir explicitement l’attribut dans votre manifeste comme indiqué ci-dessous:

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

Vous pouvez désactiver les sauvegardes en définissant android:allowBackupfalse. Vous pourriez vouloir faire cela si votre app peut recréer son état par un autre mécanisme ou si votre app traite des informations sensibles qu’Android ne devrait pas sauvegarder.

Inclure et exclure des fichiers

Par défaut, le système sauvegarde presque toutes les données de l’app. Pour plus d’informations, consultez la section Fichiers qui sont sauvegardés. Cette section vous montre comment définir des règles XML personnalisées pour contrôler ce qui est sauvegardé.

1. Dans AndroidManifest.xml, ajoutez l’attribut android:fullBackupContent à l’élément <application>. Cet attribut pointe vers un fichier XML qui contient les règles de sauvegarde. 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. Pour inclure plusieurs fichiers, utilisez plusieurs <include> éléments.

  Note : Les fichiers des répertoires renvoyés par getCacheDir()getCodeCacheDir() ou getNoBackupFilesDir() sont toujours exclus même si vous essayez de les inclure.

• <exclude> – Spécifie un fichier ou un dossier à exclure pendant la sauvegarde. Voici quelques fichiers qui sont généralement exclus de la sauvegarde :
  • Les fichiers qui ont des identifiants spécifiques au périphérique, soit émis par un serveur, soit générés sur le périphérique. Par exemple, Google Cloud Messaging (GCM) doit générer un jeton d’enregistrement chaque fois qu’un utilisateur installe votre application sur un nouvel appareil. Si l’ancien jeton d’enregistrement est restauré, l’app peut se comporter de manière inattendue.
  • Crédentiels de compte ou autres informations sensibles. Envisagez de demander à l’utilisateur de se réauthentifier la première fois qu’il lance une app restaurée plutôt que d’autoriser le stockage de ces informations dans la sauvegarde.
  • Fichiers liés au débogage de l’app.
  • 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.

Définir les conditions de l’appareil requises pour la sauvegarde

Si votre application enregistre des informations sensibles sur l’appareil, vous pouvez spécifier des conditions sous lesquelles les données de votre application sont incluses dans la sauvegarde de l’utilisateur. Vous pouvez ajouter les conditions suivantes dans Android 9 (niveau 28 de l’API) ou plus haut :

• clientSideEncryption : La sauvegarde de l’utilisateur est chiffrée avec un secret côté client. Cette forme de cryptage est activée sur les appareils fonctionnant sous Android 9 ou plus, à condition que l’utilisateur ait activé la sauvegarde dans Android 9 ou plus et qu’il ait défini un verrouillage ascendant (PIN,motif ou mot de passe) pour son appareil.
• deviceToDeviceTransfer : L’utilisateur transfère sa sauvegarde vers un autre appareil qui prend en charge le transfert local d’appareil à appareil (par exemple,Google Pixel).

Si vous avez mis à niveau vos appareils de développement vers Android 9, vous devez désactiver puis réactiver la sauvegarde des données après la mise à niveau. En effet, Android ne chiffre les sauvegardes avec un secret côté client qu’après avoir informé les utilisateurs dans les Paramètres ou l’Assistant de configuration.

Pour déclarer les conditions d’inclusion, définissez l’attribut requireFlags à la ou aux valeurs souhaitées dans votre dans les éléments <include> au sein de votre ensemble de règles de sauvegarde :

mes règles de sauvegarde.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>

Si votre application met en œuvre un système de sauvegarde clé-valeur, ou si vous implémentez vous-mêmeBackupAgent,vous pouvez également appliquer ces exigences conditionnelles à votre logique de sauvegarde en effectuant une comparaison bit à bit entre l’ensemble des drapeaux de transport d’unBackupDataOutput objet et les drapeaux de votre agent de sauvegarde personnaliséFLAG_CLIENT_SIDE_ENCRYPTION_ENABLEDou FLAG_DEVICE_TO_DEVICE_TRANSFER.

Le bout de code suivant montre un exemple d’utilisation de cette méthode :

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. Pour utiliser la sauvegarde automatique basée sur les fichiers à la place, définissez l’attribut android:fullBackupOnlytrue dans le manifeste de votre app.

Pendant les opérations de sauvegarde et de restauration automatiques, le système lance l’app dans un mode restreint pour à la fois empêcher l’app d’accéder à des fichiers qui pourraient causer des conflits et laisser l’app exécuter des méthodes de rappel dans son BackupAgent. Dans ce mode restreint, l’activité principale de l’app n’est pas automatiquement lancée, ses fournisseurs de contenu ne sont pas initialisés et la classe de base Application est instanciée au lieu de toute sous-classe déclarée dans le manifeste de l’app.

Attention : Pour éviter les erreurs, assurez-vous que les parties de votre app qui s’exécutent en mode restreint (principalement votre BackupAgent) n’accèdent pas aux fournisseurs de contenu dans la même app ou ne tentent pas de couler l’objet Application. Si vous ne pouvez pas éviter ces schémas, envisagez alors de mettre en œuvre la sauvegarde clé/valeur ou de désactiver entièrement la sauvegarde.

Votre BackupAgent doit mettre en œuvre les méthodes abstraites onBackup() et onRestore(), qui sont utilisées pour la sauvegarde clé/valeur. Mais si vous ne voulez pas effectuer la sauvegarde des valeurs clés, vous pouvez simplement laisser votre implémentation de ces méthodes vierge.

Pour plus d’informations, voir Extending BackupAgent.