Esito dell'integrità

Questa pagina descrive come interpretare e utilizzare il giudizio di integrità restituito. Indipendentemente dal fatto che tu effettui una richiesta API standard o classica, l'esito relativo all'integrità viene restituito nello stesso formato con contenuti simili. Il verdetto sull'integrità fornisce informazioni sulla validità di dispositivi, app e account. Il server dell'app può utilizzare il payload risultante in un verdetto decriptato e verificato per determinare la migliore modalità di procedere con una determinata azione o richiesta nell'app.

Formato dell'esito relativo all'integrità restituito

Il payload è in JSON in testo normale e contiene indicatori di integrità insieme alle informazioni fornite dagli sviluppatori.

La struttura generale del payload è la seguente:

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

Prima di controllare ogni verdetto di integrità, devi verificare che i valori nel campo requestDetails corrispondano a quelli della richiesta originale. Le seguenti sezioni descrivono ciascun campo in modo più dettagliato.

Campo Dettagli della richiesta

Il campo requestDetails contiene informazioni sulla richiesta, tra cui quelle fornite dallo sviluppatore in requestHash per le richieste standard e in nonce per le richieste classiche.

Per le richieste API standard:

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

Questi valori devono corrispondere a quelli della richiesta originale. Pertanto, verifica la parte requestDetails del payload JSON assicurandoti che requestPackageName e requestHash corrispondano a quanto inviato nella richiesta originale, come mostrato nel seguente snippet di codice:

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

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

Per le richieste API classiche:

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

Questi valori devono corrispondere a quelli della richiesta originale. Pertanto, verifica la parte requestDetails del payload JSON assicurandoti che requestPackageName e nonce corrispondano a quanto inviato nella richiesta originale, come mostrato nel seguente snippet di codice:

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

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

Campo Integrità dell'applicazione

Il campo appIntegrity contiene informazioni relative al pacchetto.

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 può avere i seguenti valori:

PLAY_RECOGNIZED

L'app e il certificato corrispondono alle versioni distribuite da Google Play.

UNRECOGNIZED_VERSION

Il nome del certificato o del pacchetto non corrisponde ai record di Google Play.

UNEVALUATED

L'integrità dell'applicazione non è stata valutata. Mancava un requisito necessario, ad esempio il dispositivo non era abbastanza attendibile.

Per assicurarti che il token sia stato generato da un'app creata da te, verifica che l'integrità dell'applicazione sia come previsto, come mostrato nel seguente snippet di codice:

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

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

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

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

Puoi anche controllare manualmente il nome del pacchetto dell'app, la versione dell'app e i certificati dell'app.

Campo Integrità del dispositivo

Il campo deviceIntegrity può contenere un singolo valore, deviceRecognitionVerdict, con una o più etichette che rappresentano il grado di applicazione dell'integrità dell'app da parte di un dispositivo. Se un dispositivo non soddisfa i criteri di alcuna etichetta, il campo deviceIntegrity è vuoto.

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

Per impostazione predefinita, deviceRecognitionVerdict può contenere quanto segue:

MEETS_DEVICE_INTEGRITY

L'app viene eseguita su un dispositivo Android con Google Play Services. Il dispositivo supera i controlli relativi all'integrità del sistema e soddisfa i requisiti di compatibilità di Android.

Vuoto (valore vuoto)

L'app è in esecuzione su un dispositivo per cui sono stati rilevati segni di attacco (come l'hook delle API) o una compromissione del sistema (ad esempio il rooting) oppure l'app non è in esecuzione su un dispositivo fisico (ad esempio un emulatore che non supera i controlli relativi all'integrità di Google Play).

Per assicurarti che il token provenga da un dispositivo attendibile, verifica che deviceRecognitionVerdict sia come previsto, come mostrato nel seguente snippet di codice:

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

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

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

Se hai problemi con l'integrità del dispositivo di test, assicurati che sia installata la ROM di fabbrica (ad esempio ripristinando i dati di fabbrica del dispositivo) e che il bootloader sia bloccato. Puoi anche creare test dell'API Play Integrity in Play Console.

Etichette dei dispositivi condizionali

Se la tua app viene rilasciata su Google Play Giochi per PC, il valore deviceRecognitionVerdict può contenere anche la seguente etichetta:

MEETS_VIRTUAL_INTEGRITY

L'app è installata su un emulatore Android con Google Play Services. L'emulatore supera i controlli relativi all'integrità del sistema e soddisfa i requisiti fondamentali di compatibilità con Android.

Informazioni facoltative sul dispositivo

Se attivi la ricezione di altre etichette nel verdetto sull'integrità,deviceRecognitionVerdict può contenere le seguenti etichette aggiuntive:

MEETS_BASIC_INTEGRITY

L'app è installata su un dispositivo che supera i controlli di base relativi all'integrità del sistema. Il dispositivo potrebbe non soddisfare i requisiti di compatibilità di Android e potrebbe non essere approvato per l'esecuzione di Google Play Services. Ad esempio, sul dispositivo potrebbe essere in esecuzione una versione non riconosciuta di Android, oppure il dispositivo potrebbe includere un bootloader sbloccato o non essere stato certificato dal produttore.

MEETS_STRONG_INTEGRITY

L'app è in esecuzione su un dispositivo Android con Google Play Services e ha una solida garanzia di integrità del sistema, ad esempio una prova dell'integrità dell'avvio supportata da hardware. Il dispositivo supera i controlli relativi all'integrità del sistema e soddisfa i requisiti di compatibilità di Android.

Un singolo dispositivo restituirà più etichette nel verdetto sull'integrità del dispositivo se viene soddisfatto ognuno dei criteri dell'etichetta.

Attività del dispositivo recente

Puoi anche attivare l'attività del dispositivo recente, che ti consente di sapere quante volte la tua app ha richiesto un token di integrità su un dispositivo specifico nell'ultima ora. Puoi utilizzare l'attività recente del dispositivo per proteggere la tua app da dispositivi iperattivi e inaspettati che potrebbero indicare un attacco attivo. Puoi decidere quanto dare credito a ogni livello di attività del dispositivo recente in base al numero di volte che prevedi che la tua app installata su un dispositivo standard richieda un token di integrità ogni ora.

Se attivi la ricezione di recentDeviceActivity, il campo deviceIntegrity avrà due valori:

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

Le definizioni di deviceActivityLevel variano in base alla modalità e possono avere uno dei seguenti valori:

Attributi del dispositivo

Puoi anche attivare gli attributi del dispositivo, che indicano la versione dell'SDK Android del sistema operativo Android in esecuzione sul dispositivo. In futuro, potrebbe essere esteso con altri attributi del dispositivo.

Il valore della versione dell'SDK è il numero di versione dell'SDK Android definito in Build.VERSION_CODES. La versione dell'SDK non viene valutata se manca un requisito necessario. In questo caso, il campo sdkVersion non è impostato, pertanto il campo deviceAttributes è vuoto. Ciò può accadere perché:

• Il dispositivo non è abbastanza attendibile.
• La versione dell'app installata sul dispositivo non è nota a Google Play.
• Si sono verificati problemi tecnici sul dispositivo.

Se attivi la ricezione di deviceAttributes, il campo deviceIntegrity conterrà il seguente campo aggiuntivo:

deviceIntegrity: {
  deviceRecognitionVerdict: ["MEETS_DEVICE_INTEGRITY"]
  deviceAttributes: {
    // 33 is one possible value, which represents Android 13 (Tiramisu).
    sdkVersion: 33
  }
}

Se la versione dell'SDK non viene valutata, il campo deviceAttributes verrà impostato come segue:

deviceIntegrity: {
  deviceRecognitionVerdict: ["MEETS_DEVICE_INTEGRITY"]
  deviceAttributes: {}  // sdkVersion field is not set.
}

Campo Dettagli account

Il campo accountDetails contiene un singolo valore, appLicensingVerdict, che rappresenta lo stato della licenza Google Play dell'app per l'account utente che ha eseguito l'accesso sul dispositivo. Se l'account utente dispone della licenza Play per l'app, significa che l'ha scaricata o acquistata da Google Play.

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

appLicensingVerdict può avere uno dei seguenti valori:

LICENSED

L'utente dispone di un diritto per l'app. In altre parole, l'utente ha installato o aggiornato la tua app da Google Play sul proprio dispositivo.

