完整性判定

本页面介绍了如何解读和使用返回的完整性判定结果。无论您发出标准 API 请求还是传统 API 请求,系统都会以相同的格式返回内容相似的完整性判定结果。完整性判定用于传达与设备、应用和账号有效性相关的信息。已解密且经过验证的判定中包含所生成的载荷,应用服务器可使用此载荷来确定如何以最佳方式继续推进应用中的特定操作或请求。

返回的完整性判定结果的格式

载荷是纯文本 JSON,其中包含完整性信号以及开发者提供的信息。

常规载荷结构如下:

{
  requestDetails: { ... }
  appIntegrity: { ... }
  deviceIntegrity: { ... }
  accountDetails: { ... }
  environmentDetails: { ... }
}

您必须先检查 requestDetails 字段中的值是否与原始请求的值相符,然后再检查每个完整性判定结果。下面几部分详细介绍了各个字段。

请求详情字段

requestDetails 字段包含与请求相关的信息,其中包括 requestHash(适用于标准请求)和 nonce(适用于传统请求)中由开发者提供的信息。

对于标准 API 请求:

requestDetails: {
  // Application package name this attestation was requested for.
  // Note that this field might be spoofed in the middle of the request.
  requestPackageName: "com.package.name"
  // Request hash provided by the developer.
  requestHash: "aGVsbG8gd29scmQgdGhlcmU"
  // The timestamp in milliseconds when the integrity token
  // was prepared (computed on the server).
  timestampMillis: "1675655009345"
}

这些值应与原始请求中的值相符。因此,请验证 JSON 载荷的 requestDetails 部分,确保 requestPackageNamerequestHash 与原始请求中发送的内容相符,如以下代码段所示:

Kotlin

val requestDetails = JSONObject(payload).getJSONObject("requestDetails")
val requestPackageName = requestDetails.getString("requestPackageName")
val requestHash = requestDetails.getString("requestHash")
val timestampMillis = requestDetails.getLong("timestampMillis")
val currentTimestampMillis = ...

// Ensure the token is from your app.
if (!requestPackageName.equals(expectedPackageName)
        // Ensure the token is for this specific request
    || !requestHash.equals(expectedRequestHash)
        // Ensure the freshness of the token.
    || currentTimestampMillis - timestampMillis > ALLOWED_WINDOW_MILLIS) {
        // The token is invalid! See below for further checks.
        ...
}

Java

RequestDetails requestDetails =
    decodeIntegrityTokenResponse
    .getTokenPayloadExternal()
    .getRequestDetails();
String requestPackageName = requestDetails.getRequestPackageName();
String requestHash = requestDetails.getRequestHash();
long timestampMillis = requestDetails.getTimestampMillis();
long currentTimestampMillis = ...;

// Ensure the token is from your app.
if (!requestPackageName.equals(expectedPackageName)
        // Ensure the token is for this specific request.
    || !requestHash.equals(expectedRequestHash)
        // Ensure the freshness of the token.
    || currentTimestampMillis - timestampMillis > ALLOWED_WINDOW_MILLIS) {
        // The token is invalid! See below for further checks.
        ...
}

对于传统 API 请求:

requestDetails: {
  // Application package name this attestation was requested for.
  // Note that this field might be spoofed in the middle of the
  // request.
  requestPackageName: "com.package.name"
  // base64-encoded URL-safe no-wrap nonce provided by the developer.
  nonce: "aGVsbG8gd29scmQgdGhlcmU"
  // The timestamp in milliseconds when the request was made
  // (computed on the server).
  timestampMillis: "1617893780"
}

这些值应与原始请求中的值相符。因此,请验证 JSON 载荷的 requestDetails 部分,确保 requestPackageNamenonce 与原始请求中发送的内容相符,如以下代码段所示:

Kotlin

