Bloquer le magasin

Important : Pour une expérience utilisateur actualisée et d'autres améliorations, envisagez d'utiliser des clés d'accès avec Credential Manager.

De nombreux utilisateurs gèrent encore leurs propres identifiants lorsqu'ils configurent un nouvel appareil Android. Ce processus manuel peut devenir difficile et entraîne souvent une mauvaise expérience utilisateur. L'API Block Store, une bibliothèque fournie par les services Google Play, cherche à résoudre ce problème en permettant aux applications d'enregistrer les identifiants des utilisateurs sans la complexité ni les risques de sécurité associés à l'enregistrement des mots de passe.

L'API Block Store permet à votre application de stocker des données qu'elle pourra récupérer ultérieurement pour réauthentifier les utilisateurs sur un nouvel appareil. Cela permet d'offrir une expérience plus fluide à l'utilisateur, car il n'a pas besoin de voir un écran de connexion lorsqu'il lance votre application pour la première fois sur le nouvel appareil.

Voici les avantages de l'utilisation de Block Store :

• Solution de stockage des identifiants chiffrés pour les développeurs. Les identifiants sont chiffrés de bout en bout lorsque cela est possible.
• Enregistrez des jetons au lieu de noms d'utilisateur et de mots de passe.
• Éliminez les frictions des flux de connexion.
• Épargnez aux utilisateurs la gestion de mots de passe complexes.
• Google vérifie l'identité de l'utilisateur.

Remarque : L'utilisation de Block Store ne limite pas l'utilisateur au type d'identifiants pouvant être utilisés. Les utilisateurs peuvent se connecter avec leur nom d'utilisateur et leur mot de passe, leur compte Google ou tout autre fournisseur d'identité fédéré, et Block Store fonctionne toujours.

Avant de commencer

Pour préparer votre application, procédez comme indiqué dans les sections suivantes.

Configurer votre application

Dans votre fichier build.gradle au niveau du projet, ajoutez le dépôt Maven de Google aux sections buildscript et allprojects :

buildscript {
  repositories {
    google()
    mavenCentral()
  }
}

allprojects {
  repositories {
    google()
    mavenCentral()
  }
}

Ajoutez la dépendance des services Google Play pour l'API Block Store au fichier de compilation Gradle de votre module, qui est généralement app/build.gradle :

dependencies {
  implementation 'com.google.android.gms:play-services-auth-blockstore:16.4.0'
}

Fonctionnement

Block Store permet aux développeurs d'enregistrer et de restaurer jusqu'à 16 tableaux d'octets. Cela vous permet d'enregistrer des informations importantes concernant la session utilisateur actuelle et vous offre la flexibilité de les enregistrer comme vous le souhaitez. Ces données peuvent être chiffrées de bout en bout, et l'infrastructure compatible avec Block Store repose sur l'infrastructure de sauvegarde et de restauration.

Ce guide décrit le cas d'utilisation de l'enregistrement du jeton d'un utilisateur dans Block Store. Voici comment fonctionne une application utilisant Block Store :

1. Pendant le flux d'authentification de votre application, ou à tout moment par la suite, vous pouvez stocker le jeton d'authentification de l'utilisateur dans Block Store pour le récupérer ultérieurement.
2. Le jeton sera stocké localement et pourra également être sauvegardé dans le cloud, avec un chiffrement de bout en bout lorsque cela est possible.
3. Les données sont transférées lorsque l'utilisateur lance un flux de restauration sur un nouvel appareil.
4. Si l'utilisateur restaure votre application pendant le processus de restauration, votre application peut alors récupérer le jeton enregistré à partir de Block Store sur le nouvel appareil.

Enregistrer le jeton

Lorsqu'un utilisateur se connecte à votre application, vous pouvez enregistrer le jeton d'authentification que vous générez pour cet utilisateur dans Block Store. Vous pouvez stocker ce jeton à l'aide d'une valeur de paire de clés unique d'une taille maximale de 4 ko par entrée. Pour stocker le jeton, appelez setBytes() et setKey() sur une instance de StoreBytesData.Builder afin de stocker les identifiants de l'utilisateur sur l'appareil source. Une fois que vous avez enregistré le jeton avec Block Store, il est chiffré et stocké localement sur l'appareil.

L'exemple suivant montre comment enregistrer le jeton d'authentification sur l'appareil local :

Java

