Configurazione

Questa pagina spiega come configurare l'app, il gioco o l'SDK per utilizzare l'API Play Integrity. Per integrare l'API, devi avere un progetto Google Cloud, necessario per iniziare a effettuare richieste. Puoi quindi collegare il tuo progetto Google Cloud in Google Play Console (per le app) o in Google Play SDK Console (per gli SDK). Il collegamento del progetto è necessario per accedere a opzioni di configurazione aggiuntive, funzionalità di test, report API e per richiedere un aumento della quota di richieste giornaliere.

Abilitare l'API Play Integrity

Ogni app o SDK che chiama l'API Play Integrity deve disporre di un progetto Google Cloud per utilizzare l'API e monitorare l'utilizzo. Questo è il primo passaggio obbligatorio per tutte le integrazioni. Puoi attivare l'API Play Integrity nella console Google Cloud oppure puoi passare direttamente al collegamento del tuo progetto Cloud a Google Play e l'API Play Integrity verrà attivata automaticamente.

Nella console Google Cloud, crea un nuovo progetto Cloud o scegli un progetto Cloud esistente da utilizzare con l'API Play Integrity.

  1. Vai ad API e servizi.
  2. Seleziona Abilita API e servizi.
  3. Cerca API Play Integrity.
  4. Fai clic su Abilita.

Ora puoi integrare l'API Play Integrity nella tua app. Per accedere a funzionalità avanzate e aumenti della quota, devi procedere al passaggio di collegamento.

Link a Google Play (consigliato)

Collega la tua app o il tuo SDK a Google Play seguendo queste istruzioni.

Per app e giochi su Google Play

Le app distribuite su Google Play devono collegare il proprio progetto Google Cloud in Google Play Console per attivare funzionalità aggiuntive e richiedere una quota API giornaliera maggiore.

  1. Apri Google Play Console e seleziona la tua app.
  2. Vai a Testa e rilascia > Integrità dell'app.
  3. Nella sezione API Play Integrity, fai clic su Collega un progetto Cloud.
  4. Scegli il progetto Google Cloud che prevedi di utilizzare con l'API Play Integrity. Se l'API Play Integrity non è già abilitata per il progetto, verrà abilitata automaticamente al momento del collegamento.

Per i provider di SDK su Play SDK Console

I fornitori di SDK che utilizzano Google Play SDK Console possono collegare il proprio progetto Google Cloud per attribuire l'utilizzo dell'API all'SDK anziché alle singole app che lo utilizzano, attivare funzionalità aggiuntive e richiedere un aumento della quota API giornaliera. Tieni presente che l'accesso a Google Play SDK Console è soggetto a criteri di idoneità.

  1. Apri Google Play SDK Console e seleziona il tuo SDK.
  2. Vai a Integrità dell'SDK
  3. Nella sezione API Play Integrity, fai clic su Collega un progetto Cloud.
  4. Scegli il progetto Google Cloud che prevedi di utilizzare con l'API Play Integrity. Se l'API Play Integrity non è già abilitata per il progetto, verrà abilitata automaticamente al momento del collegamento.

Informazioni sui limiti di utilizzo dell'API Play Integrity

La tua app o il tuo SDK ha un limite giornaliero predefinito di 10.000 richieste totali, legato al numero di progetto Cloud associato. Se prevedi un volume più elevato, puoi richiedere un aumento della quota.

Azione Quota giornaliera Note
Richieste di token 10.000 Condiviso tra le richieste classiche e le preparazioni standard dei token
Decrittografia dei token sui server di Google 10.000 Condiviso tra richieste classiche e standard

Aumentare il numero massimo giornaliero di richieste

L'aumento della quota è soggetto a criteri di idoneità. Gli aumenti della quota si applicano sia alla generazione di token lato client sia alle chiamate di decriptazione lato server. L'elaborazione delle richieste può richiedere fino a una settimana. Ti consigliamo di monitorare l'utilizzo dell'API Play Integrity nella console Google Cloud e di impostare avvisi relativi alle quote per evitare interruzioni del servizio.

Anche con una quota più elevata, continua a limitare le richieste classiche ad azioni rare e di alto valore per preservare l'utilizzo di batteria e dati da parte degli utenti.