val requestDetails = JSONObject(payload).getJSONObject("requestDetails")
val requestPackageName = requestDetails.getString("requestPackageName")
val nonce = requestDetails.getString("nonce")
val timestampMillis = requestDetails.getLong("timestampMillis")
val currentTimestampMillis = ...

// Ensure the token is from your app.
if (!requestPackageName.equals(expectedPackageName)
        // Ensure the token is for this specific request. See 'Generate a nonce'
        // section of the doc on how to store/compute the expected nonce.
    || !nonce.equals(expectedNonce)
        // Ensure the freshness of the token.
    || currentTimestampMillis - timestampMillis > ALLOWED_WINDOW_MILLIS) {
        // The token is invalid! See below for further checks.
        ...
}

Java

JSONObject requestDetails =
    new JSONObject(payload).getJSONObject("requestDetails");
String requestPackageName = requestDetails.getString("requestPackageName");
String nonce = requestDetails.getString("nonce");
long timestampMillis = requestDetails.getLong("timestampMillis");
long currentTimestampMillis = ...;

// Ensure the token is from your app.
if (!requestPackageName.equals(expectedPackageName)
        // Ensure the token is for this specific request. See 'Generate a nonce'
        // section of the doc on how to store/compute the expected nonce.
    || !nonce.equals(expectedNonce)
        // Ensure the freshness of the token.
    || currentTimestampMillis - timestampMillis > ALLOWED_WINDOW_MILLIS) {
        // The token is invalid! See below for further checks.
        ...
}

应用完整性字段

appIntegrity 字段包含与软件包相关的信息。

appIntegrity: {
  // PLAY_RECOGNIZED, UNRECOGNIZED_VERSION, or UNEVALUATED.
  appRecognitionVerdict: "PLAY_RECOGNIZED"
  // The package name of the app.
  // This field is populated iff appRecognitionVerdict != UNEVALUATED.
  packageName: "com.package.name"
  // The sha256 digest of app certificates (base64-encoded URL-safe).
  // This field is populated iff appRecognitionVerdict != UNEVALUATED.
  certificateSha256Digest: ["6a6a1474b5cbbb2b1aa57e0bc3"]
  // The version of the app.
  // This field is populated iff appRecognitionVerdict != UNEVALUATED.
  versionCode: "42"
}

appRecognitionVerdict 的值可能如下:

PLAY_RECOGNIZED
应用和证书与 Google Play 分发的版本相符。
UNRECOGNIZED_VERSION
证书或软件包名称与 Google Play 记录不符。
UNEVALUATED
未评估应用完整性。未达成必要条件,例如设备不够可信。

如需确保令牌是由您创建的应用生成的,请验证应用完整性是否符合预期,如以下代码段所示:

Kotlin

val appIntegrity = JSONObject(payload).getJSONObject("appIntegrity")
val appRecognitionVerdict = appIntegrity.getString("appRecognitionVerdict")

if (appRecognitionVerdict == "PLAY_RECOGNIZED") {
    // Looks good!
}

Java

JSONObject appIntegrity =
    new JSONObject(payload).getJSONObject("appIntegrity");
String appRecognitionVerdict =
    appIntegrity.getString("appRecognitionVerdict");

if (appRecognitionVerdict.equals("PLAY_RECOGNIZED")) {
    // Looks good!
}

您也可以手动检查应用软件包名称、应用版本和应用证书。

设备完整性字段

deviceIntegrity 字段可以包含单个值 deviceRecognitionVerdict;该值具有一个或多个标签,用来表示设备可以在多大程度上满足执行应用完整性检查的条件。如果设备不满足任何标签的条件,deviceIntegrity 字段将为空。

deviceIntegrity: {
  // "MEETS_DEVICE_INTEGRITY" is one of several possible values.
  deviceRecognitionVerdict: ["MEETS_DEVICE_INTEGRITY"]
}

默认情况下,deviceRecognitionVerdict 可包含以下内容:

