设置

本页介绍了如何设置应用、游戏或 SDK 以使用 Play Integrity API。如需集成该 API，您必须拥有一个 Google Cloud 项目，这是开始发出请求的必要条件。然后，您可以在 Google Play 管理中心（针对应用）或 Google Play SDK 管理中心（针对 SDK）内关联您的 Google Cloud 项目。您必须关联项目，才能使用其他配置选项、测试功能、API 报告，以及申请提高每日请求配额。

启用 Play Integrity API

每个调用 Play Integrity API 的应用或 SDK 都必须拥有 Google Cloud 项目，才能使用该 API 并监控使用情况。这是所有集成必须执行的第一步。您可以在 Google Cloud 控制台中启用 Play Integrity API，也可以直接跳过此步骤，将云项目关联到 Google Play，系统会自动为您启用 Play Integrity API。

在 Google Cloud 控制台中，新建一个云项目，或者选择一个要与 Play Integrity API 搭配使用的现有云项目。

  1. 前往 API 和服务。
  2. 选择启用 API 和服务。
  3. 搜索 Play Integrity API。
  4. 点击启用。

现在，您即可将 Play Integrity API 集成到您的应用中。如需使用高级功能并获得配额增加，您必须继续执行关联步骤。

关联到 Google Play（推荐）

您可以按照以下说明将 Google Cloud 项目关联到应用或 SDK。

适用于 Google Play 上的应用和游戏

在 Google Play 上分发的应用应在 Google Play 管理中心内关联其 Google Cloud 项目，以启用其他功能并申请提高每日 API 配额。

  1. 打开 Google Play 管理中心，然后选择您的应用。
  2. 前往由 Google Play 提供保护。
  3. 点击 Play Integrity API 旁边的开始按钮，前往 Play Integrity API 设置。
  4. 点击关联云项目按钮。
  5. 选择您计划与 Play Integrity API 搭配使用的 Google Cloud 项目。 如果项目尚未启用 Play Integrity API，系统会在关联时自动启用该 API。

面向 Play SDK 管理中心内的 SDK 提供方

使用 Google Play SDK 管理中心的 SDK 提供方可以关联其 Google Cloud 云项目，以便将 API 使用归因于 SDK，而不是归因于使用相应 SDK 的各个应用；此外，还可以启用其他功能，并申请提高每日 API 配额。请注意，访问 Google Play SDK 管理中心需满足资格条件。

  1. 打开 Google Play SDK 管理中心，然后选择您的 SDK。
  2. 前往 SDK 完整性
  3. 在 Play Integrity API 下，点击关联云项目。
  4. 选择您计划与 Play Integrity API 搭配使用的 Google Cloud 项目；如果该项目尚未启用 Play Integrity API，则在关联后会自动启用。

了解 Play Integrity API 使用量限制

您的应用或 SDK 的默认每日总请求数上限为 10,000 次，与关联的 Cloud 项目编号相关联。如果您预计用量会增加，可以申请提高配额。

操作 每日配额 备注
令牌请求 10,000 在传统请求和标准令牌准备之间共享
在 Google 服务器上解密令牌 10,000 在传统请求和标准请求之间共享

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

配额增加须符合资格条件。配额增加同时适用于客户端令牌生成和服务器端解密调用。处理请求最多可能需要一周的时间。我们建议您在 Google Cloud 控制台中监控 Play Integrity API 的使用情况，并设置配额提醒，以免服务中断。

即使配额更高，您也应继续将传统请求限制为不频繁的高价值操作，从而节省用户电量和流量消耗。

适用于 Google Play 上的应用和游戏

若要符合提高配额的条件，您的应用除了要能通过任何其他渠道分发外，还必须在 Google Play 上架。您必须在 Play 管理中心内将 Google Cloud 项目关联到您的应用。来自未关联项目的配额请求将被拒绝。

如需申请提高限额，请执行以下操作：

  1. 在 Play 管理中心内关联相关的 Google Cloud 项目。
  2. 验证您是否已正确实现 API 逻辑（包括适当的重试策略）。
  3. 提交配额申请表单。