Per app e giochi su Google Play

Per essere idonea a un aumento della quota, la tua app deve essere disponibile su Google Play oltre che su eventuali altri canali di distribuzione. Devi collegare il tuo progetto Google Cloud alla tua app in Play Console. Le richieste di quota provenienti da progetti scollegati verranno rifiutate.

Per richiedere un aumento:

  1. Collega il progetto Google Cloud pertinente in Play Console.
  2. Verifica di aver implementato correttamente la logica dell'API, incluse le strategie di ripetizione corrette.
  3. Invia il modulo di richiesta di quota.

Per i provider di SDK su Play SDK Console

Per avere diritto a un aumento della quota, il tuo SDK deve essere rivendicato su Google Play SDK Console e il tuo progetto Cloud deve essere collegato all'SDK. L'accesso a Google Play SDK Console è soggetto a criteri di idoneità.

Per richiedere un aumento:

  1. Collega il tuo progetto Google Cloud in Google Play SDK Console.
  2. Compila il modulo di assistenza di Google Play SDK Console.

Nella sezione dei commenti aperti, descrivi il tuo caso d'uso, il tipo di richieste API che stai effettuando (standard o classiche o entrambe), la frequenza con cui effettui le richieste e il numero massimo di richieste giornaliere che desideri.

Integrare l'API Play Integrity nella tua app

Per integrare l'API Play Integrity nella tua app o nel tuo SDK, esegui una delle seguenti operazioni a seconda dell'ambiente di sviluppo:

Kotlin o Java

La libreria Android più recente per l'API Play Integrity è disponibile nel repository Maven di Google. Aggiungi la seguente dipendenza al file build.gradle della tua app:

implementation 'com.google.android.play:integrity:1.6.0'

Unity

Le sezioni seguenti descrivono come integrare e configurare l'API Google Play Integrity per i progetti Unity, incluse le versioni di Unity supportate, i metodi di installazione e la configurazione dell'ambiente.

Versioni di Unity supportate

  • Sono supportate tutte le versioni 2019.x, 2020.x e successive.
  • Se utilizzi Unity 2018.x, sono supportate le versioni 2018.4 o successive.
  • Unity 2017.x e versioni precedenti non sono supportate.

Configura l'ambiente di sviluppo

OpenUPM-CLI

Se hai installato OpenUPM CLI, puoi installare il registro OpenUPM con il seguente comando:

openupm add com.google.play.integrity

OpenUPM

  1. Apri le impostazioni di Package Manager selezionando l'opzione del menu Unity Modifica > Impostazioni progetto > Package Manager.

  2. Aggiungi OpenUPM come registro con ambito alla finestra Package Manager:

    Name: package.openupm.com
URL: https://package.openupm.com
Scopes: com.google.external-dependency-manager
  com.google.play.common
  com.google.play.core
  com.google.play.integrity

  3. Apri il menu del Package Manager selezionando l'opzione di menu Unity Window > Package Manager.

  4. Imposta il menu a discesa dell'ambito del gestore in modo da selezionare I miei registri.

  5. Seleziona il pacchetto Plug-in Google Play Integrity per Unity dall'elenco dei pacchetti e premi Installa.

Importa da GitHub

  1. Scarica l'ultima release di .unitypackage da GitHub.

  2. Importa il file .unitypackage selezionando l'opzione del menu Unity Asset > Importa pacchetto > Pacchetto personalizzato e importando tutti gli elementi.

Unreal Engine

Le sezioni seguenti descrivono come integrare e configurare l'API Google Play Integrity per i progetti Unreal Engine.

Versioni di Unreal Engine supportate

Il plug-in supporta Unreal Engine 5.0 e tutte le versioni successive.

Configura l'ambiente di sviluppo

  1. Scarica il plug-in Play Unreal Engine dal repository GitHub.

  2. Copia la cartella GooglePlay all'interno della cartella Plugins nel progetto Unreal Engine.

  3. Apri il progetto Unreal Engine e fai clic su Modifica → Plug-in.

  4. Cerca Google Play e seleziona la casella di controllo Attiva.

  5. Riavvia il progetto di gioco e attiva una build.

  6. Apri il file Build.cs del progetto e aggiungi il modulo PlayIntegrity a PublicDependencyModuleNames:

    using UnrealBuildTool;

