块商店

许多用户在设置新的 Android 设备时仍管理自己的凭据。手动执行此过程可能会非常困难，并且通常会导致糟糕的用户体验。Block Store API 是一个由 Google Play 服务提供支持的库，其解决方案旨在让应用能够保存用户凭据，而不会产生与保存用户密码相关的复杂性或安全风险。

借助 Block Store API，您的应用可以存储日后可在新设备上重新进行身份验证的数据。这有助于为用户提供更加顺畅的体验，因为他们在新设备上首次启动应用时无需查看登录屏幕。

使用 Block Store 的好处包括：

• 面向开发者的加密凭据存储解决方案。凭据会尽可能经过端到端加密。
• 保存令牌，而不是用户名和密码。
• 消除登录流程中的阻碍因素。
• 让用户无需管理复杂的密码，
• Google 会验证用户身份。

注意 ：使用 Block Store 不会限制用户可以使用的凭据类型。用户可以使用自己的用户名和密码登录其 Google 帐号或任何其他联合身份提供方服务，然后“块存储”仍可正常运行。

准备工作

为了让您的应用做好准备，请完成以下部分中的步骤。

配置您的应用

在项目级 build.gradle 文件中，同时在 buildscript 和 allprojects 部分添加 Google 的 Maven 代码库：

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

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

将 Block Store API 的 Google Play 服务依赖项添加到模块的 Gradle build 文件（通常为 app/build.gradle）中：

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

运作方式

Block Store 允许开发者保存和恢复最多 16 个字节数组。这样一来，您就可以保存有关当前用户会话的重要信息，并且可以根据自己的喜好灵活保存这些信息。这些数据可经过端到端加密，且支持“块存储”的基础架构构建在“备份和恢复”基础架构之上。

本指南将介绍将用户令牌保存到 Block Store 的用例。以下步骤概述了利用 Block Store 的应用的工作原理：

1. 在应用身份验证流程期间或之后的任何时间，您可以将用户的身份验证令牌存储在 Block Store 中，以便日后检索。
2. 该令牌将存储在本地，还可以尽可能备份到云端并经过端到端加密。
3. 当用户在新设备上启动恢复流程时，系统会转移数据。
4. 如果用户在恢复流程中恢复您的应用，您的应用便可以在新设备上从 Block Store 中检索已保存的令牌。

保存令牌

在用户登录您的应用时，您可以将自己为该用户生成的身份验证令牌保存到 Block Store。您可以使用唯一的密钥对值（每个条目最多 4kb）存储此令牌。如需存储令牌，请在 StoreBytesData.Builder 实例上调用 setBytes() 和 'setKey(/android/reference/com/google/android/gms/auth/blockstore/StoreBytesData.Builder.html#setKey(java.lang.String)' 以将用户的凭据存储到源设备。使用 Block Store 保存令牌后，令牌会被加密并存储在设备本地。

以下示例展示了如何将身份验证令牌保存到本地设备：

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)
    }

之前存储的键没有键？

如果您之前使用过 StoreBytes() API 保存数据，建议您先通过密钥保存令牌。 之前使用 StoreBytes 保存的数据现在通过键 BlockstoreClient.DEFAULT_BYTES_DATA_KEY 保存。

使用默认令牌

在没有键的情况下使用 StoreBytes 保存的数据会使用默认键 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)
    }

这些数据是如何存储在设备上的？谁可以访问？

在设备上，BlockStore 数据存储在 Google Play 服务的本地私有数据目录中。其他应用均无法直接访问数据文件。它们只能通过 retrieveBytes() API 访问 BlockStore 数据，而应用只能检索其自身存储的数据。Google Play 服务会检查软件包名称和签名。

检索令牌

之后，如果用户在新设备上完成恢复流程，Google Play 服务会先验证该用户，然后再检索您的块存储数据。用户已同意在恢复流程中恢复应用数据，因此无需更多用户意见征求。当用户打开您的应用时，您可以通过调用 retrieveBytes() 从块存储中请求令牌。然后，检索到的令牌可用于让用户在新设备上保持登录状态。

以下示例展示了如何根据特定密钥检索多个令牌。

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 requestedKeys = Arrays.asList(key1, key2, key3); // Add keys to array
RetrieveBytesRequest retrieveRequest = new RetrieveBytesRequest.Builder()
    .setKeys(requestedKeys)
    .build();

client.retrieveBytes(retrieveRequest)
    .addOnSuccessListener(
        result -> {
          Map blockstoreDataMap = result.getBlockstoreDataMap();
          for (Map.Entry 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)
  }

正在检索所有令牌。

以下示例展示了如何检索保存到 BlockStore 的所有令牌。

Java

BlockstoreClient client = Blockstore.getClient(this)

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

client.retrieveBytes(retrieveRequest)
    .addOnSuccessListener(
        result -> {
          Map blockstoreDataMap = result.getBlockstoreDataMap();
          for (Map.Entry 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)
  }

检索字节（已弃用）。

已废弃 retrieveBytes()，如需检索字节，可在 RetrieveBytesRequest 实例中使用 BlockstoreClient.DEFAULT_BYTES_DATA_KEY，以获取保存的数据

以下示例展示了如何检索默认键。

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)

删除令牌

出于以下原因，可能需要从 BlockStore 中删除令牌：

• 用户完成退出用户流程。
• 令牌已撤消或无效。

与检索令牌类似，您可以通过设置需要删除的键数组来指定需要删除的令牌。

以下示例展示了如何删除某些键。

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 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)

