如果您已使用受信任服务器验证响应,则从 SafetyNet Attestation API 迁移到 Play Integrity API 非常简单。Play Integrity API 也可以用作通过 AIDL 直接使用 Play 商店应用执行的 应用许可 检查的替代方案,例如由 许可证验证库 (LVL) 执行的那些检查。大多数必需的更改将在受信任服务器端进行,这些更改需要读取和分析 Play Integrity 响应令牌。请注意,在迁移期间,应用程序和服务器都需要同时支持这两个 API,以支持尚未更新的旧版客户端。
如果您的应用已为 SafetyNet Attestation API 授予增加的配额限制,则应检查为 Play Integrity API 分配的使用层级,并在必要时请求迁移到更高的层级。
以下更改对于支持 Play Integrity API 是必要的
Android 客户端
- 确保代码将正确格式化的 nonce 传递到
IntegrityTokenRequest
构建器String
(而不是字节数组)- URL 安全
- 编码为 Base64 且不换行
- 至少 16 个字符
- 最多 500 个字符
- 查看重试逻辑,并确保应用程序适当地处理错误。
- 确保发送到受信任服务器的响应数据能够区分 SafetyNet Attestation API 响应和 Play Integrity API 响应。
受信任服务器
- 查看 nonce 生成逻辑,并确保它满足 Play Integrity API 要求。
- 确保服务器代码能够区分 SafetyNet Attestation API 响应和 Play Integrity API 响应。确保代码正确解析和验证这些响应。
- 添加逻辑以 验证和解析 Play Integrity API 响应。
- 由于新的 Play Integrity API 响应提供了其他详细信息,因此可能需要增强决策逻辑和发送回客户端设备的反馈数据。有关更多信息,请参阅本主题中的 API 响应映射 部分。
Nonce 编码
必须将与完整性相关的 nonce 作为 Base64 编码、URL 安全 和 不换行 的 String
传递到 Play Integrity API。此格式不同于 SafetyNet Attestation API,后者需要 byte[]
。
- “URL 安全”表示使用 Base64 的“URL 和文件名安全”变体(请参阅 RFC 4648 第 5 节),其中使用 ‘-' 和 ‘_' 代替 ‘+' 和 ‘/’。有关 Base64 编码的更多信息,请参阅 RFC 4648。
- “不换行”表示省略所有换行符。这意味着输出是一行很长的行。
.setNonce(Base64.encodeToString(NONCE_BYTES,
Base64.URL_SAFE | Base64.NO_WRAP))
此外,请确保 nonce 生成符合 Play Integrity API 指南。
API 响应映射
下表将 SafetyNet Attestation API 字段映射到其 Play Integrity API 等效项。
SafetyNet Attestation API | Play Integrity API | 注释 | |
timestampMs |
requestDetails.timestampMillis
|
||
nonce |
requestDetails.nonce |
||
apkPackageName |
appIntegrity.packageName
|
||
apkCertificateDigestSha256
|
appIntegrity.certificateSha256Digest
|
确保 appRecognitionVerdict 设置为 PLAY_RECOGNIZED |
|
ctsProfileMatch |
合并到 deviceIntegrity.deviceRecognitionVerdict 中 |
||
basicIntegrity |
合并到 deviceIntegrity.deviceRecognitionVerdict 中 |
||
evaluationType |
合并到 deviceIntegrity.deviceRecognitionVerdict 中 |
||
建议 |
不可用 |
||
错误
|
不可用
|
设备完整性标签列表将为空。 |
设备完整性判定映射
SafetyNet Attestation API | Play Integrity API | ||
ctsProfileMatch
|
basicIntegrity
|
evaluationType
|
deviceRecognitionVerdict
|
FALSE |
FALSE |
无标签 | |
FALSE |
TRUE |
MEETS_BASIC_INTEGRITY |
|
TRUE |
FALSE |
无标签 | |
TRUE |
TRUE |
BASIC
|
MEETS_DEVICE_INTEGRITY, MEETS_BASIC_INTEGRITY
|
TRUE |
TRUE |
HARDWARE_BACKED |
MEETS_STRONG_INTEGRITY, MEETS_DEVICE_INTEGRITY, MEETS_BASIC_INTEGRITY
|
如果您的应用使用复杂的执行策略并需要所有可能的值,您可能需要 配置设备完整性响应集。
Play Integrity API 重试逻辑
对于某些错误代码,应用应重试 API 调用。请确保您已查看所有 错误代码,并在必要时使用指数退避进行应用重试。请确保最小延迟至少为 5 秒,并呈指数增长(5 秒、10 秒、20 秒、40 秒等),以便为 API 提供足够的时间来评估设备和应用完整性。
可选的应用许可 API 替换
如果您正在使用应用许可 API,则可以选择迁移到使用 Play Integrity API,因为 Play Integrity API 令牌包含应用的许可信息。与 SafetyNet Attestation API 迁移一样,您应该预计许多设备会保留旧版本的应用。您的信任服务器应该能够处理应用许可 API 和 Play Integrity API 响应。
接收响应直到完全停止
如果您尚未迁移到 Play Integrity API 或在迁移截止日期(2024 年 1 月 31 日)之前删除了 SafetyNet Attestation,您可以填写 此表单 以请求延期。如果延期获批,您的应用将继续接收来自 SafetyNet Attestation 的响应,直到完全停止截止日期(2025 年 1 月 31 日)。