从 SafetyNet Attestation API 迁移

如果您已在使用可信服务器验证响应,那么从 SafetyNet Attestation API 迁移到 Play Integrity API 非常简单。Play Integrity API 还可用于替代通过 AIDL 直接使用 Play 商店应用执行的应用许可检查,例如由许可验证库 (LVL) 执行的检查。大多数所需的更改都将在可信服务器端进行,需要读取和分析 Play 完整性响应令牌。请注意,在迁移过程中,应用和服务器需要同时支持这两个 API,以支持尚未更新的旧客户端。

如果应用被授予了更高的 SafetyNet Attestation API 配额限制,并且有资格获得更高的 Play Integrity API 使用量,这些应用会自动置于“高”水平以满足其使用量。

如需支持 Play Integrity API,必须进行以下更改:

Android 客户端

  • 确保代码将格式正确的 Nonce 传递给 IntegrityTokenRequest 构建器:
    • String(而非字节数组)
    • 具有网址安全性
    • 编码为 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 必须以 String 形式传递给 Play Integrity API,该字符串以 Base64 编码、具有网址安全性没有换行。此格式与需要 byte[] 的 SafetyNet Attestation API 不同。

  • “具有网址安全性”是指使用 Base64 的“网址和文件名安全”变体(请参阅 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
advice Not available
error Not available 设备完整性标签列表将为空。

设备完整性判定映射

SafetyNet Attestation API Play Integrity API
ctsProfileMatch basicIntegrity evaluationType device_recognition_verdict
FALSE FALSE Empty labels
FALSE TRUE MEETS_BASIC_INTEGRITY
TRUE FALSE Empty labels
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 提供足够的时间来评估设备和应用的完整性。

可选 App Licensing API 替换

如果您使用的是 App Licensing API,可以选择进行迁移以使用 Play Integrity API,因为 Play Integrity API 令牌包含应用的许可信息。与 SafetyNet Attestation API 迁移一样,您应该预料到有许多设备会保留应用的旧版本。您的可信服务器应该能够同时处理 App Licensing API 和 Play Integrity API 响应。