MEETS_DEVICE_INTEGRITY
应用正在已安装 Google Play 服务的 Android 设备上运行。设备通过了系统完整性检查,并且满足 Android 兼容性要求。
空(空白值)
运行应用的设备存在遭受攻击(如 API 挂接)或系统被入侵(如取得 root 权限后入侵)的迹象,或者不是实体设备(如未通过 Google Play 完整性检查的模拟器)。

为确保令牌来自可信设备,请验证 deviceRecognitionVerdict 是否符合预期,如以下代码段所示:

Kotlin

val deviceIntegrity =
    JSONObject(payload).getJSONObject("deviceIntegrity")
val deviceRecognitionVerdict =
    if (deviceIntegrity.has("deviceRecognitionVerdict")) {
        deviceIntegrity.getJSONArray("deviceRecognitionVerdict").toString()
    } else {
        ""
    }

if (deviceRecognitionVerdict.contains("MEETS_DEVICE_INTEGRITY")) {
    // Looks good!
}

Java

JSONObject deviceIntegrity =
    new JSONObject(payload).getJSONObject("deviceIntegrity");
String deviceRecognitionVerdict =
    deviceIntegrity.has("deviceRecognitionVerdict")
    ? deviceIntegrity.getJSONArray("deviceRecognitionVerdict").toString()
    : "";

if (deviceRecognitionVerdict.contains("MEETS_DEVICE_INTEGRITY")) {
    // Looks good!
}

如果您发现所用的测试设备不能满足完整性要求,请确保已安装出厂 ROM(例如,通过重置设备),并且引导加载程序处于锁定状态。您还可以在 Play 管理中心内创建 Play Integrity API 测试

条件设备标签

如果您的应用将发布到 Google Play Games 电脑版deviceRecognitionVerdict 还可包含以下标签:

MEETS_VIRTUAL_INTEGRITY
应用正在已安装 Google Play 服务的 Android 模拟器上运行。模拟器通过了系统完整性检查,并且满足核心 Android 兼容性要求。

可选设备信息

如果您选择在完整性判定结果中接收其他标签,则 deviceRecognitionVerdict 可能会包含以下额外标签:

MEETS_BASIC_INTEGRITY
应用正在已通过基本系统完整性检查的设备上运行。设备可能不满足 Android 兼容性要求,也可能未被批准运行 Google Play 服务。例如,设备运行的可能是无法识别的 Android 版本、设备的引导加载程序可能已遭解锁,或者设备可能没有经过制造商的认证。
MEETS_STRONG_INTEGRITY
应用在已安装 Google Play 服务且具有强有力的系统完整性保证(如由硬件提供支持的启动完整性保证)的 Android 设备上运行。设备通过了系统完整性检查,并且满足 Android 兼容性要求。

如果满足标签的每个条件,对于同一部设备,设备完整性判定会返回多个设备标签。

近期设备活动(Beta 版)

您还可以选择启用近期设备活动记录,了解过去一小时内您的应用在特定设备上请求完整性令牌的次数。您可以利用近期设备活动记录来保护您的应用免受意外超活跃设备的影响,意外超活跃设备可能表明存在主动攻击。您可以根据预计在典型设备上安装的应用每小时请求完整性令牌的次数,确定对每个近期设备活动记录级别的信任程度。

如果您选择接收 recentDeviceActivity,则 deviceIntegrity 字段将有两个值:

deviceIntegrity: {
  deviceRecognitionVerdict: ["MEETS_DEVICE_INTEGRITY"]
  recentDeviceActivity: {
    // "LEVEL_2" is one of several possible values.
    deviceActivityLevel: "LEVEL_2"
  }
}

deviceActivityLevel 可采用以下值之一:

LEVEL_1
最低级别:在过去一小时内,应用在此设备上请求的完整性令牌不超过 10 个。
LEVEL_2
在过去一小时内,应用在此设备上请求了 11 到 25 个完整性令牌。
LEVEL_3
在过去一小时内,应用在此设备上请求了 26 到 50 个完整性令牌。
LEVEL_4
最高级别:在过去一小时内,应用在此设备上请求了超过 50 个完整性令牌。
UNEVALUATED

