块店

注意：要获得更新的用户体验和其他改进，请考虑使用 请改为 使用 Credential Manager 的通行密钥 。

许多用户在设置新的 Android 设备时仍会管理自己的凭据 设备。这种手动流程可能颇具挑战性，并且往往会导致 用户体验。Block Store API，一个由 Google Play 提供支持的库 服务的解决方案，希望通过提供一种方式来节省 既省去了保存用户凭据的复杂性或安全风险 用户密码

Block Store API 可让您的应用存储数据，以便日后使用 检索以在新设备上对用户重新进行身份验证。这有助于提供更多 为用户提供无缝的体验，因为他们不需要看到登录屏幕 。

使用 Block Store 的好处包括：

• 面向开发者的加密凭据存储解决方案。凭据 会尽可能进行端到端加密
• 保存令牌，而不是用户名和密码。
• 消除登录流程中的不便。
• 让用户不必再费心管理复杂的密码。
• Google 会验证用户的身份。

。

注意： 使用块存储不会限制用户只能提供哪些类型的凭据 。用户可以使用自己的用户名和密码、自己的 Google 账号 账号或任何其他联合身份提供方，而 Block Store 仍然可以正常运行。

准备工作

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

配置您的应用

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

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

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

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

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

工作原理

Block Store 允许开发者保存和恢复最多 16 字节的数组。 这样，您就可以保存有关当前用户会话的重要信息，并且可以按照自己喜欢的方式灵活保存这些信息。这些数据可以进行端到端加密，支持 Block Store 的基础架构建立在“备份和恢复”基础架构之上。

本指南将介绍将用户的令牌保存到 Block Store 的用例。 以下步骤概述了使用 Block Store 的应用的运作方式：

1. 在应用的身份验证流程中或之后的任何时间，您都可以存储 将用户的身份验证令牌发送到 Block Store，以便日后检索。
2. 令牌将存储在本地，也可以备份到云端 会尽可能进行端到端加密
3. 当用户在新设备上启动恢复流程时，系统会传输数据。
4. 如果用户在恢复流程中恢复应用，则应用随后可以 在新设备上从 Block Store 中检索已保存的令牌。

保存令牌

当用户登录您的应用时，您可以将为该用户生成的身份验证令牌保存到 Block Store。您可以使用唯一密钥对值存储此令牌，每个条目的大小不得超过 4kb。 如需存储令牌，请调用 setBytes() 和setKey() 在 StoreBytesData.Builder 将用户凭据存储到源设备。保存令牌后 使用 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 服务会先验证用户，然后再检索您的“屏蔽” 存储数据。用户已同意恢复您的应用数据， 因此无需额外征得同意用户打开 您可以调用以下代码，从 Block Store 请求令牌 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<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)
  }

正在检索所有令牌。

以下示例展示了如何检索保存到 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)
  }

retrieveBytes() 弃用。

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 对象。Block Store 会定期将 setShouldBackupToCloud() 设置为 true。

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

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

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

测试方法

在开发期间使用以下方法测试恢复 流量。

卸载/重新安装同一设备

如果用户启用了备份服务 （您可以依次前往设置 > Google > 备份进行检查），“屏蔽商店数据”为 在应用卸载/重新安装后保持不变

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

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

。

注意： 由于测试跨设备恢复功能需要执行更多步骤，因此建议 先使用 卸载/重新安装支持请求。

设备到设备

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

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

云端恢复

1. 将 Blockstore API 集成到您的测试应用。测试应用需要 提交至 Play 商店
2. 在源设备上，使用测试应用调用 Blockstore API 以存储 并将 shouldBackUpToCloud 设置为 true。
3. 对于 Android O 及更高版本的设备，您可以手动触发 Block Store 云备份： 转到设置 >Google >备份后，点击“立即备份”按钮。
   1. 如需验证 Block Store 云备份是否成功，您可以执行以下操作： <ph type="x-smartling-placeholder">
      </ph>
      1. 备份完成后，搜索带有标记的日志行 “CloudSyncBpTkSvc”。
      2. 您应该会看到如下所示的行：“......, CloudSyncBpTkSvc: sync 结果：SUCCESS，...，上传大小：XXX 字节 ...”
   2. 在 Block Store 云备份之后，会有 5 分钟的“冷却”期。 在这 5 分钟内，不会触发点击“立即备份”按钮 另一项 Block Store 云备份。
4. 将目标设备恢复出厂设置，然后执行云端恢复流程。选择 在恢复流程中恢复测试应用。如需详细了解 云恢复流程，请参阅支持的云恢复流程。
5. 在目标设备上，使用测试应用调用 Blockstore API， 检索您的数据。
6. 验证检索到的字节数是否与 音频源设备。

设备要求

端到端加密

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

。

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

设备间恢复流程

如要进行设备到设备恢复，您必须拥有源设备和目标设备。这两个设备将用来传输数据。

源设备必须搭载 Android 6 (API 23) 及更高版本才能进行备份。

定位搭载 Android 9 (API 29) 及更高版本的设备，以便能够进行恢复。

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

云端备份和恢复流程

云端备份和恢复功能将需要使用源设备和目标设备。

源设备必须搭载 Android 6 (API 23) 及更高版本才能进行备份。

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