UNLICENSED

L'utente non dispone di un diritto per l'app. Questo accade, ad esempio, quando l'utente installa l'app tramite sideload o non la acquisisce da Google Play. Per risolvere il problema, puoi mostrare agli utenti la finestra di dialogo GET_LICENSED.

UNEVALUATED

I dettagli relativi all'autorizzazione non sono stati valutati perché mancava un requisito necessario.

Questo potrebbe accadere per diversi motivi, tra cui:

• Il dispositivo non è abbastanza attendibile.
• La versione dell'app installata sul dispositivo non è nota a Google Play.
• L'utente non ha eseguito l'accesso a Google Play.

Per verificare che l'utente abbia un diritto per la tua app, verifica che appLicensingVerdict sia come previsto, come mostrato nel seguente snippet di codice:

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

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

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

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

Campo Dettagli ambiente

Puoi anche attivare indicatori aggiuntivi sull'ambiente. Il rischio di accesso all'app indica alla tua app se sono in esecuzione altre app che potrebbero essere utilizzate per acquisire la schermata, mostrare overlay o controllare il dispositivo. L'esito Play Protect indica se Google Play Protect è attivo sul dispositivo e se ha rilevato malware noti.

Se hai attivato il verdetto sul rischio di accesso alle app o il verdetto Play Protect in Google Play Console, la risposta dell'API includerà il campo environmentDetails. Il campo environmentDetails può contenere due valori, appAccessRiskVerdict e playProtectVerdict.

Esito del rischio di accesso all'app

Una volta attivato, il campo environmentDetails nel payload dell'API Play Integrity conterrà il nuovo esito del rischio di accesso all'app.

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

Se è stato valutato il rischio di accesso alle app, appAccessRiskVerdict contiene il campo appsDetected con una o più risposte. Queste risposte rientrano in uno dei seguenti due gruppi a seconda dell'origine di installazione delle app rilevate:

• App di Play o di sistema: app installate da Google Play o precaricate dal produttore del dispositivo nella partizione di sistema del dispositivo (identificate con FLAG_SYSTEM). Le risposte per queste app sono precedute da KNOWN_.

• Altre app: app non installate da Google Play. Sono escluse le app pre caricate nella partizione di sistema dal produttore del dispositivo. Le risposte per queste app sono precedute dal prefisso UNKNOWN_.

È possibile restituire le seguenti risposte:

KNOWN_INSTALLED, UNKNOWN_INSTALLED

Sono installate app corrispondenti all'origine di installazione corrispondente.

KNOWN_CAPTURING, UNKNOWN_CAPTURING

Sono in esecuzione app con autorizzazioni attive che potrebbero essere utilizzate per visualizzare lo schermo mentre la tua app è in esecuzione. Sono esclusi eventuali servizi di accessibilità verificati noti a Google Play in esecuzione sul dispositivo.

KNOWN_CONTROLLING, UNKNOWN_CONTROLLING

Sono in esecuzione app con autorizzazioni abilitate che potrebbero essere utilizzate per controllare il dispositivo e controllare direttamente gli input nella tua app e potrebbero essere utilizzate per acquisire input e output della tua app. Sono esclusi eventuali servizi di accessibilità verificati noti a Google Play in esecuzione sul dispositivo.

KNOWN_OVERLAYS, UNKNOWN_OVERLAYS

Sono in esecuzione app con autorizzazioni abilitate che potrebbero essere utilizzate per visualizzare overlay sulla tua app. Sono esclusi eventuali servizi di accessibilità verificati noti a Google Play in esecuzione sul dispositivo.

Vuoto (valore vuoto)

Il rischio di accesso all'app non viene valutato se non è stato soddisfatto un requisito necessario. In questo caso, il campo appAccessRiskVerdict è vuoto. Questo potrebbe accadere per diversi motivi, tra cui:

• Il dispositivo non è abbastanza attendibile.
• Il fattore di forma del dispositivo non è uno smartphone, un tablet o un dispositivo pieghevole.
• Sul dispositivo non è installato Android 6 (livello API 23) o versioni successive.
• La versione dell'app installata sul dispositivo non è nota a Google Play.
• La versione del Google Play Store sul dispositivo non è aggiornata.
• Solo giochi: l'account utente non dispone di una licenza Google Play per il gioco.
• È stata utilizzata una richiesta standard con il parametro verdictOptOut.
• È stata utilizzata una richiesta standard con una versione della libreria API Play Integrity che non supporta ancora il rischio di accesso all'app per le richieste standard.