面向 Play SDK 管理中心内的 SDK 提供方

如需申请增加配额，您必须在 Google Play SDK 管理中心内声明您的 SDK，并且您的云项目必须与该 SDK 相关联。您必须符合资格条件，才能访问 Google Play SDK 管理中心。

如需申请提高限额，请执行以下操作：

  1. 在 Google Play SDK 管理中心内关联您的 Google Cloud 项目。
  2. 填写开发者支持表单。

在公开评论中，提供您的 SDK 详细信息，描述您的使用情形、您发出的 API 请求类型（标准、传统或两者兼有）、您发出请求的频率以及您希望获得的每日请求次数上限。

将 Play Integrity API 集成到您的应用中

如需将 Play Integrity API 集成到您的应用或 SDK 中，请根据您的开发环境执行以下其中一项操作：

Kotlin 或 Java

Google 的 Maven 制品库提供了适用于 Play Integrity API 的最新 Android 库。将以下依赖项添加到应用的 build.gradle 文件中：

implementation 'com.google.android.play:integrity:1.6.0'

Unity

以下部分介绍了如何为 Unity 项目集成和设置 Google Play Integrity API，包括支持的 Unity 版本、安装方法和环境设置。

支持的 Unity 版本

  • 所有 2019.x、2020.x 版本和更高版本均受支持。
  • 如果您使用的是 Unity 2018.x，则支持 2018.4 或更高版本。
  • 不支持 Unity 2017.x 及更低版本。

设置您的开发环境

OpenUPM-CLI

如果您已安装 OpenUPM CLI，则可以使用以下命令安装 OpenUPM 注册表：

openupm add com.google.play.integrity

OpenUPM

  1. 依次选择 Unity 菜单选项 Edit（修改）> Project Settings（项目设置）> Package Manager（资源包管理器），打开资源包管理器设置。

  2. 在资源包管理器窗口中，将 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

  3. 依次选择 Unity 菜单选项 Window（窗口）> Package Manager（资源包管理器），打开资源包管理器菜单。

  4. 在管理器范围下拉菜单中，选择 My Registries（我的注册表）。

  5. 从资源包列表中选择 Google Play Integrity plugin for Unity（适用于 Unity 的 Google Play 完整性插件）资源包，然后按 Install（安装）。

从 GitHub 导入

  1. 从 GitHub 下载最新的 .unitypackage 版本。

  2. 导入 .unitypackage 文件，方法是依次选择 Unity 菜单选项 Assets（资源）> Import package（导入资源包）> Custom Package（自定义资源包），然后导入所有项目。

Unreal Engine

以下部分介绍了如何为 Unreal Engine 项目集成和设置 Google Play Integrity API。

支持的 Unreal Engine 版本

该插件支持 Unreal Engine 5.0 及所有后续版本。

设置您的开发环境

  1. 从 GitHub 代码库下载 Play Unreal Engine 插件。

  2. 复制 Unreal Engine 项目中 Plugins 文件夹内的 GooglePlay 文件夹。

  3. 打开 Unreal Engine 项目，然后点击编辑 → 插件。

  4. 搜索 Google Play，然后选中已启用复选框。

  5. 重新启动游戏项目并触发构建。

  6. 打开项目的 Build.cs 文件，并将 PlayIntegrity 模块添加到 PublicDependencyModuleNames：

    using UnrealBuildTool;

public class MyGame : ModuleRules
{
  public MyGame(ReadOnlyTargetRules Target) : base(Target)
  {
    // ...

    PublicDependencyModuleNames.Add("PlayIntegrity");

    // ...
  }
}

原生

请按照原生设置指南操作。如需了解详情，请参阅 Play Integrity 的原生 API 参考文档。

配置 API 响应（可选）

API 响应包含每个请求中返回的默认判定结果。如果您已在 Play 管理中心或 Play SDK 管理中心内关联 Cloud 项目，则可以自定义 API 响应以包含其他信息。

