Integrity verdicts

This page describes how to interpret and work with the returned integrity verdict. Whether you make a standard or classic API request, the integrity verdict is returned in the same format with similar content. The integrity verdict communicates information about the validity of devices, apps, and accounts. Your app's server can use the resulting payload in a decrypted, verified verdict to determine how best to proceed with a particular action or request in your app.

Returned integrity verdict format

The payload is plain-text JSON and contains integrity signals alongside developer-provided information.

The general payload structure is as follows:

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

You must first check that the values in the requestDetails field match those of the original request before checking each integrity verdict. The following sections describe each field in more detail.

Request details field

The requestDetails field contains information about the request, including developer-provided information in the requestHash for standard requests and the nonce for classic requests.

For standard API requests:

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

These values should match those of the original request. Therefore, verify the requestDetails part of the JSON payload by making sure that the requestPackageName and requestHash match what was sent in the original request, as shown in the following code snippet:

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

For classic API requests:

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

These values should match those of the original request. Therefore, verify the requestDetails part of the JSON payload by making sure that the requestPackageName and nonce match what was sent in the original request, as shown in the following code snippet:

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

Application integrity field

The appIntegrity field contains package-related information.

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.
  // This field is populated iff appRecognitionVerdict != UNEVALUATED.
  certificateSha256Digest: ["6a6a1474b5cbbb2b1aa57e0bc3"]
  // The version of the app.
  // This field is populated iff appRecognitionVerdict != UNEVALUATED.
  versionCode: "42"
}

appRecognitionVerdict can have the following values:

PLAY_RECOGNIZED: The app and certificate match the versions distributed by Google Play.
UNRECOGNIZED_VERSION: The certificate or package name does not match Google Play records.
UNEVALUATED: Application integrity was not evaluated. A necessary requirement was missed, such as the device not being trustworthy enough.

To ensure that the token was generated by an app that was created by you, verify that the application integrity is as expected, as shown in the following code snippet:

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

You can also check the app package name, app version, and app certificates manually.

Device integrity field

The deviceIntegrity field can contain a single value, deviceRecognitionVerdict, that has one or more labels representing how well a device can enforce app integrity. If a device does not meet the criteria of any labels, the deviceIntegrity field is empty.

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

By default, deviceRecognitionVerdict can contain the following:

MEETS_DEVICE_INTEGRITY: The app is running on an Android-powered device with Google Play services. The device passes system integrity checks and meets Android compatibility requirements.
Empty (a blank value): The app is running on a device that has signs of attack (such as API hooking) or system compromise (such as being rooted), or the app is not running on a physical device (such as an emulator that does not pass Google Play integrity checks).

To ensure that the token came from a trustworthy device, verify the deviceRecognitionVerdict is as expected, as shown in the following code snippet:

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

If you are having problems with your testing device meeting device integrity, make sure the factory ROM is installed (for example, by resetting the device) and that the bootloader is locked. You can also create Play Integrity API tests in your Play Console.

Conditional device labels

If your app is being released to Google Play Games for PC, the deviceRecognitionVerdict can also contain the following label:

MEETS_VIRTUAL_INTEGRITY: The app is running on an Android-powered emulator with Google Play services. The emulator passes system integrity checks and meets core Android compatibility requirements.

Optional device labels

If you opt in to receive additional labels in the integrity verdict, deviceRecognitionVerdict can contain the following additional labels:

MEETS_BASIC_INTEGRITY: The app is running on a device that passes basic system integrity checks. The device may not meet Android compatibility requirements and may not be approved to run Google Play services. For example, the device may be running an unrecognized version of Android, may have an unlocked bootloader, or may not have been certified by the manufacturer.
MEETS_STRONG_INTEGRITY: The app is running on an Android-powered device with Google Play services and has a strong guarantee of system integrity such as a hardware-backed proof of boot integrity. The device passes system integrity checks and meets Android compatibility requirements.

A single device will return multiple device labels in the device integrity verdict if each of the label's criteria is met.

Recent device activity (beta)

You can also opt-in to receive recent device activity, which tells you how many times your app requested an integrity token on a specific device in the last hour. You can use recent device activity to protect your app against unexpected, hyperactive devices that could be an indication of an active attack. You can decide how much to trust each recent device activity level based on how many times you expect your app installed on a typical device to request an integrity token each hour.

If you opt-in to receive recentDeviceActivity the deviceIntegrity field will have two values:

deviceIntegrity: {
  deviceRecognitionVerdict: "MEETS_DEVICE_INTEGRITY"
  recentDeviceActivity: "LEVEL_2"
}

recentDeviceActivity can have one of the following values:

LEVEL_1

Lowest level: The app requested 10 or fewer integrity tokens on this device in the last hour.

LEVEL_2

The app requested between 11 and 25 integrity tokens on this device in the last hour.

LEVEL_3

The app requested between 26 and 50 integrity tokens on this device in the last hour.

LEVEL_4

Highest level: The app requested more than 50 integrity tokens on this device in the last hour.

UNEVALUATED

Recent device activity was not evaluated. This could happen for several reasons, including the following:

The device is not trustworthy enough.
The version of your app installed on the device is unknown to Google Play.
Technical issues on the device.

Level definitions are approximate and subject to change.

Account details field

The accountDetails field contains a single value, appLicensingVerdict, that represents app licensing status.

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

appLicensingVerdict can have the one of following values:

LICENSED

The user has an app entitlement. In other words, the user installed or bought your app on Google Play.

UNLICENSED

The user doesn't have an app entitlement. This happens when, for example, the user sideloads your app or doesn't acquire it from Google Play. You can show the GET_LICENSED dialog to users to remedy this.

UNEVALUATED

Licensing details were not evaluated because a necessary requirement was missed.

This could happen for several reasons, including the following:

The device is not trustworthy enough.
The version of your app installed on the device is unknown to Google Play.
The user is not signed in to Google Play.

To check that the user has an app entitlement for your app, verify that the appLicensingVerdict is as expected, as shown in the following code snippet:

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

Environment details field

If you have opted in to the Play Protect verdict in your Google Play Console, then your API response will include the environmentDetails field. The environmentDetails field contains a single value, playProtectVerdict, that provides information about Google Play Protect on the device.

environmentDetails: {
  playProtectVerdict: "NO_ISSUES"
}

playProtectVerdict can have one of the following values:

NO_ISSUES

Play Protect is turned on and did not find any app issues on the device.

NO_DATA

Play Protect is turned on but no scan has been performed yet. The device or the Play Store app may have been recently reset.

POSSIBLE_RISK

Play Protect is turned off.

MEDIUM_RISK

Play Protect is turned on and has found potentially harmful apps installed on the device.

HIGH_RISK

Play Protect is turned on and has found dangerous apps installed on the device.

UNEVALUATED

The Play Protect verdict was not evaluated.

This could happen for several reasons, including the following:

The device is not trustworthy enough.
Games only: The user account is not LICENSED.

Guidance on how to use the Play Protect verdict

Your app's backend server can decide how to act based on the verdict based on your risk tolerance. Here are some suggestions and potential user actions:

NO_ISSUES: Play Protect is on and hasn't found any issues so no user action is required.
POSSIBLE_RISK and NO_DATA: When receiving these verdicts, ask the user to check that Play Protect is on and has performed a scan. NO_DATA should appear only in rare circumstances.
MEDIUM_RISK and HIGH_RISK: Depending on your risk tolerance, you can ask the user to launch Play Protect and take action on the Play Protect warnings. If the user can't fufill these requirements you may block them from the server action.

Make a classic request

Error codes