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 cloud Google 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.

Attiva l'API Play Integrity

Ogni app o SDK che chiama l'API Play Integrity deve avere 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 scegline uno esistente che vuoi 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 Attiva.

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

Nota: i progetti abilitati nella console Google Cloud, ma non collegati in Play Console o Play SDK Console, non sono idonei per opzioni di configurazione aggiuntive o aumenti della quota.

Collega a Google Play (opzione consigliata)

Puoi collegare il tuo progetto cloud Google Cloud alla tua app o al tuo SDK 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 un aumento della quota API giornaliera.

1. Apri Google Play Console e seleziona la tua app.
2. Vai a Protetto con Play.
3. Accanto ad API Play Integrity, seleziona il pulsante Inizia per andare alle impostazioni dell'API Play Integrity.
4. Fai clic sul pulsante Collega progetto Cloud.
5. 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 provider 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 giornaliera dell'API. 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.

Nota: puoi collegare fino a un massimo di cinque progetti Google Cloud alla tua app o al tuo SDK. Ti consigliamo di collegare più progetti se devi supportare ambienti diversi per i test e la produzione.

Comprendi i 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 richieste classiche e preparazioni di token standard
Decrittografie dei token sui server di Google	10.000	Condiviso tra richieste classiche e standard

Aumenta il numero massimo di richieste giornaliere

L'aumento della quota è soggetto a criteri di idoneità. Gli aumenti della quota si applicano sia alle chiamate di 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 quota 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 la batteria e l'utilizzo dei dati dell'utente.

Attenzione: le variazioni di volume molto elevate devono essere implementate gradualmente. Picchi di traffico improvvisi possono causare limitazioni.

Per app e giochi su Google Play

Per avere l'idoneità 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 non collegati 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 appropriate.
3. Invia il modulo di richiesta di quota.

Per i provider di SDK su Play SDK Console

Per avere l'idoneità a un aumento della quota, il tuo SDK deve essere rivendicato su Google Play SDK Console e il tuo progetto Cloud deve essere collegato al tuo 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 per gli sviluppatori.

Nei commenti aperti, fornisci i dettagli dell'SDK, descrivi il tuo caso d'uso, il tipo di richieste API che stai effettuando (standard, classiche o entrambe), la frequenza con cui effettui le richieste e il numero massimo di richieste giornaliere che vuoi.

Integra 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'

Unità

Le sezioni seguenti descrivono come integrare e configurare l'API Google Play Integrity per i progetti Unity, illustrando 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.
• Le versioni Unity 2017.x e precedenti non sono supportate.

Configurazione dell'ambiente di sviluppo

OpenUPM-CLI

Se hai installato l'interfaccia a riga di comando OpenUPM, puoi installare il registry OpenUPM con il seguente comando:

openupm add com.google.play.integrity

OpenUPM

1. Apri le impostazioni di Gestione pacchetti selezionando l'opzione di menu di Unity Edit > Project Settings > Package Manager.

2. Aggiungi OpenUPM come registry 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 Gestione pacchetti selezionando l'opzione di menu di Unity Finestra > Gestione pacchetti.

4. Imposta il menu a discesa dell'ambito del gestore per 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 di menu di Unity Asset > Importa pacchetto > Pacchetto personalizzato e importando tutti gli elementi.

Nota: se scarichi e utilizzi i plug-in Unity di Google Play, accetti i Termini di servizio del software development kit della libreria di base Play.

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.

Configurazione dell'ambiente di sviluppo

Nota: se hai già utilizzato i plug-in per le recensioni o gli aggiornamenti dell'app in Unreal Engine, puoi andare direttamente al passaggio finale.

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 Edit → Plugins (Modifica → Plug-in).

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

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) Configura le risposte dell'API

La risposta dell'API include gli esiti 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 relativi all'integrità predefiniti

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

Campo di risposta	Valore	Descrizione
Dettagli dell'account 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.
Integrità del dispositivo	MEETS_DEVICE_INTEGRITY	L'app viene eseguita su un dispositivo Android originale e certificato. Su Android 13 e versioni successive, esiste una prova supportata dalla crittografia hardware che il bootloader del dispositivo è bloccato e che 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).

Google Play Games su PC

Se distribuisci su Google Play Games per PC, verrà attivata automaticamente la ricezione di un'etichetta aggiuntiva nell'esito di 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 relativi all'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, visita Play Console e vai a Protetto con Play. Accanto ad API Play Integrity, fai clic su Gestisci. Fai clic su Modifica risposte, apporta le modifiche e salvale.