Il rischio di accesso alle app esclude automaticamente i servizi di accessibilità verificati che hanno superato una revisione dell'accessibilità di Google Play avanzata (installati da qualsiasi store sul dispositivo). "Esclusa" indica che i servizi di accessibilità verificati in esecuzione sul dispositivo non restituiranno una risposta relativa all'acquisizione, al controllo o agli overlay nel verdetto sul rischio di accesso alle app. Per richiedere una revisione dell'accessibilità di Google Play avanzata per la tua app di accessibilità, pubblicala su Google Play assicurandoti che il flag isAccessibilityTool sia impostato su true nel file manifest della tua app oppure richiedi una revisione.

La seguente tabella fornisce alcuni esempi di giudizi e il relativo significato (questa tabella non elenca tutti i risultati possibili):

A seconda del tuo livello di rischio, puoi decidere quale combinazione di verdetti è accettabile per procedere e su quali vuoi intervenire. Il seguente snippet di codice illustra un esempio di verifica che non siano in esecuzione app che potrebbero acquisire la schermata o controllare la tua app:

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

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

Correggere i giudizi relativi al rischio di accesso all'app

A seconda del livello di rischio, puoi decidere su quali esiti del rischio di accesso all'app vuoi intervenire prima di consentire all'utente di completare una richiesta o un'azione. Esistono richieste facoltative di Google Play che puoi mostrare all'utente dopo aver controllato il verdetto sul rischio di accesso all'app. Puoi mostrare CLOSE_UNKNOWN_ACCESS_RISK per chiedere all'utente di chiudere le app sconosciute che causano il verdetto di rischio di accesso all'app oppure puoi mostrare CLOSE_ALL_ACCESS_RISK per chiedere all' utente di chiudere tutte le app (conosciute e sconosciute) che causano il verdetto di rischio di accesso all'app.

Giudizio di Play Protect

Una volta attivato, il campo environmentDetails nel payload dell'API Play Integrity conterrà il verdetto di Play Protect:

environmentDetails: {
  playProtectVerdict: "NO_ISSUES"
}

playProtectVerdict può avere uno dei seguenti valori:

NO_ISSUES

Play Protect è attivo e non ha rilevato problemi con le app sul dispositivo.

NO_DATA

Play Protect è attivo, ma non è stata ancora eseguita alcuna scansione. Il dispositivo o l'app Play Store potrebbe essere stato reimpostato di recente.

POSSIBLE_RISK

Play Protect è disattivato.

MEDIUM_RISK

Play Protect è attivo e ha rilevato app potenzialmente dannose installate sul dispositivo.

HIGH_RISK

Play Protect è attivo e ha trovato app pericolose installate sul dispositivo.

UNEVALUATED

Il verdetto di Play Protect non è stato valutato.

Questo potrebbe accadere per diversi motivi, tra cui:

• Il dispositivo non è abbastanza attendibile.
• Solo giochi: l'account utente non dispone di una licenza Google Play per il gioco.

Indicazioni per l'utilizzo del verdetto di Play Protect

Il server di backend dell'app può decidere come agire in base al verdetto in base alla tua tolleranza al rischio. Ecco alcuni suggerimenti e potenziali azioni dell'utente:

NO_ISSUES

Play Protect è attivo e non ha rilevato problemi, pertanto non è richiesta alcuna azione da parte dell'utente.

POSSIBLE_RISK e NO_DATA

Quando riceve questi giudizi, chiedi all'utente di verificare che Play Protect sia attivo e che abbia eseguito un'analisi. NO_DATA deve essere visualizzato solo in rare circostanze.

MEDIUM_RISK e HIGH_RISK

A seconda della tua tolleranza al rischio, puoi chiedere all'utente di avviare Play Protect e di intervenire in base agli avvisi di Play Protect. Se l'utente non è in grado di soddisfare questi requisiti, puoi bloccarlo dall'azione del server.