第2章 集成前的准备工作：Google Play Console配置、创建GCP项目、启用Play Integrity API、获取服务账号密钥

2.1 本章概述

Play Integrity API 要求客户端应用的数字签名与 Google Play 中上架的签名信息一致，同时需要服务端拥有有效的 API 凭证才能完成验证。本章将引导你完成所有必须的环境初始化工作，确保后续集成时调用链路正确、权限到位。

2.2 整体工作流程

整体准备工作可归纳为四个核心环节：在 Google Play Console 中注册应用、创建关联的 GCP 项目、启用 Play Integrity API、生成并安全存储服务账号密钥。下图展示了各环节之间的依赖关系和数据流向。

2.3 Google Play Console 配置

在集成 Play Integrity API 之前，必须确保应用已在 Google Play Console 中正确创建并关联到有效的 GCP 项目。若应用尚未上架，需先创建应用并上传至少一个签署版 APK/AAB。

2.3.1 创建应用或选择已有应用

1. 打开 Google Play Console 并登录对应开发者账号。
2. 点击 创建应用 或从已有应用列表中选择目标应用。
3. 填写应用名称、默认语言、应用或游戏类别，并同意开发者条款。
4. 在 应用签名 页面记录下 SHA-1 和 SHA-256 指纹，后续步骤需要用到。

2.3.2 关联 Google Cloud 项目

每个 Play Console 中的应用必须关联一个 GCP 项目才能使用 Play Integrity API。关联操作可在 Play Console 的“API 访问”页面完成。

2.4 创建 GCP 项目

如果你在 Play Console 中直接创建了项目，GCP 项目会自动生成。但有时需要独立管理 和权限，建议手动进入 GCP 控制台确认项目状态。

2.4.1 通过 GCP 控制台创建项目

1. 访问 Google Cloud Console 并登录。建议使用与 Play Console 相同的 Google 账号。
2. 点击顶部导航栏的“选择项目” → “新建项目”。
3. 填写项目名称（建议与 Play Console 应用名对应），系统自动生成唯一项目 ID。
4. 点击“创建”。创建完成后回到 Play Console 的“API 访问”页面，选择刚创建的项目进行关联。

2.4.2 确认项目与 Play Console 的关联

关联成功后，在 Play Console → 设置 → API 访问 页面应看到类似以下信息：

Google Cloud 项目: my-app-2025 (项目编号: 123456789012)
链接状态: 已链接
Play Integrity API 状态: 未启用（需要手动开启）

2.5 启用 Play Integrity API

无论通过 Play Console 还是 GCP Console，都必须显式启用 Play Integrity API。推荐在 GCP Console 中操作，权限更清晰。

2.5.1 在 GCP Console 中启用

1. 登录 GCP Console，确保当前处于关联的项目下。
2. 在左侧菜单选择 “API 和服务” → “库”。
3. 搜索 “Play Integrity API”，点击结果进入详情页。
4. 点击 “启用” 按钮。等待几秒，状态变为 “已启用”。

2.5.2 通过 gcloud 命令行启用

如果你安装了 Google Cloud SDK，可用以下命令启用（适用于自动化脚本）：

gcloud services enable playintegrity.googleapis.com \
  --project=YOUR_PROJECT_ID

2.6 获取服务账号密钥

Play Integrity API 的服务端验证需要使用 服务账号（Service Account）进行认证。需下载 JSON 格式的私钥，并妥善保管。

2.6.1 创建服务账号

1. 在 GCP Console 中，进入 “IAM 与管理” → “服务账号”。
2. 点击 “创建服务账号”，填写名称（如 “play-integrity-server”），点击 “创建并继续”。
3. 为服务账号授予以下角色之一（任选）：
   Play Integrity API 用户 (roles/playintegrity.user) 或 项目 > 查看者 (roles/viewer)。
   建议使用最小权限原则，仅授予 Play Integrity API 用户 角色。
4. 点击 “完成”。

2.6.2 生成并下载密钥

1. 在服务账号列表中，点击刚创建的账号右侧操作菜单 → “管理密钥”。
2. 点击 “添加密钥” → “新建密钥”。
3. 密钥类型选择 JSON，点击 “创建”。浏览器会自动下载一个 .json 文件。
4. 该文件包含 private_key、client_email 等字段。请将文件保存在安全的服务器目录中，切勿提交到公开仓库。

2.6.3 验证密钥有效性（可选）

可用以下命令行快速验证 JWT 生成的正确性：

# 使用 google-auth 库验证
pip install google-auth
python3 -c "
from google.oauth2 import service_account
import json

with open('service-account.json') as f:
    info = json.load(f)

credentials = service_account.Credentials.from_service_account_info(info)
print('服务账号邮箱:', credentials.service_account_email)
print('密钥有效期限:', credentials.expiry)
"

2.7 常见错误与排查

2.8 后续步骤

完成上述配置后，你已获得：

• GCP 项目 ID
• Play Integrity API 已启用
• 服务账号 JSON 密钥（包含 client_email 和 private_key）
• Play Console 应用签名指纹