Attenzione: le modifiche alle risposte sull'integrità vengono applicate immediatamente, anche per le app e gli SDK in produzione. Assicurati che il tuo server sia pronto ad accettare nuove risposte prima di salvare le modifiche.

Informazioni del dispositivo

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

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

L'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 token eccessivi per la distribuzione abusiva a dispositivi non attendibili.

Il richiamo del dispositivo ti consente di memorizzare 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.

Nota: il richiamo del dispositivo è disponibile in versione beta per le app ed è soggetto a modifiche. Dopo la release generale, potrebbero essere applicati prezzi per un utilizzo su larga scala. Gli SDK non possono utilizzare il richiamo del 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 è installata 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 radice di attendibilità dell'attestazione sia fornita da Google.
	MEETS_STRONG_INTEGRITY	L'app viene eseguita su un dispositivo Android originale e certificato con un aggiornamento della sicurezza recente. Su Android 13 e versioni successive, l'esito MEETS_STRONG_INTEGRITY richiede MEETS_DEVICE_INTEGRITY e aggiornamenti della sicurezza nell'ultimo anno per tutte le partizioni del dispositivo, inclusa una patch della partizione del sistema operativo Android e una patch della partizione del fornitore. Su Android 12 e versioni precedenti, l'esito MEETS_STRONG_INTEGRITY richiede solo una prova di 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, ..., 37	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ò potrebbe accadere perché: Il dispositivo non è abbastanza attendibile. Si sono verificati problemi tecnici sul dispositivo.
		Richieste di token di integrità dell'API standard su questo dispositivo nell'ultima ora per app	Richieste di token di integrità dell'API classica su questo dispositivo nell'ultima ora per app
Attività del dispositivo recente	LEVEL_1 (più basso)	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 (massimo)	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 dei bit impostati in passato per il dispositivo specifico. Sei tu a decidere il significato di ogni bit. I tre valori di bit sono false per impostazione predefinita.
	writeDates: yyyymmFirst, yyyymmSecond, yyyymmThird	Queste sono le date di scrittura del valore del bit in UTC, con precisione di anno e mese. La data di scrittura di un bit di richiamo 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 esito.

Esito di Play Protect: indica se Google Play Protect è attivo 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 sulla 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 mostrare overlay sull'app richiedente.
	UNKNOWN_INSTALLED	Sono installate altre app che non sono state installate da Google Play o precaricate sulla 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 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.
	UNKNOWN_OVERLAYS	Sono in esecuzione altre app (non installate da Play o precaricate sul dispositivo) che potrebbero mostrare 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 pieghevole. Il dispositivo non utilizza 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 dell'API Play Integrity che non supporta ancora il rischio di accesso all'app per le richieste standard.
Esito 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 è 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 di Play Protect non è stato valutato. Mancava un requisito necessario, ad esempio il dispositivo non era abbastanza attendibile.

Nota: l'esito del rischio di accesso alle app esenta automaticamente i servizi di accessibilità verificati noti a Google Play. Questi servizi non attiveranno una risposta di acquisizione, controllo o overlay, il che significa che gli strumenti di accessibilità legittimi non vengono segnalati come rischi.

(Facoltativo) Configura le impostazioni relative alle richieste classiche

Salta 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 tuo backend chiama il server di Google per decriptare gli esiti. In alternativa, puoi gestire le chiavi in autonomia per decriptare i dati localmente nel tuo ambiente server sicuro.

Consenti a Google di gestire la crittografia delle tue 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.

Gestisci le tue chiavi di crittografia

Per decriptare localmente nel tuo ambiente server sicuro, puoi scaricare le chiavi di crittografia da Play Console o Play SDK Console. Per utilizzare questa funzionalità, l'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.

Attenzione: non decriptare mai i token o esporre le chiavi all'interno della tua app client.

Suggerimento: anche se gestisci autonomamente le chiavi, la tua app può comunque utilizzare il server di Google Play per la decriptazione.

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

1. Apri Play Console e seleziona la tua app .
2. Vai a Protetto con Play.
3. Accanto ad API Play Integrity, fai clic su Gestisci.
4. In Richieste classiche, accanto a Crittografia della risposta, 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 tuo 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.

Attenzione: il passaggio alla crittografia gestita da Google invalida immediatamente le chiavi scaricate in precedenza, anche in produzione. Prima di cambiare, assicurati che il tuo server sia configurato per gestire la modifica ed evitare interruzioni.