此页面由 Cloud Translation API 翻译。

添加 Play Integrity API

适用于 PC 的 Play Integrity API 可帮助您检查互动和服务器请求是否来自正版 PC 设备。通过检测可能存在风险的欺诈性互动，应用的后端服务器可以采取适当的措施来防范攻击并减少滥用行为。

该 API 会返回有助于您检测潜在威胁的判定结果，包括：

存在风险的设备和环境：deviceIntegrity 判定结果可帮助您确定应用是否在正版 PC 设备或 Google Play Games 电脑版的正版实例上运行。

与 API 集成

如需将面向 PC 的 Play Integrity API 集成到您的应用中，您需要先在 Google Cloud 控制台中完成初始设置。之后，您需要针对每次完整性检查执行以下步骤：

准备完整性令牌
请求完整性令牌
请求令牌数据

在 Google Cloud 控制台中进行初始设置

每个调用 Play Integrity API 的应用或 SDK 都需要利用 Google Cloud 项目来验证其调用并监控其 API 使用情况。如果您要新建 Cloud 项目，或者您的应用专门在 Google Play 之外进行分发，则可以通过 Google Cloud 控制台启用 Play Integrity API 响应。

在 Google Cloud 控制台中，新建一个 Cloud 项目，或者选择一个要与 Play Integrity API for PC 搭配使用的现有 Cloud 项目。前往 API 和服务。选择启用 API 和服务。搜索 Play Integrity API，然后启用它。现在，您即可将 Play Integrity API 集成到您的应用中。

第 1 步：准备完整性令牌

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

在请求完整性令牌（请参阅 RequestIntegrityToken）之前，您必须先准备（或“预热”）Play Integrity API。这样一来，Google Play 便可以智能地在设备上缓存部分证明信息，以在您发出请求以获取完整性判定结果时缩短关键路径上的延迟时间。

如果成功，系统将使用包含 RequestTokenData 的 PrepareIntegrityTokenResultValue 调用 continuation，该 RequestTokenData 应用于请求完整性令牌。此数据应缓存在内存中，并在应用会话期间重复使用，以用于对 RequestIntegrityToken 的调用。只有当应用确定需要完全重新评估完整性判定结果时，才应调用 PrepareIntegrityToken。

详细信息
参数	`params`：包含 Google Cloud 项目编号的参数。 `continuation`：用于返回完整性令牌提供程序的异步回调。

第 2 步：请求完整性令牌

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

完整性令牌是一种机制，可供应用验证设备是否遭到篡改。例如，您的后端服务器可以使用完整性令牌来验证：

正版设备：确定您的应用是否在包含 Google Play Games 电脑版正版实例且未被篡改的正版设备上运行。

使用 Play Integrity API for PC 检查应用中的用户操作时，您可以利用 RequestIntegrityTokenParams::request_hash 字段来防范篡改攻击。例如，游戏可能想要将玩家得分报告给游戏后端服务器，并且您的服务器想要验证此得分没有被代理服务器篡改。Play Integrity API 会在带签名的完整性响应中返回您在此字段中设置的值。如果没有 requestHash，完整性令牌将仅绑定到设备，而不会绑定到特定请求（这可能会导致遭到攻击）。

在请求完整性判定时，为了缓解此问题，请执行以下操作：

计算正在发生的用户操作或服务器请求中的所有相关请求参数（例如，稳定请求序列化的 SHA256）的摘要。
将 RequestIntegrityTokenParams::request_hash 字段设置为摘要。

详细信息
参数	`params`：包含准备好的 RequestTokenData 和完整性检查请求哈希的参数。 `continuation`：用于返回数据的异步回调。

第 3 步：请求令牌数据

在您请求完整性判定后，Play Integrity API 会提供加密的响应令牌。如需获取设备完整性判定，您必须在 Google 服务器上解密完整性令牌。为此，请完成以下步骤：

在与您的应用关联的 Google Cloud 项目中创建一个服务账号。

在应用服务器上，使用 playintegrity 范围从服务账号凭据中提取访问令牌，然后发出以下请求：

playintegrity.googleapis.com/v1/<var>PACKAGE_NAME</var>:decodePcIntegrityToken -d \
 '{ "integrity_token": "<var>INTEGRITY_TOKEN</var>" }'

读取 JSON 响应。

生成的载荷是包含完整性判定结果和详细信息以及开发者提供的信息的纯文本令牌。令牌格式如下：

{
  "requestDetails": { ... },
  "deviceIntegrity": { ... },
}

您必须先检查 requestDetails 字段中的值是否与原始请求的值相符，然后再检查每个完整性判定结果。下面几部分详细介绍了各个字段。

请求详情字段

requestDetails 字段包含与请求相关的信息，其中包括 requestHash（适用于标准请求）和 nonce（适用于传统请求）中由开发者提供的信息。

"requestDetails": {
  // Application package name this attestation was requested for.
  // Note that this field might be spoofed in the middle of the request.
  "requestPackageName": "com.package.name",
  // The timestamp when the integrity token was requested.
  "requestTime": "1675655009345"
  // Request hash provided by the developer.
  "requestHash": "aGVsbG8gd29scmQgdGhlcmU",
}

