Questa pagina è stata tradotta dall'API Cloud Translation.

Esito dell'integrità

Questa pagina descrive come interpretare e utilizzare il verdetto di integrità restituito. A prescindere dal fatto che tu effettui una richiesta API standard o classica, il verdetto di integrità viene restituito nello stesso formato con contenuti simili. Il verdetto di integrità comunica informazioni sulla validità di dispositivi, app e account. Il server della tua app può utilizzare il payload risultante in un esito decriptato e verificato per determinare come procedere al meglio con una determinata azione o richiesta nella tua app.

Formato dell'esito relativo all'integrità restituito

Il payload è in formato JSON in testo normale e contiene indicatori di integrità insieme alle informazioni fornite dallo sviluppatore.

La struttura generale del payload è la seguente:

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

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

Campo dei dettagli della richiesta

Il campo requestDetails contiene informazioni sulla richiesta, incluse le informazioni fornite dallo sviluppatore nella requestHash per le richieste standard e nel 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 prepared (computed on the server).
  timestampMillis: "1675655009345"
}

Questi valori devono corrispondere a quelli della richiesta originale. Verifica pertanto 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:

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

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. Verifica pertanto 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:

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

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. Un requisito necessario non è stato soddisfatto, ad esempio perché il dispositivo non è abbastanza affidabile.

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

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

Puoi anche controllare manualmente il nome del pacchetto e 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 l'efficacia con cui un dispositivo può applicare l'integrità dell'app. Se un dispositivo non soddisfa i criteri di nessuna 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 i seguenti elementi:

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 che presenta segnali di attacco (ad esempio 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 di 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:

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

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

Etichette condizionali dei dispositivi

Se la tua app sta per essere rilasciata su Google Play Giochi per PC, il 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 del dispositivo facoltative

Se attivi la ricezione di altre etichette nell'esito relativo all'integrità, deviceRecognitionVerdict può contenere le seguenti etichette aggiuntive:

MEETS_BASIC_INTEGRITY: L'app è in esecuzione su un dispositivo che supera i controlli di base di 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, avere un bootloader sbloccato o non essere stato certificato dal produttore.
MEETS_STRONG_INTEGRITY: L'app viene eseguita 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 di integrità del sistema e soddisfa i requisiti di compatibilità di Android.

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

Attività recente del dispositivo (beta)

Puoi anche attivare l'attività recente del dispositivo, che indica 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 inaspettati che potrebbero indicare un attacco attivo. Puoi decidere in che misura considerare attendibile ogni livello di attività recente del dispositivo in base al numero di volte in cui prevedi che l'app venga installata su un dispositivo tipico per richiedere 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 a seconda della modalità e possono avere uno dei seguenti valori:

Livello di attività recente del dispositivo	Richiesta API standard	Richiesta API classica
`LEVEL_1` (valore più basso)	L'app ha richiesto al massimo 10 token per l'integrità su questo dispositivo nell'ultima ora.	L'app ha richiesto al massimo 5 token per l'integrità su questo dispositivo nell'ultima ora.
`LEVEL_2`	L'app ha richiesto tra 11 e 25 token di integrità su questo dispositivo nell'ultima ora.	L'app ha richiesto da 6 a 15 token di integrità su questo dispositivo nell'ultima ora.
`LEVEL_3`	L'app ha richiesto tra 26 e 50 token di integrità su questo dispositivo nell'ultima ora.	L'app ha richiesto tra 16 e 30 token di integrità su questo dispositivo nell'ultima ora.
`LEVEL_4` (valore più alto)	L'app ha richiesto più di 50 token di integrità su questo dispositivo nell'ultima ora.	L'app ha richiesto più di 30 token di integrità su questo dispositivo nell'ultima ora.
`UNEVALUATED`	L'attività recente del dispositivo non è stata valutata. 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. Problemi tecnici sul dispositivo.

Campo dei dettagli dell'account

Il campo accountDetails contiene un singolo valore, appLicensingVerdict, che rappresenta lo stato di licenza dell'app.

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

appLicensingVerdict può avere uno dei seguenti valori:

LICENSED

L'utente dispone di autorizzazione per l'app. In altre parole, l'utente ha installato o acquistato la tua app su Google Play.

UNLICENSED

L'utente non dispone di diritti 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 la finestra di dialogo GET_LICENSED agli utenti.

UNEVALUATED

I dettagli relativi alle licenze 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 disponga di diritti per l'app, verifica che appLicensingVerdict sia come previsto, come mostrato nel seguente snippet di codice:

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

Campo dei dettagli dell'ambiente

Se hai attivato l'esito Play Protect in Google Play Console, la risposta dell'API includerà il campo environmentDetails. Il campo environmentDetails contiene un singolo valore, playProtectVerdict, che fornisce informazioni su Google Play Protect sul dispositivo.

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 potrebbero essere stati reimpostati 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 rilevato app pericolose installate sul dispositivo.

UNEVALUATED

L'esito Play Protect non è stato valutato.

Questo potrebbe accadere per diversi motivi, tra cui:

Il dispositivo non è abbastanza attendibile.
Solo giochi: l'account utente non è LICENSED.

Indicazioni su come usare l'esito Play Protect

Il server di backend dell'app può decidere come agire in base all'esito basato sulla tolleranza al rischio. Ecco alcuni suggerimenti e potenziali azioni dell'utente:

NO_ISSUES: Play Protect è attivo e non ha rilevato problemi, quindi non è richiesta alcuna azione da parte dell'utente.
POSSIBLE_RISK e NO_DATA: Quando ricevi questi esiti, chiedi all'utente di verificare che Play Protect sia attivo e che abbia eseguito un'analisi. NO_DATA dovrebbe apparire 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 intervenire sugli avvisi di Play Protect. Se l'utente non riesce a soddisfare questi requisiti, puoi bloccarlo dall'azione del server.

Indietro

Effettua una richiesta classica

Avanti

Gestire i codici di errore