public class MyGame : ModuleRules
{
  public MyGame(ReadOnlyTargetRules Target) : base(Target)
  {
    // ...

    PublicDependencyModuleNames.Add("PlayIntegrity");

    // ...
  }
}

Nativo

Segui la guida alla configurazione nativa. Per maggiori dettagli, consulta la documentazione di riferimento dell'API nativa di Play Integrity.

(Facoltativo) Configurare le risposte dell'API

La risposta dell'API include i verdetti predefiniti restituiti in ogni richiesta. Se hai collegato il tuo progetto Cloud in Play Console o Play SDK Console, puoi personalizzare la risposta dell'API in modo da includere informazioni aggiuntive.

Esiti integrità predefiniti

Per impostazione predefinita, nella risposta dell'API Play Integrity vengono restituiti i seguenti esiti relativi all'integrità:

Campo di risposta Valore Descrizione
Integrità del dispositivo MEETS_DEVICE_INTEGRITY L'app è in esecuzione su un dispositivo Android originale e certificato. Su Android 13 e versioni successive, esiste una prova supportata dall'hardware che il bootloader del dispositivo è bloccato e il sistema operativo Android caricato è un'immagine certificata del produttore del dispositivo.
Vuoto (valore vuoto) L'app è in esecuzione su un dispositivo per cui sono stati rilevati segnali 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).
Dettagli dell'account Google Play LICENSED L'utente dispone di autorizzazione 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 autorizzazione per l'app. Questo accade, ad esempio, quando l'utente installa l'app tramite sideload o non la acquisisce da Google Play.
UNEVALUATED I dettagli relativi all'autorizzazione non sono stati valutati perché mancava un requisito. Questo potrebbe accadere per diversi motivi, tra cui:
  • Il dispositivo non è abbastanza attendibile.
  • L'utente non ha eseguito l'accesso a Google Play.
  • La versione dell'app installata sul dispositivo non è nota a Google Play.
Integrità dell'applicazione 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.

Google Play Games su PC

Se distribuisci la tua app su Google Play Giochi per PC, verrà attivata automaticamente la ricezione di un'etichetta aggiuntiva nel verdetto sull'integrità del dispositivo:

Campo di risposta Etichetta Descrizione
Integrità del dispositivo 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.

Esiti integrità facoltativi

Se hai collegato il tuo progetto Cloud in Play Console o Play SDK Console, puoi attivare la ricezione di informazioni aggiuntive.

Per apportare modifiche, vai su Play Console e seleziona Test e release > Integrità dell'app. Accanto ad API Play Integrity, fai clic su Impostazioni. Fai clic su Modifica risposte, modifica e salva le modifiche.

Informazioni sul dispositivo

Le etichette del dispositivo aggiuntive nell'deviceIntegrityesito forniscono ulteriori informazioni sull'ambiente del dispositivo su cui è in esecuzione l'app. Un singolo dispositivo restituisce più etichette se soddisfa i criteri per ciascuna. Puoi utilizzare queste etichette per creare una strategia di applicazione a più livelli. Ad esempio, potresti scegliere di considerare attendibile un dispositivo che restituisce tre etichette (MEETS_STRONG_INTEGRITY, MEETS_DEVICE_INTEGRITY e MEETS_BASIC_INTEGRITY) più di un dispositivo che ne restituisce solo una (MEETS_BASIC_INTEGRITY).

Gli attributi del dispositivo indicano la versione dell'SDK Android del sistema operativo Android sul dispositivo. In futuro, potrebbe essere esteso con altri attributi del dispositivo.

Attività del dispositivo recente restituisce un livello compreso tra LEVEL_1 (numero basso di richieste) e LEVEL_4 (numero elevato di richieste). Livelli di attività elevati potrebbero indicare che un dispositivo viene utilizzato per generare un numero eccessivo di token per la distribuzione abusiva a dispositivi non attendibili.