这些值应与原始请求中的值相符。因此，请验证 JSON 载荷的 requestDetails 部分，确保 requestPackageName 和 requestHash 与原始请求中发送的内容相符。

设备完整性字段

deviceIntegrity 字段可以包含单个值 deviceRecognitionVerdict；该值具有一个或多个标签，用来表示设备可以在多大程度上满足执行应用完整性检查的条件。如果设备不满足任何标签的条件，则 deviceIntegrity 字段会省略 deviceRecognitionVerdict。

"deviceIntegrity": {
  "deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}

默认情况下，deviceRecognitionVerdict 可包含以下内容：

MEETS_PC_INTEGRITY: 如果应用在正版 PC 环境中运行，且未检测到设备端篡改，则返回判定结果。
空（空白值）: 运行应用的设备存在遭受攻击（如 API 挂接）或系统被入侵（如取得 root 权限后入侵）的迹象，或者不是实体设备（如未通过 Google Play 完整性检查的模拟器）。

使用限制

Play Integrity API 使用量限制

您的应用每天最多只能发出共 10,000 次请求。如果您的应用需要处理更多用户，您可以按照以下说明申请提高此每日上限。

操作	每个应用的每日配额	备注
令牌请求	10000	在 Play Integrity API（PC 版）以及 Play Integrity API（传统和标准请求）之间共享
在 Google 服务器上解密令牌	10000	在 Play Integrity API（PC 版）以及 Play Integrity API（传统和标准请求）之间共享

提高您的每日请求次数上限

若要符合提高每日请求次数上限的条件，您的应用除了要能通过任何其他渠道分发外，还必须在 Google Play 上架。

如需申请提高请求的每日次数上限，请按以下步骤操作：

在 Play 管理中心内关联要与 Play Integrity API 搭配使用的 Google Cloud 项目。
验证您是否正确实现了 API 逻辑（包括建议的重试策略）。
请使用此表单申请增加配额。

增加 Play Integrity API 配额最多可能需要一周时间，因此我们强烈建议您在 Google Play 管理中心或 Google Cloud 控制台内监控 Play Integrity API 使用情况；此外，您还可以在 Google Cloud 控制台设置配额提醒，以免服务中断。

配额增加会自动应用于客户端调用以生成完整性令牌，并会自动应用于服务器调用以解密和验证完整性令牌。

安全注意事项

如果您遵循以下推荐做法，Play Integrity API 可为您的应用带来最大价值：

制定反滥用策略

将 Play Integrity API 与其他信号一起使用时，让其作为整体反滥用策略的一部分，而不是作为唯一的反滥用机制，这时该 API 效果最佳。在应用中使用该 API 时，请同时搭配使用其他适当的安全性最佳实践。默认情况下，应用每天最多可针对所有安装发出共 10,000 次请求，您可以请求提高每日上限。

收集遥测数据并了解受众群体，再采取行动

在根据 Play Integrity API 判定结果更改应用的行为方式之前，您可以先实现该 API，但不进行违规处置，以了解现有受众群体的当前状况。了解当前安装群体返回的判定结果后，就可以预估计划采取的任何违规处置的影响，并相应地调整反滥用策略。

适时请求完整性判定

您应尽可能在要防范的操作或服务器请求发生时发出 API 请求。

使 API 请求难以复制

API 请求具有一个名为 requestHash 的字段，用于防范篡改和类似攻击。在该字段中，您应添加应用请求中所有相关值的摘要。请遵循有关如何使用内容绑定的指南来保护应用的标准请求。

避免缓存完整性判定

缓存完整性判定会增加发生代理攻击的风险。在代理攻击中，作恶方会重复使用来自正常设备的判定结果，以便在其他环境中滥用。

从服务器向应用发送一系列响应

与其每次都将二进制“允许”/“拒绝”响应从服务器发送回应用，不如提供一系列决策结果，因为这样可以增加复制难度。例如，您可以使用一系列相关的响应，如“允许”“允许但有限制”“CAPTCHA 完成后允许但有限制”和“拒绝”。

显示可执行操作的错误消息

尽可能向用户提供有用的错误消息，并告诉用户可以采取哪些措施来解决问题。

针对意外问题或服务中断制定计划

Play 状态信息中心会显示有关 Play Integrity API 服务状态的信息，以及任何服务暂停和中断的相关信息。您应该预先规划，万一发生大规模 Play Integrity API 服务中断时，您希望后端服务器如何运行。

服务条款和数据安全

访问或使用 Play Integrity API for PC 即表示您同意接受 Play Integrity API 服务条款。请先阅读并了解所有适用的条款及政策，然后再访问该 API。

Google Play 有一个“数据安全”部分，供开发者披露其应用的数据收集、分享和安全做法，以便用户及时了解相关信息。为了帮助您填写数据表单，请参阅有关 Play Integrity API 如何处理数据的信息。