默认完整性判定

默认情况下，Play Integrity API 响应中会返回以下完整性判定结果：

响应字段 值 说明
Play 账号详细信息 LICENSED 用户拥有应用使用权。换句话说，用户在其设备上从 Google Play 安装或更新了您的应用。
UNLICENSED 用户没有应用使用权。例如，当用户旁加载了您的应用，或未从 Google Play 获取您的应用时，就会发生这种情况。
UNEVALUATED 由于未达成相关条件，系统未能评估许可详情。导致这种情况的原因可能有多种，其中包括以下原因：
  • 设备不够可信。
  • 用户未登录 Google Play。
  • 设备上安装的应用是 Google Play 未知的版本。
应用完整性 PLAY_RECOGNIZED 应用和证书与 Google Play 分发的版本相符。
UNRECOGNIZED_VERSION 证书或软件包名称与 Google Play 记录不符。
UNEVALUATED 未评估应用完整性。未达成必要条件，例如设备不够可信。
设备完整性 MEETS_DEVICE_INTEGRITY 应用正在经过认证的正版 Android 设备上运行。在 Android 13 及更高版本中，有由硬件支持的证明表明设备引导加载程序已锁定，并且加载的 Android OS 是经过认证的设备制造商映像。
空（空白值） 应用正在存在攻击迹象（如 API 挂接）或系统被侵入迹象（如取得 root 权限后入侵）的设备上运行，或者应用未在实体设备（如未通过 Google Play 完整性检查的模拟器）上运行。

Google Play 游戏电脑版

如果您的应用分发到 Google Play 游戏电脑版，则会自动选择接收设备完整性判定结果中的其他标签：

响应字段 标签 说明
设备完整性 MEETS_VIRTUAL_INTEGRITY 应用正在由 Google Play 服务提供支持的 Android 模拟器上运行。模拟器通过了系统完整性检查，并且满足核心 Android 兼容性要求。

可选完整性判定

如果您已在 Play 管理中心或 Play SDK 管理中心内关联 Cloud 项目，则可以选择接收其他信息。

如需进行更改，请访问 Play 管理中心，然后前往由 Google Play 提供保护。点击 Play Integrity API 旁边的管理。点击更改响应，修改并保存更改。

设备信息

deviceIntegrity 判定结果中的其他设备标签可让您详细了解应用所运行的设备环境。 如果一部设备满足多个标签的条件，则会返回多个标签。 您可以使用这些标签来制定分级违规处置策略。例如，与仅返回一个标签 (MEETS_BASIC_INTEGRITY) 的设备相比，您可能会选择更信任返回三个标签（MEETS_STRONG_INTEGRITY、MEETS_DEVICE_INTEGRITY 和 MEETS_BASIC_INTEGRITY）的设备。

设备属性会显示设备上 Android OS 的 Android SDK 版本。未来，可能会添加其他设备属性。

近期设备活动记录会返回一个介于 LEVEL_1（请求数量较少）到 LEVEL_4（请求数量较多）之间的级别。高活动水平可能表明设备正被用于生成过多的令牌，以滥用方式分发给不可信的设备。

借助设备回想，您可以将一些自定义的每台设备数据与特定设备相关联，以便在日后于同一设备上重新安装应用时可靠地检索这些数据。

选择启用可选信息后，您的 API 响应将在判定结果中包含以下新字段和响应：

响应字段 标签 说明
设备完整性 MEETS_BASIC_INTEGRITY 应用正在已通过基本系统完整性检查的设备上运行。设备引导加载程序可以锁定或解锁，启动状态可以是已验证或未验证。设备可能未经认证，在这种情况下，Google 无法提供任何安全、隐私或应用兼容性保证。在 Android 13 及更高版本中，MEETS_BASIC_INTEGRITY 判定要求由 Google 提供证明 信任根。
MEETS_STRONG_INTEGRITY 应用正在已通过认证的正版 Android 设备上运行，且该设备已安装最新的安全更新。
  • 在 Android 13 及更高版本中，