删除所有令牌

以下示例会删除当前保存到 BlockStore 中的所有令牌：

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

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

端到端加密

若要提供端到端加密，设备必须搭载 Android 9 或更高版本，且用户必须为设备设置屏幕锁定（PIN 码、解锁图案或密码）。您可以通过调用 isEndToEndEncryptionAvailable() 验证设备是否提供加密功能。

以下示例展示了如何在云备份期间验证加密是否可用：

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

注意 ：建议在启用云备份之前验证端到端加密是否可用。

启用云端备份

如需启用云端备份，请将 setShouldBackupToCloud() 方法添加到 StoreBytesData 对象中。在 setShouldBackupToCloud() 设置为 true 时，Block Store 会定期备份存储在云端的字节。

以下示例展示了如何仅在云端备份已经过端到端加密时启用云端备份：

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.")
          }
        }

注意 ：如果系统调用 shouldBackupToCloud 未设置 storeBytes 或将其设置为 false，那么下次定期同步时，系统将从云端删除此设备之前备份到云端的字节。

测试方法

在开发过程中使用以下方法可测试恢复流程。

卸载/重新安装同一设备

如果用户启用备份服务（可以在设置 > Google > 备份中检查），系统会在应用卸载/重新安装期间保留块存储数据。

您可以按照以下步骤进行测试：

1. 将 BlockStore API 集成到您的测试应用。
2. 使用测试应用调用 BlockStore API 来存储数据。
3. 卸载测试应用，然后在同一设备上重新安装您的应用。
4. 使用测试应用调用 BlockStore API 来检索您的数据。
5. 验证检索的字节是否与卸载之前存储的字节相同。

注意 ：由于测试跨设备恢复需要执行更多步骤，因此建议您先使用卸载/重新安装用例来验证您的应用与 BlockStore API 的集成。

设备到设备

在大多数情况下，这需要将目标设备恢复出厂设置。然后，您可以进入 Android 无线恢复流程或 Google 数据恢复（适用于支持的设备）。

注意 ：如果目标设备是 Samsung Galaxy，您可以在设置之外启动 Smart Switch 以进入恢复流程。

云端恢复

1. 将 Blockstore API 集成到您的测试应用。您需要将测试应用提交到 Play 商店。
2. 在源设备上，使用测试应用调用 Blockstore API 来存储您的数据，并将 shouldBackUpToCloud 设为 true。
3. 对于 Android 及更高版本的设备，您可以手动触发 Block Store 云备份：依次点击设置 > Google > 备份，然后点击“立即备份”按钮。
   1. 如需验证“块存储区”云备份成功，您可以：
      1. 备份完成后，搜索标有“CloudSyncBpTkSvc”的日志行。
      2. 您应该会看到如下内容：“......, CloudSyncBpTkSvc: sync result: SUCCESS, ..., uploaded size: XXX bytes ...”
   2. 块存储云备份之后，会有一个 5 分钟的“冷却”期。 在这 5 分钟内，点击“立即备份”按钮不会触发另一个块存储云备份。
4. 将目标设备恢复出厂设置，并完成云端恢复流程。选择在恢复流程中恢复您的测试应用。如需详细了解云恢复流程，请参阅支持的云恢复流程。
5. 在目标设备上，使用测试应用调用 Blockstore API 来检索您的数据。
6. 验证检索的字节是否与源设备中存储的字节相同。

设备要求

端到端加密

• 搭载 Android 9 (API 29) 及更高版本的设备支持端到端加密。
• 设备必须设置屏幕锁定，并提供 PIN 码、图案或密码，才能启用端到端加密功能并正确加密用户数据。

注意 ：如果不满足上述任何条件，isEndtoEndEncryptionAvailable() 将返回 false。

设备到设备恢复流程

设备到设备恢复需要您拥有源设备和目标设备。这两种设备正在传输数据。

若要备份，源设备必须搭载 Android 6 (API 23) 及更高版本。

目标设备：搭载 Android 9 (API 29) 及更高版本并能够恢复设备。

如需详细了解设备到设备恢复流程，请点击此处。

Cloud 备份和恢复流程

Cloud 备份和恢复功能需要源设备和目标设备。

若要备份，源设备必须搭载 Android 6 (API 23) 及更高版本。

目标设备取决于供应商。Pixel 设备可在 Android 9 (API 29) 中使用此功能，所有其他设备必须搭载 Android 12 (API 31) 或更高版本。