完整性验证

此页面介绍如何解释和处理返回的完整性验证结果。无论您发出标准 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 requested.
  timestampMillis: "1675655009345"
}

这些值应与原始请求的值匹配。因此，请通过确保 requestPackageName 和 requestHash 与原始请求中发送的内容匹配来验证 JSON 有效负载的 requestDetails 部分，如下面的代码片段所示

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"
}

这些值应与原始请求的值匹配。因此，请通过确保 requestPackageName 和 nonce 与原始请求中发送的内容匹配来验证 JSON 有效负载的 requestDetails 部分，如下面的代码片段所示

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 完整性 API 测试。

条件设备标签

如果您的应用正在发布到Google Play 游戏电脑版，则deviceRecognitionVerdict还可以包含以下标签：

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

可选设备信息

如果您在完整性验证结果中选择接收附加标签，则deviceRecognitionVerdict可以包含以下附加标签

MEETS_BASIC_INTEGRITY
应用正在通过基本系统完整性检查的设备上运行。该设备可能不符合Android兼容性要求，并且可能未获批准运行Google Play服务。例如，该设备可能运行的是无法识别的Android版本，可能已解锁引导加载程序，或者可能未经制造商认证。
MEETS_STRONG_INTEGRITY
应用正在运行在具有Google Play服务的Android设备上，并具有强大的系统完整性保证，例如基于硬件的引导完整性证明。该设备通过系统完整性检查并满足Android兼容性要求。

如果满足每个标签的条件，则单个设备将在设备完整性验证结果中返回多个设备标签。

最近的设备活动

您还可以选择加入最近的设备活动，这会告诉您您的应用在过去一小时内在特定设备上请求完整性令牌的次数。您可以使用最近的设备活动来保护您的应用免受意外的、过度活跃的设备的攻击，这可能是主动攻击的迹象。您可以根据预期安装在典型设备上的应用每小时请求完整性令牌的次数来决定信任每个最近设备活动级别的程度。

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

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

不同模式下的deviceActivityLevel定义有所不同，并且可以具有以下值之一

最近的设备活动级别 过去一小时内，此设备上每个应用的标准API完整性令牌请求数 过去一小时内，此设备上每个应用的经典API完整性令牌请求数
LEVEL_1（最低） 10个或更少 5个或更少
LEVEL_2 11到25之间 6到10之间
LEVEL_3 26到50之间 11到15之间
LEVEL_4（最高） 超过50个 超过15个
UNEVALUATED 未评估最近的设备活动。这可能是因为
  • 设备不够可靠。
  • 安装在设备上的应用版本在Google Play中未知。
  • 设备上的技术问题。

帐户详细信息字段

accountDetails字段包含单个值appLicensingVerdict，该值表示应用针对设备上登录的用户的Google Play许可状态。如果用户帐户具有该应用的Play许可证，则表示他们已从Google Play下载或购买了该应用。

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!
}

环境详细信息字段

您还可以选择加入有关环境的其他信号。应用访问风险会告诉您的应用是否存在其他正在运行的应用，这些应用可能会用于捕获屏幕、显示叠加层或控制设备。“Play 保护”验证结果会告诉您设备上是否启用了Google Play保护，以及它是否发现了已知的恶意软件。

如果您已在Google Play控制台中选择加入应用访问风险验证结果或“Play 保护”验证结果，则您的API响应将包含environmentDetails字段。environmentDetails字段可以包含两个值：appAccessRiskVerdict和playProtectVerdict。

应用访问风险验证结果（测试版）

启用后，Play 完整性API有效负载中的environmentDetails字段将包含新的应用访问风险验证结果。

{
  requestDetails: { ... }
  appIntegrity: { ... }
  deviceIntegrity: { ... }
  accountDetails: { ... }
  environmentDetails: {
      appAccessRiskVerdict: {
          // This field contains one or more responses, for example the following.
          appsDetected: ["KNOWN_INSTALLED", "UNKNOWN_INSTALLED", "UNKNOWN_CAPTURING"]
      }
 }
}

如果评估了应用访问风险，则appAccessRiskVerdict包含字段appsDetected，其中包含一个或多个响应。这些响应根据检测到的应用的安装来源分为以下两组之一

  • Play应用或系统应用：通过Google Play安装或由设备制造商预加载到设备系统分区上的应用（使用FLAG_SYSTEM标识）。此类应用的响应以KNOWN_为前缀。

  • 其他应用：并非通过Google Play安装的应用。这排除了设备制造商预加载到系统分区上的应用。此类应用的响应以UNKNOWN_为前缀。

可以返回以下响应

KNOWN_INSTALLED，UNKNOWN_INSTALLED
已安装的应用与相应的安装来源匹配。
KNOWN_CAPTURING，UNKNOWN_CAPTURING
正在运行的应用启用了可能在您的应用运行时用于查看屏幕的权限。这排除了在设备上运行的任何已验证的Google Play已知辅助功能服务。
KNOWN_CONTROLLING，UNKNOWN_CONTROLLING
正在运行的应用启用了可能用于控制设备并直接控制输入到您的应用的权限，并且可能用于捕获您的应用的输入和输出。这排除了在设备上运行的任何已验证的Google Play已知辅助功能服务。
KNOWN_OVERLAYS，UNKNOWN_OVERLAYS
正在运行的应用启用了可能用于在您的应用上显示叠加层的权限。这排除了在设备上运行的任何已验证的Google Play已知辅助功能服务。
EMPTY（空值）

