本页介绍了如何设置应用或游戏以使用 Play Integrity API。您需要启用来自 API 的响应，然后将该 API 集成到您的应用和应用后端服务器中。在 Google Play 管理中心关联用于 Play Integrity API 的 Google Cloud 项目后，即可使用更多配置选项、测试功能和报告。
启用 Play Integrity API 响应
调用 Play Integrity API 的每个应用或 SDK 都需要使用 Google Cloud 项目来监控 API 用量。Google Play 上的应用可以在 Google Play 管理中心关联 Cloud 项目以启用 Play Integrity API 响应。如果您想创建新的 Cloud 项目，或您的应用仅在 Google Play 之外分发，则可以在 Google Cloud 控制台启用 Play Integrity API 响应。
在 Google Play 管理中心设置（推荐）
在Google Play 管理中心启用 Play Integrity API 响应后，您将获得更多配置选项、测试功能和 API 报告。此选项仅适用于在 Google Play 上分发的应用。导航至 发布 > 应用完整性。在 Play Integrity API 下，选择 关联 Cloud 项目。选择您要关联到应用的 Cloud 项目，这将启用 Play Integrity API 响应。现在您可以将 Play Integrity API 集成到您的应用中了。
在 Google Cloud 控制台中设置
在您的Google Cloud 控制台中，创建一个新的 Cloud 项目或选择一个现有 Cloud 项目，用于 Play Integrity API。导航至 API 和服务。选择 启用 API 和服务。搜索Play Integrity API，然后启用。现在您可以将 Play Integrity API 集成到您的应用中了。
SDK 提供商的设置说明
SDK 提供商必须使用自己的 Google Cloud 项目来调用 Play Integrity API，这样 API 用量才会归因于 SDK，而非使用该 SDK 的各个应用。这意味着使用您的 SDK 的应用无需单独设置 Play Integrity API。您的 Play Integrity API 请求会自动计入您的 SDK 的 API 用量，而非应用的用量。
SDK 开发者有两种方式来设置 Play Integrity API：Google Play SDK Console 或 Google Cloud Console。
使用 Google Play SDK Console（推荐）
在 Google Play SDK Console 中启用 Play Integrity API 响应后，您将获得更多配置选项。导航至 SDK 完整性，然后点击 设置。在“项目配置”下选择 关联 Cloud 项目。选择您要关联到 SDK 的 Cloud 项目，这将启用 Play Integrity API 响应。现在您可以将 Play Integrity API 集成到您的 SDK 中了。请注意，访问 Google Play SDK Console 受资格要求的限制。
使用 Google Cloud 控制台
您可以在 Google Cloud 控制台启用 Play Integrity API 响应。在您的Google Cloud 控制台中，创建一个新的 Cloud 项目或选择一个现有 Cloud 项目，用于 Play Integrity API。导航至 API 和服务。选择 启用 API 和服务。搜索Play Integrity API，然后启用。现在您可以将 Play Integrity API 集成到您的 SDK 中了。
提高 SDK 的每日 Play Integrity API 请求配额
希望提高每日最大请求配额的 SDK 提供商应填写配额申请表。在开放式意见部分，请指明您正在提交 SDK 请求，并附上您的 Maven 坐标（groupId:artifactId）或您的 SDK 网址。
Play Integrity API 使用限制
您的应用每日每应用总请求上限为 10,000 次。如果您的应用需要处理更多用户，可以按照以下说明申请提高此每日上限。
| 操作 | 每日每应用配额 | 备注 |
|---|---|---|
| 令牌请求 | 10,000 | 在经典请求和标准令牌准备操作之间共享 |
| 在 Google 服务器上进行令牌解密 | 10,000 | 在经典请求和标准请求之间共享 |
提高您的每日最大请求数量
要获得提高每日最大请求数量的资格，除了任何其他分发渠道外，您的应用必须在 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 集成到您的应用或 SDK 中，请根据您的开发环境执行以下任一操作
Kotlin 或 Java
可从Google 的 Maven 代码库获取 Play Integrity API 的最新 Android 库。将以下依赖项添加到您应用的 build.gradle 文件中
implementation 'com.google.android.play:integrity:1.4.0'
Unity
以下各部分介绍如何将 Google Play Integrity API 集成到 Unity 项目并进行设置，内容涵盖受支持的 Unity 版本、安装方法和环境设置。
受支持的 Unity 版本
- 支持 2019.x、2020.x 及更高版本的所有版本。
- 如果您使用 Unity 2018.x，则支持 2018.4 或更高版本。
- 不支持 Unity 2017.x 及更早版本。
设置开发环境
OpenUPM-CLI
如果您已安装 OpenUPM CLI，可以使用以下命令安装 OpenUPM 代码库
openupm add com.google.play.integrityOpenUPM
依次选择 Unity 菜单选项 修改 > 项目设置 > 包管理器，打开包管理器设置。
将 OpenUPM 添加为包管理器窗口的作用域注册表
Name: package.openupm.com URL: https://package.openupm.com Scopes: com.google.external-dependency-manager com.google.play.common com.google.play.core com.google.play.integrity依次选择 Unity 菜单选项 窗口 > 包管理器，打开包管理器菜单。
设置管理器范围下拉菜单，选择 我的注册表。
从软件包列表中选择 适用于 Unity 的 Google Play Integrity 插件 软件包，然后按 安装。
从 GitHub 导入
从 GitHub 下载最新的
.unitypackage版本。依次选择 Unity 菜单选项 资源 > 导入软件包 > 自定义软件包，导入
.unitypackage文件和所有项。
Unreal Engine
以下各部分介绍了如何将 Google Play Integrity API 集成到 Unreal Engine 项目并进行设置。
受支持的 Unreal Engine 版本
该插件支持 Unreal Engine 5.0 及所有后续版本。
设置开发环境
从 GitHub 代码库下载 Play Unreal Engine 插件。
将
GooglePlay文件夹复制到 Unreal Engine 项目的Plugins文件夹中。打开您的 Unreal Engine 项目，然后依次点击 修改 > 插件。
搜索 Google Play 并勾选 已启用 复选框。
重新启动游戏项目并触发构建。
打开项目的
Build.cs文件，并将PlayIntegrity模块添加到PublicDependencyModuleNames中using UnrealBuildTool; public class MyGame : ModuleRules { public MyGame(ReadOnlyTargetRules Target) : base(Target) { // ... PublicDependencyModuleNames.Add("PlayIntegrity"); // ... } }
原生
安装 Play Core Native SDK 1.13.0 或更高版本。如需了解说明，请参阅 Play Core Native 的开发环境设置指南。
配置 API 响应（可选）
API 响应包含在每个请求中返回的默认裁定。如果您在 Play 管理中心设置了 Play Integrity API 集成，则可以自定义 API 响应。
默认响应
默认情况下，Play Integrity API 响应中会返回以下完整性裁定
| 响应字段 | 值 | 说明 |
|---|---|---|
| 设备完整性 | MEETS_DEVICE_INTEGRITY |
应用运行在经 Play Protect 认证的真实 Android 设备上。在 Android 13 及更高版本中，有硬件支持的证据表明设备引导加载程序已锁定，且加载的 Android OS 是经过认证的设备制造商映像。 |
| 空（空白值） | 应用运行的设备有受到攻击（例如 API Hooking）或系统遭到入侵（例如已 Root）的迹象，或者应用未运行在物理设备上（例如未通过 Google Play 完整性检查的模拟器）。 | |
| Play 帐号详情 | LICENSED |
用户拥有应用授权。换句话说，用户在其设备上通过 Google Play 安装或更新了您的应用。 |
UNLICENSED |
用户没有应用授权。例如，当用户通过非官方渠道安装您的应用或未通过 Google Play 获取应用时，就会发生这种情况。 | |
UNEVALUATED |
未评估许可详情，因为不符合某项要求。可能的原因包括以下几点
|
|
| 应用完整性 | PLAY_RECOGNIZED |
应用和证书与 Google Play 分发的版本一致。 |
UNRECOGNIZED_VERSION |
证书或软件包名称与 Google Play 记录不符。 | |
UNEVALUATED |
未评估应用完整性。不符合某项必要要求，例如设备不够可信。 |
条件响应
如果您分发到适用于 PC 的 Google Play 游戏，您将自动选择在设备完整性裁定中收到额外的标签
| 响应字段 | 标签 | 说明 |
|---|---|---|
| 设备完整性 | MEETS_VIRTUAL_INTEGRITY |
应用正在运行在由 Google Play 服务驱动的 Android 模拟器上。该模拟器通过了系统完整性检查，并符合核心 Android 兼容性要求。 |
可选响应
如果您在 Play 管理中心或 Play SDK Console 中设置了 Play Integrity API 集成，则可以选择在 API 响应中接收信息。
要更改 API 响应，请访问 Play 管理中心并导航至 发布 > 应用完整性。在 响应 下，编辑并保存您的更改。
可选设备信息和设备召回功能
应用和 SDK 可以选择在设备完整性裁定中接收其他设备标签。选择接收其他标签后，如果满足每个标签条件，完整性响应将包含同一设备的多个标签。您可以准备您的后端服务器以根据可能的响应范围做出不同的行为。例如，返回三个标签（MEETS_STRONG_INTEGRITY、MEETS_DEVICE_INTEGRITY 和 MEETS_BASIC_INTEGRITY）的设备比仅返回一个标签（MEETS_BASIC_INTEGRITY）的设备更值得信赖。
您可以选择接收设备属性，它会告诉您设备上运行的 Android OS 的 Android SDK 版本。将来，可能会扩展为包含其他设备属性。
您可以选择接收近期设备活动。近期设备活动会返回一个级别，范围从 LEVEL_1（低请求次数）到 LEVEL_4（高请求次数）。例如，返回的活动级别远高于您的应用典型水平的设备，可能是试图生成大量完整性令牌分发给不可信的设备。
应用还可以选择接收设备召回功能。设备召回功能允许您在特定设备上存储一些自定义的、基于设备的数据，当您的应用稍后在同一设备上再次安装时，可以可靠地检索这些数据。
选择接收可选设备信息和设备召回功能后，您的 API 响应将在裁定中包含新的设备完整性字段和响应
| 响应字段 | 标签 | 说明 | |
|---|---|---|---|
| 设备完整性 | MEETS_BASIC_INTEGRITY |
应用正在运行在通过基本系统完整性检查的设备上。设备的引导加载程序可以锁定或解锁，引导状态可以验证或未验证。设备可能未经 Play Protect 认证，在这种情况下，Google 无法提供任何安全、隐私或应用兼容性保证。在 Android 13 及更高版本中，MEETS_BASIC_INTEGRITY 裁定要求证明的信任根由 Google 提供。 |
|
MEETS_STRONG_INTEGRITY |
应用正在运行在带有近期安全更新的经 Play Protect 认证的真实 Android 设备上。
|
||
| 设备属性 | sdkVersion: 19, 20, ..., 36 |
设备上运行的 Android OS 的 SDK 版本。返回的数字映射到Build.VERSION_CODES。 |
|
| 空（空白值） | 未评估 SDK 版本，因为不符合某项必要要求。在这种情况下，sdkVersion 字段未设置；因此，deviceAttributes 字段为空。这可能发生的原因是
|
||
| 此设备上每应用每小时的标准 API 完整性令牌请求次数 | 此设备上每应用每小时的经典 API 完整性令牌请求次数 | ||
| 近期设备活动 | LEVEL_1（最低） |
10 次或更少 | 5 次或更少 |
LEVEL_2 |
介于 11 到 25 次之间 | 介于 6 到 10 次之间 | |
LEVEL_3 |
介于 26 到 50 次之间 | 介于 11 到 15 次之间 | |
LEVEL_4 （最高） |
超过 50 次 | 超过 15 次 | |
UNEVALUATED |
未评估近期设备活动。这可能发生的原因是
|
||
| 设备召回功能 | 值：bitFirst, bitSecond, bitThird |
这些是您过去为此特定设备设置的位值。您可以决定每个位的含义。默认情况下，这三个位值都为 false。 | |
写入日期：yyyymmFirst, yyyymmSecond, yyyymmThird |
这些是 UTC 中精确到年月日的位值写入日期。召回位的写入日期在每次将位设置为 true 时更新，在将位设置为 false 时移除。 | ||
可选环境详情
应用可以选择接收关于环境的其他裁定。通过 应用访问风险，您可以了解是否有其他正在运行的应用可能捕获屏幕、显示叠加层或控制设备。通过 Play Protect 裁定，您可以了解设备上是否启用了 Play Protect，以及是否发现了已知恶意软件。
选择接收这些裁定后，您的 API 响应将包含环境详情字段和裁定
| 响应字段 | 值 | 说明 |
|---|---|---|
| 应用访问风险裁定 | KNOWN_INSTALLED |
应用由 Google Play 安装或由设备制造商预加载到系统分区。 |
KNOWN_CAPTURING |
Google Play 安装或预加载在设备上的应用正在运行，这些应用可能用于读取或捕获请求应用的输入和输出，例如屏幕录制应用。 | |
KNOWN_CONTROLLING |
Google Play 安装或预加载在设备上的应用正在运行，这些应用可能用于控制设备以及请求应用的输入和输出，例如远程控制应用。 | |
KNOWN_OVERLAYS |
Google Play 安装或预加载在设备上的应用正在运行，这些应用可能在请求的应用上显示叠加层。 | |
UNKNOWN_INSTALLED |
安装了其他应用，这些应用并非由 Google Play 安装或由设备制造商预加载到系统分区。 | |
UNKNOWN_CAPTURING |
正在运行的其他应用（非由 Play 安装或预加载在设备上）可能用于读取或捕获请求应用的输入和输出，例如屏幕录制应用。 | |
UNKNOWN_CONTROLLING |
正在运行的其他应用（非由 Play 安装或预加载在设备上）可能用于控制设备以及请求应用的输入和输出，例如远程控制应用。 | |
UNKNOWN_OVERLAYS |
正在运行的其他应用（非由 Play 安装或预加载在设备上）可能在请求的应用上显示叠加层。 | |
| 空（空白值） | 如果缺少某项必要要求，则不会评估应用访问风险。在这种情况下，appAccessRiskVerdict 字段为空。可能的原因包括以下几点
|
|
| Play Protect 裁定 | NO_ISSUES |
Play Protect 已开启，且未在设备上发现任何应用问题。 |
NO_DATA |
Play Protect 已开启，但尚未执行任何扫描。设备或 Play 商店应用可能最近已重置。 | |
POSSIBLE_RISK |
Play Protect 已关闭。 | |
MEDIUM_RISK |
Play Protect 已开启，并在设备上发现了可能有害的应用。 | |
HIGH_RISK |
Play Protect 已开启，并在设备上发现了危险的应用。 | |
UNEVALUATED |
未评估 Play Protect 裁定。不符合某项必要要求，例如设备不够可信。 |
配置经典请求设置（可选）
如果您只计划进行标准 API 请求，请跳过此部分。
当您发出经典请求时，默认情况下，Google Play 的服务器会管理您的应用在使用 Play Integrity API 时使用的响应加密。虽然我们建议您使用此默认选项，但您也可以按照以下说明自行管理和下载响应加密密钥。
让 Google 管理您的响应加密（默认且推荐）
为了保护您应用的安全，建议您允许 Google 生成和管理您的响应加密密钥。您的后端服务器将调用 Google Play 的服务器来解密响应。
管理和下载我的响应加密密钥
如果您想在自己的安全服务器环境中本地解密完整性裁定，您可以管理和下载您的响应加密密钥。要管理和下载您的响应加密密钥，您必须使用 Play 管理中心，并且您的应用必须在 Google Play 上提供，以及在任何其他分发渠道上。按照以下说明从 Google 管理切换到自行管理的响应加密密钥。
请记住不要在客户端应用内解密或验证收到的令牌，并且绝不要将任何解密密钥暴露给客户端应用。
在您更改 Play 管理中心中的响应加密管理策略之前，请确保您的服务器已正确配置，可以在 Google Play 的服务器上解密和验证完整性令牌，以避免中断。
在 Google 管理的响应加密密钥与自行管理的响应加密密钥之间切换
如果 Google 当前管理您的响应加密，并且您想切换为自行管理和下载您的响应加密密钥，请按以下步骤操作
- 登录Play 管理中心。
- 选择一个使用 Play Integrity API 的应用。
- 在左侧菜单的 发布 部分，转到 应用完整性。
- 在 Play Integrity API 旁边，点击 设置。
- 在此页面的 经典请求 部分，在 响应加密 旁边，点击 修改。
- 在显示的窗口中，点击 管理和下载我的响应加密密钥。
- 按照说明上传公钥。
- 窗口显示上传成功后，点击 保存，您的加密密钥将自动下载。
- 修改您的服务器逻辑，以便您在自己的安全服务器环境中，使用您的响应加密密钥，本地解密和验证完整性令牌。
- （可选）当您自行管理您的响应加密密钥时，您的应用仍然可以回退到 Google Play 的服务器来解密和验证响应。
如果您自行管理您的响应加密密钥，并且想切换为让 Google 管理您的响应加密，请按以下步骤操作
- 修改您的服务器逻辑，以便您仅在 Google 的服务器上解密和验证。
- 登录Play 管理中心。
- 选择一个使用 Play Integrity API 的应用。
- 在左侧菜单的 发布 部分，转到 应用完整性。
- 在 Play Integrity API 旁边，点击 设置。
- 在此页面的 经典请求 部分，在 响应加密 旁边，点击 修改。
- 在显示的窗口中，点击 让 Google 管理我的响应加密（推荐）。
- 点击 保存更改。