BlockstoreClient client = Blockstore.getClient(this);
byte[] bytes1 = new byte[] { 1, 2, 3, 4 };  // Store one data block.
String key1 = "com.example.app.key1";
StoreBytesData storeRequest1 = StoreBytesData.Builder()
        .setBytes(bytes1)
        // Call this method to set the key-value pair the data should be associated with.
        .setKeys(Arrays.asList(key1))
        .build();
client.storeBytes(storeRequest1)
  .addOnSuccessListener(result -> Log.d(TAG, "stored " + result + " bytes"))
  .addOnFailureListener(e -> Log.e(TAG, "Failed to store bytes", e));

Kotlin

val client = Blockstore.getClient(this)

val bytes1 = byteArrayOf(1, 2, 3, 4) // Store one data block.
val key1 = "com.example.app.key1"
val storeRequest1 = StoreBytesData.Builder()
  .setBytes(bytes1) // Call this method to set the key value with which the data should be associated with.
  .setKeys(Arrays.asList(key1))
  .build()
client.storeBytes(storeRequest1)
  .addOnSuccessListener { result: Int ->
    Log.d(TAG,
          "Stored $result bytes")
  }
  .addOnFailureListener { e ->
    Log.e(TAG, "Failed to store bytes", e)
  }

Remarque : Vous avez déjà stocké des octets sans clé ? Si vous avez déjà utilisé l'API StoreBytes() pour enregistrer vos données, nous vous recommandons de commencer à enregistrer vos jetons avec une clé. Les données précédemment enregistrées à l'aide de StoreBytes sont désormais enregistrées avec la clé BlockstoreClient.DEFAULT_BYTES_DATA_KEY.

Utiliser le jeton par défaut

Les données enregistrées à l'aide de StoreBytes sans clé utilisent la clé par défaut BlockstoreClient.DEFAULT_BYTES_DATA_KEY.

Java

BlockstoreClient client = Blockstore.getClient(this);
// The default key BlockstoreClient.DEFAULT_BYTES_DATA_KEY.
byte[] bytes = new byte[] { 9, 10 };
StoreBytesData storeRequest = StoreBytesData.Builder()
        .setBytes(bytes)
        .build();
client.storeBytes(storeRequest)
  .addOnSuccessListener(result -> Log.d(TAG, "stored " + result + " bytes"))
  .addOnFailureListener(e -> Log.e(TAG, "Failed to store bytes", e));

Kotlin

val client = Blockstore.getClient(this);
// the default key BlockstoreClient.DEFAULT_BYTES_DATA_KEY.
val bytes = byteArrayOf(1, 2, 3, 4)
val storeRequest = StoreBytesData.Builder()
  .setBytes(bytes)
  .build();
client.storeBytes(storeRequest)
  .addOnSuccessListener { result: Int ->
    Log.d(TAG,
          "stored $result bytes")
  }
  .addOnFailureListener { e ->
    Log.e(TAG, "Failed to store bytes", e)
  }

Remarque : Sur l'appareil, les données Block Store sont stockées dans le répertoire de données privées local des services Google Play. Aucune autre application ne peut accéder directement au fichier de données. Elles ne peuvent accéder aux données Block Store qu'à l'aide de l'API retrieveBytes(), et une application ne peut récupérer que les données qu'elle a elle-même stockées. Les services Google Play vérifient à la fois le nom du package et la signature.

Récupérer le jeton

Plus tard, lorsqu'un utilisateur suit le processus de restauration sur un nouvel appareil, les services Google Play vérifient d'abord l'utilisateur, puis récupèrent vos données Block Store. L'utilisateur a déjà accepté de restaurer les données de votre application dans le cadre du flux de restauration. Aucune autorisation supplémentaire n'est donc requise. Lorsque l'utilisateur ouvre votre application, vous pouvez demander votre jeton à Block Store en appelant retrieveBytes(). Le jeton récupéré peut ensuite être utilisé pour maintenir la connexion de l'utilisateur sur le nouvel appareil.

L'exemple suivant montre comment récupérer plusieurs jetons en fonction de clés spécifiques.

Java

BlockstoreClient client = Blockstore.getClient(this);

// Retrieve data associated with certain keys.
String key1 = "com.example.app.key1";
String key2 = "com.example.app.key2";
String key3 = BlockstoreClient.DEFAULT_BYTES_DATA_KEY; // Used to retrieve data stored without a key

List<String> requestedKeys = Arrays.asList(key1, key2, key3); // Add keys to array
RetrieveBytesRequest retrieveRequest = new RetrieveBytesRequest.Builder()
    .setKeys(requestedKeys)
    .build();

