Configurazione

In questa pagina viene spiegato come configurare l'app o il gioco per usare l'API Play Integrity. Devi abilitare le risposte dall'API, poi devi integrare l'API nell'app e nel server di backend dell'app. Dopo aver collegato il progetto Google Cloud che stai utilizzando per l'API Play Integrity in Google Play Console, sono disponibili opzioni di configurazione, funzionalità di test e report aggiuntivi.

Attiva le risposte dell'API Play Integrity

Ogni app o SDK che chiama l'API Play Integrity deve utilizzare un progetto Google Cloud per monitorare l'utilizzo dell'API. Le app su Google Play possono collegare un progetto Cloud in Google Play Console per attivare le risposte dell'API Play Integrity. Se vuoi creare un nuovo progetto Cloud o se la tua app viene distribuita esclusivamente all'esterno di Google Play, puoi attivare le risposte dell'API Play Integrity dalla console Google Cloud.

Configura in Google Play Console (opzione consigliata)

Se attivi le risposte dell'API Play Integrity in Google Play Console, avrai accesso a ulteriori opzioni di configurazione, funzionalità di test e report API. Questa opzione è disponibile soltanto per le app distribuite su Google Play. Vai a Release > Integrità dell'app. In API Play Integrity, seleziona Collega un progetto Cloud. Scegli il progetto Cloud che vuoi collegare alla tua app per attivare le risposte dell'API Play Integrity. Ora puoi integrare l'API Play Integrity nella tua app.

Configura nella console Google Cloud

Nella console Google Cloud, crea un nuovo progetto Cloud o scegli un progetto Cloud esistente che vuoi utilizzare con l'API Play Integrity. Vai ad API e servizi. Seleziona Abilita API e servizi. Cerca l'API Play Integrity e attivala. Ora puoi integrare l'API Play Integrity nella tua app.

Istruzioni di configurazione per i provider di SDK

I provider di SDK devono utilizzare il proprio progetto Google Cloud per chiamare l'API Play Integrity, in modo che l'utilizzo dell'API venga attribuito all'SDK e non alle singole app che utilizzano l'SDK. Ciò significa che le app che utilizzano il tuo SDK non devono configurare singolarmente l'API Play Integrity. Le richieste all'API Play Integrity vengono conteggiate automaticamente ai fini dell'utilizzo dell'API da parte dell'SDK, non dell'app.

Gli sviluppatori di SDK hanno due opzioni per configurare l'API Play Integrity: Google Play SDK Console o Google Cloud Console.

Utilizza Google Play SDK Console (consigliato)

Se attivi le risposte dell'API Play Integrity in Google Play SDK Console, puoi accedere a opzioni di configurazione aggiuntive. Vai a Integrità dell'SDK e fai clic su Impostazioni. In Configurazione progetto, seleziona Collega un progetto Cloud. Scegli il progetto Cloud che vuoi collegare all'SDK per attivare le risposte dell'API Play Integrity. Ora puoi integrare l'API Play Integrity nel tuo SDK. Tieni presente che l'accesso a Google Play SDK Console è soggetto a criteri di idoneità.

Utilizza Google Cloud Console

Puoi attivare le risposte dell'API Play Integrity dalla console Google Cloud. Nella console Google Cloud, crea un nuovo progetto Cloud o scegli un progetto Cloud esistente che vuoi utilizzare con l'API Play Integrity. Vai ad API e servizi. Seleziona Abilita API e servizi. Cerca l'API Play Integrity e attivala. Ora puoi integrare l'API Play Integrity nel tuo SDK.

Aumentare le richieste giornaliere dell'API Play Integrity del tuo SDK

I provider di SDK che vogliono aumentare il numero massimo di richieste giornaliere devono completare il modulo di richiesta di quota. Nella sezione dei commenti aperti, specifica che stai effettuando una richiesta SDK e includi le tue coordinate Maven (groupId:artifactId) o un URL al tuo SDK.

Aumentare le richieste giornaliere dell'API Play Integrity

La tua app sarà soggetta a un massimo di 10.000 richieste totali per app al giorno. Puoi richiedere di aumentare questo limite massimo giornaliero se la tua app deve gestire un aumento del numero di utenti seguendo le istruzioni riportate di seguito.

Aumenta il numero massimo giornaliero di richieste

Per poter usufruire di un aumento del numero massimo giornaliero di richieste, la tua app deve essere disponibile su Google Play, oltre che su eventuali altri canali di distribuzione. Anche con un aumento del valore massimo giornaliero, dovresti continuare a limitare le richieste classiche per utente ad azioni non frequenti e di alto valore per preservare i dati utente e la batteria.