如果缺少必要的条件，则不会评估应用访问风险。在这种情况下，appAccessRiskVerdict字段为空。这可能由于以下几个原因造成

  • 设备不够可靠。
  • 设备外形不是手机、平板电脑或折叠屏。
  • 设备未运行Android 6（API级别23）或更高版本。
  • 安装在设备上的应用版本在Google Play中未知。
  • 设备上的Google Play商店版本已过期。
  • 仅限游戏：用户帐户没有游戏的Play许可证。
  • 使用verdictOptOut参数使用了标准请求。
  • 使用尚未支持标准请求的应用访问风险的Play完整性API库版本使用了标准请求。

应用访问风险会自动排除已通过增强的Google Play辅助功能审核（由设备上的任何应用商店安装）的已验证辅助功能服务。“排除”表示设备上运行的已验证辅助功能服务不会在应用访问风险验证结果中返回捕获、控制或叠加层响应。要为您的辅助功能应用请求增强的Google Play辅助功能审核，请将其发布到Google Play，确保您的应用的清单中将isAccessibilityTool标志设置为true，或请求审核。

下表给出了一些验证结果示例及其含义（此表未列出所有可能的结果）

应用访问风险验证结果示例响应 解释
appsDetected
["KNOWN_INSTALLED"] 		仅安装了Google Play识别的应用或设备制造商预加载到系统分区的应用。
没有运行会产生捕获、控制或叠加层验证结果的应用。
appsDetected
["KNOWN_INSTALLED",
"UNKNOWN_INSTALLED",
"UNKNOWN_CAPTURING"] 		已安装通过Google Play安装的应用或设备制造商预加载到系统分区的应用。
其他应用正在运行，并启用了可能用于查看屏幕或捕获其他输入和输出的权限。
appsDetected
["KNOWN_INSTALLED",
"KNOWN_CAPTURING",
"UNKNOWN_INSTALLED",
"UNKNOWN_CONTROLLING"] 		正在运行的Play应用或系统应用启用了可能用于查看屏幕或捕获其他输入和输出的权限。
其他应用也正在运行，并启用了可能用于控制设备并直接控制输入到您的应用的权限。
appAccessRiskVerdict: {} 由于缺少必要的条件，因此未评估应用访问风险。例如，设备不够可靠。

根据您的风险级别，您可以决定哪些验证结果组合是可以接受的，哪些验证结果需要采取措施。以下代码片段说明了验证没有运行的应用可能捕获屏幕或控制您的应用的示例

Kotlin

val environmentDetails =
    JSONObject(payload).getJSONObject("environmentDetails")
val appAccessRiskVerdict =
    environmentDetails.getJSONObject("appAccessRiskVerdict")

if (appAccessRiskVerdict.has("appsDetected")) {
    val appsDetected = appAccessRiskVerdict.getJSONArray("appsDetected").toString()
    if (!appsDetected.contains("CAPTURING") && !appsDetected.contains("CONTROLLING")) {
        // Looks good!
    }
}

Java

JSONObject environmentDetails =
    new JSONObject(payload).getJSONObject("environmentDetails");
JSONObject appAccessRiskVerdict =
    environmentDetails.getJSONObject("appAccessRiskVerdict");

if (appAccessRiskVerdict.has("appsDetected")) {
    String appsDetected = appAccessRiskVerdict.getJSONArray("appsDetected").toString()
    if (!appsDetected.contains("CAPTURING") && !appsDetected.contains("CONTROLLING")) {
        // Looks good!
    }
}
纠正应用访问风险验证结果

根据您的风险级别，您可以决定在允许用户完成请求或操作之前要对哪些应用访问风险验证结果采取措施。在检查应用访问风险验证结果后，您可以向用户显示可选的Google Play提示。您可以显示CLOSE_UNKNOWN_ACCESS_RISK以要求用户关闭导致应用访问风险验证结果的未知应用，或者您可以显示CLOSE_ALL_ACCESS_RISK以要求用户关闭所有导致应用访问风险验证结果的应用（已知和未知）。

Play 保护验证结果

启用后，Play 完整性API有效负载中的environmentDetails字段将包含“Play 保护”验证结果

environmentDetails: {
  playProtectVerdict: "NO_ISSUES"
}

playProtectVerdict 可以具有以下值之一

NO_ISSUES
Play Protect 已开启，并且未在设备上发现任何应用问题。
NO_DATA
Play Protect 已开启，但尚未执行扫描。设备或 Play 商店应用可能最近已重置。
POSSIBLE_RISK
Play Protect 已关闭。
MEDIUM_RISK
Play Protect 已开启，并在设备上发现了可能存在危害的已安装应用。
HIGH_RISK
Play Protect 已开启，并在设备上发现了危险的已安装应用。
UNEVALUATED

未评估 Play Protect 的检测结果。

这可能由于以下几个原因造成

  • 设备不够可靠。
  • 仅限游戏：用户帐户没有游戏的Play许可证。

关于使用 Play Protect 检测结果的指南

您的应用后端服务器可以根据您的风险承受能力，根据检测结果决定如何采取行动。以下是一些建议和潜在的用户操作

NO_ISSUES
Play Protect 已开启且未发现任何问题，因此无需用户操作。
POSSIBLE_RISK 和 NO_DATA
收到这些检测结果时，请提示用户检查 Play Protect 是否已开启并已执行扫描。NO_DATA 仅应在极少数情况下出现。
MEDIUM_RISK 和 HIGH_RISK
根据您的风险承受能力，您可以提示用户启动 Play Protect 并对 Play Protect 警告采取措施。如果用户无法满足这些要求，您可以阻止他们执行服务器操作。
上一页
发出常规请求
下一页
处理错误代码