未评估近期设备活动水平。导致这种情况的原因可能有多种,其中包括以下原因:

  • 设备不够可信。
  • 设备上安装的应用是 Google Play 未知的版本。
  • 设备存在技术问题。

等级定义是近似定义,可能会发生变化。

账号详情字段

accountDetails 字段包含单个值 appLicensingVerdict,用来表示应用许可状态。

accountDetails: {
  // This field can be LICENSED, UNLICENSED, or UNEVALUATED.
  appLicensingVerdict: "LICENSED"
}

appLicensingVerdict 可采用以下值之一:

LICENSED
用户拥有应用使用权。换句话说,用户从 Google Play 安装或购买了您的应用。
UNLICENSED
用户没有应用使用权。例如,如果用户旁加载了您的应用,或不是通过 Google Play 获取您的应用,就会发生这种情况。您可以向用户显示 GET_LICENSED 对话框来加以补救。
UNEVALUATED

由于未达成必要条件,系统未能评估许可详情。

导致这种情况的原因可能有多种,其中包括以下原因:

  • 设备不够可信。
  • 设备上安装的应用是 Google Play 未知的版本。
  • 用户未登录 Google Play。

如需检查用户是否拥有应用的使用权,请验证 appLicensingVerdict 是否符合预期,如以下代码段所示:

Kotlin

val accountDetails = JSONObject(payload).getJSONObject("accountDetails")
val appLicensingVerdict = accountDetails.getString("appLicensingVerdict")

if (appLicensingVerdict == "LICENSED") {
    // Looks good!
}

Java

JSONObject accountDetails =
    new JSONObject(payload).getJSONObject("accountDetails");
String appLicensingVerdict = accountDetails.getString("appLicensingVerdict");

if (appLicensingVerdict.equals("LICENSED")) {
    // Looks good!
}

环境详情字段

如果您已在 Google Play 管理中心内选择启用 Play 保护机制判定,则您的 API 响应将包含 environmentDetails 字段。environmentDetails 字段包含单个值,即 playProtectVerdict,用于提供设备上 Google Play 保护机制的相关信息。

environmentDetails: {
  playProtectVerdict: "NO_ISSUES"
}

playProtectVerdict 可采用以下值之一:

NO_ISSUES
Play 保护机制处于开启状态,但在设备上未发现任何应用问题。
NO_DATA
Play 保护机制处于开启状态,但尚未执行任何扫描。设备或 Play 商店应用可能在近期重置了。
POSSIBLE_RISK
Play 保护机制处于关闭状态。
MEDIUM_RISK
Play 保护机制处于开启状态,并且在设备上发现了可能有害的已安装应用。
HIGH_RISK
Play 保护机制处于开启状态,并在设备上发现了危险的已安装应用。
UNEVALUATED

未评估 Play 保护机制判定。

导致这种情况的原因可能有多种,其中包括以下原因:

  • 设备不够可信。
  • 仅限游戏:用户账号不是 LICENSED

Play 保护机制判定使用指南

应用的后端服务器可基于您的风险容忍度来决定如何应对。以下是一些建议和可行的用户操作:

NO_ISSUES
Play 保护机制处于开启状态,但未发现任何问题,因此用户无需执行任何操作。
POSSIBLE_RISK”和“NO_DATA
收到这些判定后,要求用户检查 Play 保护机制是否处于开启状态以及是否已执行扫描。NO_DATA 应仅在极少数情况下显示。
MEDIUM_RISK”和“HIGH_RISK
您可根据自己的风险容忍度,要求用户启动 Play 保护机制并基于 Play 保护机制警告采取相应措施。如果用户无法满足这些要求,您可以阻止他们执行服务器操作。