client.retrieveBytes(retrieveRequest)
    .addOnSuccessListener(
        result -> {
          Map<String, BlockstoreData> blockstoreDataMap = result.getBlockstoreDataMap();
          for (Map.Entry<String, BlockstoreData> entry : blockstoreDataMap.entrySet()) {
            Log.d(TAG, String.format(
                "Retrieved bytes %s associated with key %s.",
                new String(entry.getValue().getBytes()), entry.getKey()));
          }
        })
    .addOnFailureListener(e -> Log.e(TAG, "Failed to store bytes", e));

Kotlin

val client = Blockstore.getClient(this)

// Retrieve data associated with certain keys.
val key1 = "com.example.app.key1"
val key2 = "com.example.app.key2"
val key3 = BlockstoreClient.DEFAULT_BYTES_DATA_KEY // Used to retrieve data stored without a key

val requestedKeys = Arrays.asList(key1, key2, key3) // Add keys to array

val retrieveRequest = RetrieveBytesRequest.Builder()
  .setKeys(requestedKeys)
  .build()

client.retrieveBytes(retrieveRequest)
  .addOnSuccessListener { result: RetrieveBytesResponse ->
    val blockstoreDataMap =
      result.blockstoreDataMap
    for ((key, value) in blockstoreDataMap) {
      Log.d(ContentValues.TAG, String.format(
        "Retrieved bytes %s associated with key %s.",
        String(value.bytes), key))
    }
  }
  .addOnFailureListener { e: Exception? ->
    Log.e(ContentValues.TAG,
          "Failed to store bytes",
          e)
  }

Récupération de tous les jetons…

L'exemple suivant montre comment récupérer tous les jetons enregistrés dans BlockStore.

Java

BlockstoreClient client = Blockstore.getClient(this)

// Retrieve all data.
RetrieveBytesRequest retrieveRequest = new RetrieveBytesRequest.Builder()
    .setRetrieveAll(true)
    .build();

client.retrieveBytes(retrieveRequest)
    .addOnSuccessListener(
        result -> {
          Map<String, BlockstoreData> blockstoreDataMap = result.getBlockstoreDataMap();
          for (Map.Entry<String, BlockstoreData> entry : blockstoreDataMap.entrySet()) {
            Log.d(TAG, String.format(
                "Retrieved bytes %s associated with key %s.",
                new String(entry.getValue().getBytes()), entry.getKey()));
          }
        })
    .addOnFailureListener(e -> Log.e(TAG, "Failed to store bytes", e));

Kotlin

val client = Blockstore.getClient(this)

val retrieveRequest = RetrieveBytesRequest.Builder()
    .setRetrieveAll(true)
    .build()

  client.retrieveBytes(retrieveRequest)
    .addOnSuccessListener { result: RetrieveBytesResponse ->
      val blockstoreDataMap =
        result.blockstoreDataMap
      for ((key, value) in blockstoreDataMap) {
        Log.d(ContentValues.TAG, String.format(
          "Retrieved bytes %s associated with key %s.",
          String(value.bytes), key))
      }
    }
    .addOnFailureListener { e: Exception? ->
      Log.e(ContentValues.TAG,
            "Failed to store bytes",
            e)
    }

Remarque : Abandon de retrieveBytes() retrieveBytes() est désormais obsolète. Pour récupérer des octets, la clé BlockstoreClient.DEFAULT_BYTES_DATA_KEY peut être utilisée dans l'instance RetrieveBytesRequest afin d'obtenir vos données enregistrées.

L'exemple suivant montre comment récupérer la clé par défaut.

Java

BlockStoreClient client = Blockstore.getClient(this);
RetrieveBytesRequest retrieveRequest = new RetrieveBytesRequest.Builder()
    .setKeys(Arrays.asList(BlockstoreClient.DEFAULT_BYTES_DATA_KEY))
    .build();
client.retrieveBytes(retrieveRequest);

Kotlin

val client = Blockstore.getClient(this)

val retrieveRequest = RetrieveBytesRequest.Builder()
  .setKeys(Arrays.asList(BlockstoreClient.DEFAULT_BYTES_DATA_KEY))
  .build()
client.retrieveBytes(retrieveRequest)

Supprimer des jetons

La suppression de jetons de BlockStore peut être nécessaire pour les raisons suivantes :

• L'utilisateur suit le parcours utilisateur de déconnexion.
• Le jeton a été révoqué ou n'est pas valide.

Comme pour la récupération de jetons, vous pouvez spécifier les jetons à supprimer en définissant un tableau de clés à supprimer.

L'exemple suivant montre comment supprimer certaines clés :

Java