Per richiedere un aumento del numero massimo di richieste giornaliere:

1. Collega in Play Console il progetto Google Cloud che utilizzi per l'API Play Integrity.
2. Assicurati di implementare correttamente la logica dell'API, inclusa la strategia consigliata per i nuovi tentativi.
3. Per richiedere un aumento della quota, utilizza questo modulo.

L'aumento della quota dell'API Play Integrity può richiedere fino a una settimana, perciò ti consigliamo vivamente di monitorare l'utilizzo dell'API Play Integrity in Google Play Console o in Google Cloud Console, dove puoi anche configurare avvisi di quota per evitare interruzioni del servizio.

Gli aumenti della quota delle richieste classiche verranno applicati automaticamente sia alla chiamata client per generare token di integrità sia alla chiamata al server per decriptare e verificare i token di integrità. Gli aumenti della quota di richieste standard vengono applicati alla chiamata del server per decriptare e verificare i token di integrità.

Nota: lo stesso nome di pacchetto su Google Play e su altri canali di distribuzione viene conteggiato come una singola app in termini di utilizzo dell'API. Se utilizzi un singolo ID progetto Google Cloud per più app con nomi di pacchetto diversi, verranno conteggiate come una singola app in termini di utilizzo delle API.

Integra l'API Play Integrity nella tua app

Per integrare l'API Play Integrity nella tua app o nell'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 dell'app:

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

Unity

Installa il plug-in di Google Play Integrity per Unity 1.3.0 o versioni successive. Per le istruzioni, scopri come installare i pacchetti Google per Unity.

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

Nativo

Installa l'SDK nativo della libreria di base Play 1.13.0 o versioni successive. Per istruzioni, consulta la guida alla configurazione dell'ambiente di sviluppo di Play Core Native.

Configura le risposte dell'API (facoltativo)

La risposta dell'API include esiti predefiniti restituiti in ogni richiesta. Se configuri l'integrazione dell'API Play Integrity in Play Console, puoi personalizzare la risposta API.

Risposte predefinite

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

Campo della risposta	Valore	Descrizione
Integrità del dispositivo	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 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 account	LICENSED	L'utente dispone di autorizzazione per l'app. In altre parole, l'utente ha installato o acquistato la tua app su Google Play. L'utente mantiene il diritto per l'app dopo averla disinstallata, pertanto l'account utente verrà comunque autorizzato se l'utente in seguito otterrà la stessa app in un altro modo.
	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.

Risposte condizionali

Se distribuisci la tua app su Google Play Giochi per PC, verrà attivata automaticamente la ricezione di un'etichetta aggiuntiva nell'esito relativo all'integrità del dispositivo:

Campo della risposta	Casa discografica	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.

Risposte facoltative

Se configuri l'integrazione dell'API Play Integrity in Play Console o in Play SDK Console, puoi attivare la ricezione di informazioni nella risposta dell'API.

Per apportare modifiche alle risposte dell'API, visita Play Console e vai a Release > Integrità dell'app. In Risposte, modifica e salva le modifiche.

Attenzione: le modifiche apportate alle risposte relative all'integrità del dispositivo hanno effetto immediato, anche quando la tua app è in produzione. Prima di modificare l'insieme di risposte relative all'integrità del dispositivo in Play Console, assicurati che il server sia pronto ad accettare queste risposte.

Informazioni del dispositivo facoltative

Le app e gli SDK possono attivare ulteriori etichette del dispositivo nel test relativo all'integrità del dispositivo. Dopo aver attivato la ricezione di altre etichette, la risposta relativa all'integrità includerà più etichette per lo stesso dispositivo se viene soddisfatto ognuno dei criteri relativi alle etichette. Puoi preparare il tuo server di backend affinché tenga un comportamento diverso a seconda dell'intervallo di risposte possibili. Ad esempio, un dispositivo che restituisce tre etichette (MEETS_STRONG_INTEGRITY, MEETS_DEVICE_INTEGRITY e MEETS_BASIC_INTEGRITY ) può essere considerato attendibile più di un dispositivo che restituisce una sola etichetta (MEETS_BASIC_INTEGRITY). È possibile considerare anche i livelli di attività recenti del dispositivo, con livelli che vanno da LEVEL_1 (numero ridotto di richieste) a LEVEL_4 (numero elevato di richieste). Ad esempio, un dispositivo che restituisce un livello di attività notevolmente più elevato rispetto a quello tipico della tua app potrebbe generare un numero elevato di token di integrità per la distribuzione su dispositivi non attendibili. Il livello UNEVALUATED indica potenziali problemi di sicurezza o tecnici.

