本页介绍了如何设置您的应用或游戏以使用 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 项目，或者选择一个要与 Play Integrity API 搭配使用的现有 Cloud 项目。前往 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 使用量，而非应用的 API 使用量。
SDK 开发者可以通过以下两种方式设置 Play Integrity API：Google Play SDK 管理中心或 Google Cloud 控制台。
使用 Google Play SDK 管理中心（推荐）
通过在 Google Play SDK 管理中心内启用 Play Integrity API 响应，您将能够使用额外的配置选项。前往 SDK 完整性，然后点击 Settings。在“项目配置”下，选择关联 Cloud 项目。选择要关联到 SDK 的 Cloud 项目，此操作即会启用 Play Integrity API 响应。现在，您即可将 Play Integrity API 集成到您的 SDK 中。请注意，您必须满足资格条件，才能访问 Google Play SDK 管理中心。
使用 Google Cloud 控制台
您可以通过 Google Cloud 控制台启用 Play Integrity API 响应。在 Google Cloud 控制台中，新建一个 Cloud 项目，或者选择一个要与 Play Integrity API 搭配使用的现有 Cloud 项目。前往 API 和服务。选择启用 API 和服务。搜索 Play Integrity API，然后启用它。现在，您即可将 Play Integrity API 集成到您的 SDK 中。
提高您 SDK 的每日 Play Integrity API 请求次数
若要提高每日请求次数上限，SDK 提供方应填写配额请求表单。在可用的备注部分中，请指明您要发出 SDK 请求，并在请求中包含您的 Maven 坐标 (groupId:artifactId) 或 SDK 的网址。
提高您的每日 Play Integrity API 请求次数
您的应用每天最多只能发出共 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 Plugin for Unity 1.3.0 或更高版本。如需了解相关说明，请参阅如何安装适用于 Unity 的 Google 软件包。
- 所有 2019.x、2020.x 版本和更高版本均受支持。
- 如果您使用的是 Unity 2018.x，则支持 2018.4 或更高版本。
- 不支持 Unity 2017.x 及更低版本。
原生
安装 Play Core 原生 SDK 1.13.0 或更高版本。如需了解相关说明，请参阅 Play Core 原生库的开发环境设置指南。
配置 API 响应（可选）
API 响应包含每个请求中返回的默认判定结果。如果您在 Play 管理中心内设置 Play Integrity API 集成，则可以自定义 API 响应。
默认响应
默认情况下，Play Integrity API 响应中会返回以下完整性判定结果：
| 响应字段 | 值 | 说明 |
|---|---|---|
| 设备完整性 | MEETS_DEVICE_INTEGRITY |
应用正在由 Google Play 服务提供支持的 Android 设备上运行。设备通过了系统完整性检查，并且满足 Android 兼容性要求。 |
| 空（空白值） | 应用正在存在攻击迹象（如 API 挂接）或系统被侵入迹象（如取得 root 权限后入侵）的设备上运行，或者应用未在实体设备（如未通过 Google Play 完整性检查的模拟器）上运行。 | |
| Play 账号详细信息 | LICENSED |
用户拥有应用使用权。换句话说，用户在其设备上从 Google Play 安装或更新了您的应用。 |
UNLICENSED |
用户没有应用使用权。例如，当用户旁加载了您的应用，或未从 Google Play 获取您的应用时，就会发生这种情况。 | |
UNEVALUATED |
由于未达成相关条件，系统未能评估许可详情。导致这种情况的原因可能有多种，其中包括以下原因：
|
|
| 应用完整性 | PLAY_RECOGNIZED |
应用和证书与 Google Play 分发的版本相符。 |
UNRECOGNIZED_VERSION |
证书或软件包名称与 Google Play 记录不符。 | |
UNEVALUATED |
未评估应用完整性。未达成必要条件，例如设备不够可信。 |
条件响应
如果您的应用分发到 Google Play Games 电脑版，则会自动选择在设备完整性判定结果中接收其他标签：
| 响应字段 | 标签 | 说明 |
|---|---|---|
| 设备完整性 | MEETS_VIRTUAL_INTEGRITY |
应用正在由 Google Play 服务提供支持的 Android 模拟器上运行。模拟器通过了系统完整性检查，并且满足核心 Android 兼容性要求。 |
可选的响应
如果您在 Play 管理中心或 Play SDK 管理中心内设置 Play Integrity API 集成，则可以选择在 API 响应中接收相关信息。
如需更改您的 API 响应，请访问 Play 管理中心，然后依次点击发布 > 应用完整性。在响应下方，修改并保存更改。
可选设备信息
应用和 SDK 可以选择在设备完整性判定结果中接收其他设备标签。在您选择接收其他标签后，如果满足所有标签条件，完整性响应就会包含针对同一设备的多个标签。您可以准备您的后端服务器，使其表现出不同的行为，具体取决于可能的响应范围。例如，与仅返回一个标签 (MEETS_BASIC_INTEGRITY) 的设备相比，返回三个标签（MEETS_STRONG_INTEGRITY、MEETS_DEVICE_INTEGRITY 和 MEETS_BASIC_INTEGRITY）的设备可能更可信。
您还可以选择接收近期设备活动记录。“近期设备活动记录”会返回一个级别，该级别介于 LEVEL_1（请求数量较少）和 LEVEL_4（请求数量较大）之间。例如，如果设备返回的活动水平明显高于相应应用的一般水平，就可能会尝试生成大量完整性令牌来分发到非可信设备。
| 响应字段 | 标签 | 说明 | |
|---|---|---|---|
| 设备完整性 | MEETS_BASIC_INTEGRITY |
应用正在已通过基本系统完整性检查的设备上运行。设备可能不满足 Android 兼容性要求，也可能未被批准运行 Google Play 服务。例如，设备可能正在运行无法识别的 Android 版本、可能有已解锁的引导加载程序，或者可能没有经过制造商的认证。 | |
MEETS_STRONG_INTEGRITY |
应用正在由 Google Play 服务提供支持且具有强有力的系统完整性保证（如由硬件提供支持的启动完整性保证）的 Android 设备上运行。设备通过了系统完整性检查，并且满足 Android 兼容性要求。 | ||
| 近期设备活动记录 | 过去一小时内，每款应用在此设备上发出的标准 API 完整性令牌请求次数 | 过去一小时内，每个应用在此设备上发出的传统 API 完整性令牌请求次数 | |
LEVEL_1（最低） |
10 个或 10 个以下 | 5 个或更少 | |
LEVEL_2 |
介于 11 到 25 之间 | 介于 6 到 10 之间 | |
LEVEL_3 |
介于 26 到 50 之间 | 介于 11 到 15 之间 | |
LEVEL_4 （最高） |
50 个以上 | 超过 15 个 | |
UNEVALUATED |
未评估近期设备活动记录。出现这种情况的原因可能是：
|
||
可选环境详情
应用可以选择接收关于环境的其他判定结果。利用“应用访问风险”信号，您可以了解是否有其他可能会截屏、显示叠加层或控制设备的应用正在运行。通过 Play 保护机制判定，您可以了解设备上是否启用了 Play 保护机制，以及该机制是否发现了已知恶意软件。
选择接收这些判定结果后，您的 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 安装或预加载到设备上），这些应用可能会在请求应用上显示叠加层。 | |
| EMPTY（空白值） | 如果未达成必要条件，系统将不会评估应用访问风险。在这种情况下，appAccessRiskVerdict 字段为空。导致这种情况的原因可能有多种，其中包括以下原因：
|
|
| Play 保护机制判定结果 | NO_ISSUES |
Play 保护机制处于开启状态，但在设备上未发现任何应用问题。 |
NO_DATA |
Play 保护机制处于开启状态，但尚未执行任何扫描。设备或 Play 商店应用可能在近期被重置了。 | |
POSSIBLE_RISK |
Play 保护机制处于关闭状态。 | |
MEDIUM_RISK |
Play 保护机制处于开启状态，并且在设备上发现了可能有害的已安装应用。 | |
HIGH_RISK |
Play 保护机制处于开启状态，并在设备上发现了危险的已安装应用。 | |
UNEVALUATED |
未评估 Play 保护机制判定。未达成必要条件，例如设备不够可信。 |
配置传统请求设置（可选）
如果您只计划发出标准 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 管理我的响应加密事宜（推荐）。
- 点击保存更改。