BlockstoreClient client = Blockstore.getClient(this);

// Delete data associated with certain keys.
String key1 = "com.example.app.key1";
String key2 = "com.example.app.key2";
String key3 = BlockstoreClient.DEFAULT_BYTES_DATA_KEY; // Used to delete data stored without key

List<String> requestedKeys = Arrays.asList(key1, key2, key3) // Add keys to array
DeleteBytesRequest deleteRequest = new DeleteBytesRequest.Builder()
        .setKeys(requestedKeys)
        .build();
client.deleteBytes(deleteRequest)

Kotlin

val client = Blockstore.getClient(this)

// Retrieve data associated with certain keys.
val key1 = "com.example.app.key1"
val key2 = "com.example.app.key2"
val key3 = BlockstoreClient.DEFAULT_BYTES_DATA_KEY // Used to retrieve data stored without a key

val requestedKeys = Arrays.asList(key1, key2, key3) // Add keys to array

val retrieveRequest = DeleteBytesRequest.Builder()
      .setKeys(requestedKeys)
      .build()

client.deleteBytes(retrieveRequest)

Supprimer tous les jetons

L'exemple suivant montre comment supprimer tous les jetons enregistrés dans Block Store :

Java

// Delete all data.
DeleteBytesRequest deleteAllRequest = new DeleteBytesRequest.Builder()
        .setDeleteAll(true)
        .build();
client.deleteBytes(deleteAllRequest)
  .addOnSuccessListener(result -> Log.d(TAG, "Any data found and deleted? " + result));

Kotlin

// Delete all data.
val deleteAllRequest = DeleteBytesRequest.Builder()
        .setDeleteAll(true)
        .build()
client.deleteBytes(deleteAllRequest)
  .addOnSuccessListener { result -> Log.d(TAG, "Any data found and deleted? $result") }

Chiffrement de bout en bout

Pour que le chiffrement de bout en bout soit disponible, l'appareil doit être équipé d'Android 9 ou version ultérieure, et l'utilisateur doit avoir défini un verrouillage de l'écran (code, schéma ou mot de passe) pour son appareil. Vous pouvez vérifier si le chiffrement sera disponible sur l'appareil en appelant isEndToEndEncryptionAvailable().

L'exemple suivant montre comment vérifier si le chiffrement sera disponible lors de la sauvegarde cloud :

client.isEndToEndEncryptionAvailable()
        .addOnSuccessListener { result ->
          Log.d(TAG, "Will Block Store cloud backup be end-to-end encrypted? $result")
        }

Remarque : Nous vous recommandons de vérifier que le chiffrement de bout en bout est disponible avant d'activer la sauvegarde cloud.

Activer la sauvegarde cloud

Pour activer la sauvegarde cloud, ajoutez la méthode setShouldBackupToCloud() à votre objet StoreBytesData. Block Store sauvegarde régulièrement dans le cloud les octets stockés lorsque setShouldBackupToCloud() est défini sur "true".

L'exemple suivant montre comment activer la sauvegarde cloud uniquement lorsqu'elle est chiffrée de bout en bout :

val client = Blockstore.getClient(this)
val storeBytesDataBuilder = StoreBytesData.Builder()
        .setBytes(/* BYTE_ARRAY */)

client.isEndToEndEncryptionAvailable()
        .addOnSuccessListener { isE2EEAvailable ->
          if (isE2EEAvailable) {
            storeBytesDataBuilder.setShouldBackupToCloud(true)
            Log.d(TAG, "E2EE is available, enable backing up bytes to the cloud.")

            client.storeBytes(storeBytesDataBuilder.build())
                .addOnSuccessListener { result ->
                  Log.d(TAG, "stored: ${result.getBytesStored()}")
                }.addOnFailureListener { e ->
                  Log.e(TAG, "Failed to store bytes", e)
                }
          } else {
            Log.d(TAG, "E2EE is not available, only store bytes for D2D restore.")
          }
        }

Remarque : Si storeBytes est appelé avec shouldBackupToCloud non défini ou défini sur false, les octets de cet appareil précédemment sauvegardés dans le cloud seront supprimés du cloud lors de la prochaine synchronisation périodique.

Comment tester

Utilisez les méthodes suivantes pendant le développement pour tester les flux de restauration.

Désinstallation et réinstallation sur le même appareil

Si l'utilisateur active les services de sauvegarde (vous pouvez le vérifier dans Paramètres > Google > Sauvegarde), les données Block Store sont conservées lors de la désinstallation et de la réinstallation d'une application.

