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:
|
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
eNO_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
eHIGH_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.