Il richiamo del dispositivo ti consente di archiviare alcuni dati personalizzati per dispositivo con dispositivi specifici che puoi recuperare in modo affidabile quando la tua app viene installata di nuovo in un secondo momento sullo stesso dispositivo.

Dopo aver attivato le informazioni facoltative, la risposta dell'API includerà nuovi campi e risposte nell'esito:

Campo di risposta Etichetta Descrizione
Integrità del dispositivo MEETS_BASIC_INTEGRITY L'app è in esecuzione su un dispositivo che supera i controlli di base relativi all'integrità del sistema. Il bootloader del dispositivo può essere bloccato o sbloccato e lo stato di avvio può essere verificato o non verificato. Il dispositivo potrebbe non essere certificato, nel qual caso Google non può fornire alcuna garanzia di sicurezza, privacy o compatibilità delle app. Su Android 13 e versioni successive, l'esito MEETS_BASIC_INTEGRITY richiede che la root of trust dell'attestazione sia fornita da Google.
MEETS_STRONG_INTEGRITY L'app è in esecuzione su un dispositivo Android originale e certificato con un aggiornamento della sicurezza recente.
  • Su Android 13 e versioni successive, il MEETS_STRONG_INTEGRITY verdetto richiede MEETS_DEVICE_INTEGRITY e aggiornamenti della sicurezza nell'ultimo anno per tutte le partizioni del dispositivo, inclusi una patch della partizione del sistema operativo Android e una patch della partizione del fornitore.
  • Su Android 12 e versioni precedenti, il verdetto MEETS_STRONG_INTEGRITY richiede solo una prova dell'integrità dell'avvio supportata dall'hardware e non richiede che il dispositivo abbia un aggiornamento della sicurezza recente. Pertanto, quando utilizzi MEETS_STRONG_INTEGRITY, ti consigliamo di tenere conto anche della versione dell'SDK Android nel campo deviceAttributes.
Attributi del dispositivo sdkVersion: 19, 20, ..., 36 La versione dell'SDK del sistema operativo Android in esecuzione sul dispositivo. Il numero restituito corrisponde a Build.VERSION_CODES.
Vuoto (valore vuoto) La versione dell'SDK non viene valutata perché mancava 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.
  • Si sono verificati problemi tecnici sul dispositivo.
Richieste di token di integrità API standard su questo dispositivo nell'ultima ora per app Richieste di token di integrità API classici su questo dispositivo nell'ultima ora per app
Attività del dispositivo recente LEVEL_1 (minimo) 10 o meno 5 o meno
LEVEL_2 Tra 11 e 25 Tra 6 e 10
LEVEL_3 Tra 26 e 50 Tra 11 e 15
LEVEL_4 (più alto) Più di 50 Più di 15
UNEVALUATED L'attività del dispositivo recente non è stata valutata. Ciò potrebbe 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.
Richiamo del dispositivo values: bitFirst, bitSecond, bitThird Questi sono i valori di bit che hai impostato in passato per il dispositivo specifico. Sei tu a decidere il significato di ogni bit. I tre valori bit sono false per impostazione predefinita.
writeDates: yyyymmFirst, yyyymmSecond, yyyymmThird Queste sono le date di scrittura del valore bit in UTC accurate fino all'anno e al mese. La data di scrittura di un bit di ritiro viene aggiornata ogni volta che il bit viene impostato su true e viene rimossa quando il bit viene impostato su false.

Dettagli ambiente

Rischio di accesso all'app indica se sono in esecuzione altre app che potrebbero essere utilizzate per acquisire la schermata, mostrare overlay o controllare il dispositivo. I servizi di accessibilità verificati noti a Google Play vengono esclusi automaticamente da questo verdetto.

L'esito di Play Protect indica se Google Play Protect è attivato sul dispositivo e se ha rilevato malware noti.

Dopo aver attivato le informazioni facoltative, la risposta dell'API includerà nuovi campi e risposte nell'esito:

Campo di risposta Valore Descrizione
Esito del rischio di accesso all'app KNOWN_INSTALLED Le app vengono installate da Google Play o precaricate nella partizione di sistema dal produttore del dispositivo.
KNOWN_CAPTURING Sono in esecuzione app installate da Google Play o precaricate sul dispositivo che potrebbero essere utilizzate per leggere o acquisire input e output dell'app richiedente, ad esempio app di registrazione dello schermo.
KNOWN_CONTROLLING Sono in esecuzione app installate da Google Play o precaricate sul dispositivo che potrebbero essere utilizzate per controllare il dispositivo e gli input e gli output dell'app richiedente, ad esempio app di controllo remoto.
KNOWN_OVERLAYS Le app installate da Google Play o precaricate sul dispositivo sono in esecuzione e potrebbero visualizzare overlay sull'app richiedente.
UNKNOWN_INSTALLED Sono installate altre app che non sono state installate da Google Play o precaricate nella partizione di sistema dal produttore del dispositivo.
UNKNOWN_CAPTURING Sono in esecuzione altre app (non installate da Google Play o precaricate sul dispositivo) che potrebbero essere utilizzate per leggere o acquisire input e output dell'app richiedente, ad esempio app di registrazione dello schermo.
UNKNOWN_CONTROLLING Sono in esecuzione altre app (non installate da Play o precaricate sul dispositivo) che potrebbero essere utilizzate per controllare il dispositivo e gli input e output dell'app richiedente, ad esempio app di controllo remoto.
UNKNOWN_OVERLAYS Sono in esecuzione altre app (non installate da Google Play o precaricate sul dispositivo) che potrebbero visualizzare overlay sull'app richiedente.
Vuoto (valore vuoto) Il rischio di accesso all'app non viene valutato se manca 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 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.
Verdetto di Play Protect NO_ISSUES Play Protect è attivo e non ha rilevato problemi con le app sul dispositivo.
NO_DATA Play Protect è attivo, ma non è ancora stata 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 trovato app potenzialmente dannose installate sul dispositivo.
HIGH_RISK Play Protect è attivo e ha trovato app pericolose installate sul dispositivo.
UNEVALUATED L'esito di Play Protect non è stato valutato. Mancava un requisito necessario, ad esempio il dispositivo non era abbastanza attendibile.

(Facoltativo) Configurare le impostazioni relative alle richieste classiche

Ignora questa sezione se prevedi di effettuare solo richieste API standard.

Per impostazione predefinita, Google Play gestisce la crittografia delle risposte, il che significa che il backend chiama il server di Google per decriptare i risultati. In alternativa, puoi gestire le chiavi autonomamente per decriptarle localmente all'interno del tuo ambiente server sicuro.

Consenti a Google di gestire la crittografia delle risposte (opzione consigliata)

Ti consigliamo di consentire a Google di generare e gestire le chiavi per proteggere la sicurezza della tua app. Il tuo backend chiamerà il server di Google Play per decriptare e verificare le risposte.

Gestire le proprie chiavi di crittografia

Per decriptare localmente all'interno del tuo ambiente server sicuro, puoi scaricare le chiavi di crittografia da Play Console o Play SDK Console. Per utilizzare questa funzionalità, la tua app deve essere disponibile su Google Play.

Prima di modificare la strategia di gestione della crittografia delle risposte in Play Console, assicurati che il tuo server sia configurato correttamente per decriptare e verificare i token di integrità sui server di Google Play per evitare interruzioni.

Passare dalle chiavi di crittografia gestite da Google a quelle autogestite e viceversa

  1. Apri Play Console e seleziona la tua app .
  2. Vai a Testa e rilascia > Integrità dell'app.
  3. Accanto ad API Play Integrity, fai clic su Impostazioni.
  4. In Richieste classiche, accanto a Crittografia delle risposte, fai clic su Modifica.

Per passare alle chiavi autogestite:

  1. Seleziona Gestisco e scarico le chiavi di crittografia delle mie risposte in modo autonomo e carica la tua chiave pubblica.
  2. Fai clic su Salva per scaricare automaticamente le chiavi criptate.
  3. Aggiorna il server di backend sicuro per decriptare localmente utilizzando queste chiavi.

Per passare alle chiavi gestite da Google:

  1. Seleziona Consento a Google di gestire la crittografia delle mie risposte (opzione consigliata).
  2. Fai clic su Salva modifiche.
Indietro
Panoramica
Avanti
Effettua una richiesta standard