Pour ce faire, procédez comme suit :

1. Intégrez l'API Block Store à votre application de test.
2. Utilisez l'application de test pour appeler l'API Block Store afin de stocker vos données.
3. Désinstallez votre application de test, puis réinstallez-la sur le même appareil.
4. Utilisez l'application de test pour appeler l'API Block Store afin de récupérer vos données.
5. Vérifiez que les octets récupérés sont identiques à ceux stockés avant la désinstallation.

Remarque : Étant donné que le test de la restauration multi-appareil nécessite plus d'étapes, nous vous recommandons de commencer par vérifier l'intégration de votre application à l'API Block Store en utilisant le cas de désinstallation et de réinstallation.

D'appareil à appareil

Dans la plupart des cas, cela nécessite de rétablir la configuration d'usine de l'appareil cible. Vous pouvez ensuite accéder au processus de restauration sans fil Android ou à la restauration par câble Google (pour les appareils compatibles).

Remarque : Si l'appareil cible est un Samsung Galaxy, vous pouvez lancer le processus de restauration en lançant Smart Switch en dehors de la configuration.

Restauration cloud

1. Intégrez l'API Block Store à votre application de test. L'application de test doit être envoyée au Play Store.
2. Sur l'appareil source, utilisez l'application de test pour appeler l'API Block Store afin de stocker vos données, avec shouldBackUpToCloud défini sur true.
3. Sur les appareils équipés d'Android 8.0 (niveau d'API 26) ou version ultérieure, vous pouvez déclencher manuellement une sauvegarde cloud Block Store : accédez à Paramètres > Google > Sauvegarde, puis cliquez sur le bouton "Sauvegarder maintenant".
   1. Pour vérifier que la sauvegarde cloud Block Store a réussi, vous pouvez :
      1. Une fois la sauvegarde terminée, recherchez les lignes de journal contenant la balise [CloudSyncBackupTaskService].
      2. Vous devriez voir des lignes comme celles-ci : ..., [CloudSyncBackupTaskService] sync result: SUCCESS, ..., uploaded size: [size] bytes ...
   2. Après une sauvegarde cloud Block Store, une période de "refroidissement" de cinq minutes est appliquée. Pendant ces cinq minutes, cliquer sur le bouton "Sauvegarder maintenant" ne déclenchera pas d'autre sauvegarde cloud Block Store.
4. Rétablissez la configuration d'usine de l'appareil cible et suivez la procédure de restauration dans le cloud. Sélectionnez cette option pour restaurer votre application de test pendant le flux de restauration. Pour en savoir plus sur les flux de restauration cloud, consultez Flux de restauration cloud compatibles.
5. Sur l'appareil cible, utilisez l'application de test pour appeler l'API Block Store afin de récupérer vos données.
6. Vérifiez que les octets récupérés sont identiques à ceux stockés sur l'appareil source.

Conditions requises concernant l'appareil

Examinez les exigences suivantes pour les appareils participant aux opérations Block Store.

Chiffrement de bout en bout

• Le chiffrement de bout en bout est compatible avec les appareils équipés d'Android 9 (API 29) ou version ultérieure.
• L'appareil doit disposer d'un verrouillage de l'écran défini avec un code, un schéma ou un mot de passe pour que le chiffrement de bout en bout soit activé et chiffre correctement les données de l'utilisateur.

Remarque : isEndtoEndEncryptionAvailable() renvoie "false" si l'une de ces conditions n'est pas remplie.

Flux de restauration d'un appareil à un autre

La restauration d'appareil à appareil nécessite un appareil source et un appareil cible. Il s'agit des deux appareils entre lesquels les données sont transférées.

Les appareils sources doivent exécuter Android 6 (API 23) ou une version ultérieure pour effectuer une sauvegarde.

Ciblez les appareils équipés d'Android 9 (API 29) ou version ultérieure pour pouvoir effectuer la restauration.

Pour en savoir plus sur le flux de restauration d'appareil à appareil, consultez Flux de restauration d'appareil à appareil compatibles.

Flux de sauvegarde et de restauration dans le cloud

La sauvegarde dans le cloud et la restauration nécessitent un appareil source et un appareil cible.

Les appareils sources doivent exécuter Android 6 (API 23) ou une version ultérieure pour effectuer une sauvegarde.

Les appareils cibles sont compatibles en fonction de leurs fournisseurs. Les appareils Pixel peuvent utiliser cette fonctionnalité à partir d'Android 9 (API 29). Tous les autres appareils doivent exécuter Android 12 (API 31) ou version ultérieure.