Campo della risposta	Casa discografica	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 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 viene eseguita su un dispositivo Android con Google Play Services e ha una solida garanzia di integrità del sistema, ad esempio una prova di integrità dell'avvio supportata da hardware. Il dispositivo supera i controlli relativi all'integrità del sistema e soddisfa i requisiti di compatibilità di Android.
Attività recente del dispositivo (beta)		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.

Dettagli ambiente facoltativi

Le app possono attivare la ricezione di ulteriori esiti sull'ambiente. Dopo aver attivato la ricezione dell'esito Play Protect, la risposta dell'API includerà il campo dei dettagli dell'ambiente con l'esito.

Campo della risposta	Valore	Descrizione
Esito Play Protect	NO_ISSUES	Play Protect è attivo e non ha rilevato problemi con l'app sul dispositivo.
	NO_DATA	Play Protect è attivo, ma non è stata ancora eseguita alcuna analisi. 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. Mancava un requisito necessario, ad esempio il dispositivo non era abbastanza attendibile.

(Facoltativo) Configurare le impostazioni relative alle richieste classiche

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

Quando effettui richieste in modalità classica, per impostazione predefinita i server di Google Play gestiscono la crittografia delle risposte che la tua app utilizza quando interagisci con l'API Play Integrity. Ti consigliamo di utilizzare questa opzione predefinita, ma puoi anche scegliere di gestire e scaricare le chiavi di crittografia delle risposte seguendo le istruzioni riportate di seguito.

Consenti a Google di gestire la crittografia delle risposte (impostazione predefinita e consigliata)

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

Gestisci e scarica le mie chiavi di crittografia delle risposte

Se vuoi decriptare l'esito relativo all'integrità localmente all'interno del tuo ambiente server sicuro, puoi gestire e scaricare le chiavi di crittografia delle risposte. Per gestire e scaricare le chiavi di crittografia delle risposte, devi usare Play Console e l'app deve essere disponibile su Google Play oltre agli eventuali altri canali di distribuzione. Segui le istruzioni riportate di seguito per passare dalle chiavi di crittografia delle risposte gestite da Google a quelle autogestite.

Ricordati di non decriptare o verificare il token ricevuto dall'app client e non esporre mai chiavi di decrittografia all'app client.

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

Suggerimento: se gestisci e scarichi le chiavi di crittografia delle risposte, l'app può comunque ricorrere ai server di Google Play per decriptare e verificare la risposta.

Passa dalle chiavi di crittografia delle risposte gestite da Google a quelle autogestite

Se al momento Google gestisce la crittografia delle risposte e vuoi passare alla gestione e al download delle chiavi di crittografia delle risposte autonomamente, segui questi passaggi:

1. Accedi a Play Console.
2. Seleziona un'app che usa l'API Play Integrity.
3. Nella sezione Release del menu a sinistra, vai a Integrità dell'app.
4. Accanto ad API Play Integrity, fai clic su Impostazioni.
5. Nella sezione Richieste classiche della pagina, accanto a Crittografia delle risposte, fai clic su Modifica.
6. Nella finestra visualizzata, fai clic su Gestisci e scarica le mie chiavi di crittografia delle risposte.
7. Segui le istruzioni per caricare una chiave pubblica.
8. Quando la finestra mostra che il caricamento è riuscito, fai clic su Salva e le chiavi criptate verranno scaricate automaticamente.
9. Modifica la logica del server in modo da decriptare e verificare i token di integrità in locale, nel tuo ambiente server sicuro, utilizzando le chiavi di crittografia delle risposte.
10. (Facoltativo) Se gestisci autonomamente le chiavi di crittografia delle risposte, l'app può comunque ricorrere al server di Google Play per decriptare e verificare la risposta.

Se gestisci autonomamente le chiavi di crittografia delle risposte e vuoi consentire a Google di gestire la crittografia delle risposte, segui questi passaggi:

1. Modifica la logica del server in modo da eseguire solo la decriptazione e la verifica sui server di Google.
2. Accedi a Play Console.
3. Seleziona un'app che usa l'API Play Integrity.
4. Nella sezione Release del menu a sinistra, vai a Integrità dell'app.
5. Accanto ad API Play Integrity, fai clic su Impostazioni.
6. Nella sezione Richieste classiche della pagina, accanto a Crittografia delle risposte, fai clic su Modifica.
7. Nella finestra visualizzata, fai clic su Consenti a Google di gestire la crittografia delle mie risposte (opzione consigliata).
8. Fai clic su Salva modifiche.

Attenzione: dopo aver apportato la modifica in Play Console, le eventuali chiavi di crittografia delle risposte scaricate non funzioneranno più. La modifica ha effetto immediato, anche quando la tua app è in produzione.