块店

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

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

使用 Block Store 的好处包括:

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

准备工作

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

配置您的应用

在项目级 build.gradle 文件中,添加 Google 的 Maven 代码库buildscriptallprojects 部分:

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 保存的数据使用默认键 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)
    }

检索令牌

之后,当用户在新的设备上完成恢复流程时, 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)
  }

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

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

测试方法

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

卸载/重新安装同一设备

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

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

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

设备到设备

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

云端恢复

  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 码、图案或密码屏锁,才能启用端到端加密并正确加密用户数据。

设备间恢复流程

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

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

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

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

云端备份和恢复流程

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

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

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