Novità: attiva gli esiti dell'API Play Integrity più efficaci sui dispositivi con Android 13 e versioni successive. Scopri di più sulle modifiche imminenti che miglioreranno sicurezza, prestazioni e privacy.

Questa pagina è stata tradotta dall'API Cloud Translation.

Configurazione

Questa pagina spiega come configurare l'app o il gioco per utilizzare l'API Play Integrity. Devi attivare le risposte dell'API e poi integrarla nella tua app e nel server di backend dell'app. Opzioni di configurazione aggiuntive, funzionalità di test e report diventano disponibili dopo aver collegato il progetto Google Cloud che utilizzi per l'API Play Integrity in Google Play Console.

Attivare 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 al di fuori di Google Play, puoi attivare le risposte dell'API Play Integrity dalla console Google Cloud.

Configurazione in Google Play Console (opzione consigliata)

Se attivi le risposte dell'API Play Integrity in Google Play Console, potrai accedere ad altre opzioni di configurazione, funzionalità di test e report sull'API. Questa opzione è disponibile solo 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.

Configurazione nella console Google Cloud

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

Istruzioni di configurazione per i provider di SDK

I fornitori 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 lo utilizzano. 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 per l'utilizzo dell'API dell'SDK e non dell'app.

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

Utilizza Google Play SDK Console (opzione consigliata)

Se attivi le risposte dell'API Play Integrity in Google Play SDK Console, hai accesso a ulteriori opzioni di configurazione. Vai a Integrità dell'SDK e fai clic su Impostazioni. In Configurazione progetto, seleziona Collega un progetto Cloud. Scegli il progetto Cloud da collegare al tuo 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à.

Utilizzare la console Google Cloud

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 a API e servizi. Seleziona Abilita API e servizi. Cerca API Play Integrity e poi attivala. Ora puoi integrare l'API Play Integrity nel tuo SDK.

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

I fornitori di SDK che vogliono aumentare le richieste giornaliere massime devono compilare il modulo di richiesta di quota. Nella sezione dei commenti aperti, specifica che stai facendo una richiesta di SDK e includi le coordinate Maven (groupId:artifactId) o un URL del tuo SDK.

Aumentare le richieste giornaliere all'API Play Integrity

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

Aumentare il numero massimo di richieste giornaliere

Per poter aumentare il numero massimo di richieste giornaliere, la tua app deve essere disponibile su Google Play, oltre che su altri canali di distribuzione. Anche con un aumento del limite giornaliero, devi continuare a limitare le richieste classiche per utente ad azioni rare e di alto valore per preservare i dati e la batteria dell'utente.

Per richiedere un aumento del numero massimo di richieste giornaliere, svolgi i seguenti passaggi:

Collega il progetto Google Cloud che utilizzi per l'API Play Integrity in Play Console.
Assicurati di implementare correttamente la logica dell'API, inclusa la strategia di ripetizione consigliata.
Richiedi un aumento della quota utilizzando questo modulo.

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

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

Integrare l'API Play Integrity nella tua app

Per integrare l'API Play Integrity nella tua app o nel tuo SDK, svolgi una delle operazioni riportate di seguito, a seconda del tuo 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.4.0'

Unity

Le sezioni seguenti descrivono come integrare e configurare l'API Google Play Integrity per i progetti Unity, coprendo 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, è supportata la versione 2018.4 o successive.
Le versioni Unity 2017.x e precedenti non sono supportate.

Configura l'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

Apri le impostazioni del gestore dei pacchetti selezionato l'opzione di menu di Unity Modifica > Impostazioni progetto > Gestore dei pacchetti.

Aggiungi OpenUPM come registry con ambito alla finestra Gestione pacchetti:

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

Apri il menu del gestore dei pacchetti selezionando l'opzione di menu di Unity Finestra > Gestore dei pacchetti.
Imposta il menu a discesa dell'ambito dell'amministratore in modo da selezionare I miei registri.
Seleziona il pacchetto Google Play Integrity Plugin for Unity dall'elenco dei pacchetti e premi Installa.

Importa da GitHub

Scarica la release più recente di .unitypackage da GitHub.
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

Scarica il plug-in Play Unreal Engine dal repository GitHub.
Copia la cartella GooglePlay all'interno della cartella Plugins nel progetto Unreal Engine.
Apri il progetto Unreal Engine e fai clic su Modifica → Plug-in.
Cerca Google Play e seleziona la casella di controllo Attiva.
Riavviare il progetto di gioco e attivare una compilazione.

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

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

(Facoltativo) Configura le risposte dell'API

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

Risposte predefinite

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 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 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 della licenza non sono stati valutati perché non è stato soddisfatto un requisito. Ciò 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 su Google Play Giochi per PC, la funzionalità verrà attivata automaticamente per ricevere 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.

Risposte facoltative

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

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

Informazioni facoltative sul dispositivo

Le app e gli SDK possono attivare etichette aggiuntive per i dispositivi nel verdetto sull'integrità del dispositivo. Dopo aver attivato la ricezione di altre etichette, la risposta di integrità includerà più etichette per lo stesso dispositivo se tutti i criteri di etichetta sono soddisfatti. Puoi preparare il server di backend in modo che si comporti in modo diverso a seconda dell'intervallo di possibili risposte. Ad esempio, un dispositivo che restituisce tre etichette (MEETS_STRONG_INTEGRITY, MEETS_DEVICE_INTEGRITY e MEETS_BASIC_INTEGRITY) può essere considerato più attendibile di un dispositivo che restituisce una sola etichetta (MEETS_BASIC_INTEGRITY).

Puoi anche attivare l'attività del dispositivo recente. L'attività del dispositivo recente restituisce un livello compreso tra LEVEL_1 (numero ridotto di richieste) e LEVEL_4 (numero elevato di richieste). Ad esempio, un dispositivo che restituisce un livello di attività molto superiore a quello tipico della tua app potrebbe tentare di generare un numero elevato di token di integrità per la distribuzione a dispositivi non attendibili.

Puoi anche attivare gli attributi del dispositivo, che indicano la versione dell'SDK Android del sistema operativo Android in esecuzione sul dispositivo. In futuro, potrebbe essere estesa con altri attributi del dispositivo.

Campo di risposta	Etichetta	Descrizione
Integrità del dispositivo	`MEETS_BASIC_INTEGRITY`	L'app è in esecuzione su un dispositivo che supera i controlli di integrità di base del sistema e, per i dispositivi con Android 13 o versioni successive, richiede l'attestazione delle chiavi della piattaforma Android. 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, il dispositivo potrebbe eseguire una versione di Android non riconosciuta, avere un bootloader sbloccato, un avvio non verificato o non essere stato certificato dal produttore.
	`MEETS_STRONG_INTEGRITY`	L'app è in esecuzione 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 basata sull'hardware e per i dispositivi con Android 13 e versioni successive è necessario disporre di un aggiornamento della sicurezza nell'ultimo anno. Il dispositivo supera i controlli relativi all'integrità del sistema e soddisfa i requisiti di compatibilità di Android.
		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` (più alto)	Più di 50	Più di 15
	`UNEVALUATED`	L'attività recente del dispositivo 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.
Attributi del dispositivo	`sdkVersion: 19, 20, ..., 35`	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é non è stato soddisfatto 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. La versione dell'app installata sul dispositivo non è nota a Google Play. Si sono verificati problemi tecnici sul dispositivo.

Dettagli facoltativi dell'ambiente

Le app possono attivare la ricezione di ulteriori giudizi sull'ambiente. Il rischio di accesso all'app ti consente di sapere se sono in esecuzione altre app che potrebbero acquisire lo schermo, mostrare overlay o controllare il dispositivo. Il verdetto di Play Protect ti informa se Play Protect è attivo sul dispositivo e se ha rilevato malware noti.

Dopo aver attivato la ricezione di questi verdetti, la risposta dell'API includerà il campo dei dettagli dell'ambiente con il verdetto:

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 che effettua la richiesta, 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 le uscite dell'app che richiede l'accesso, ad esempio le app di controllo remoto.
	`KNOWN_OVERLAYS`	Sono in esecuzione app installate da Google Play o precaricate sul dispositivo che potrebbero mostrare 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 che richiede l'autorizzazione, 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 le uscite dell'app che effettua la richiesta, ad esempio le app di controllo remoto.
	`UNKNOWN_OVERLAYS`	Sono in esecuzione altre app (non installate da Google Play o precaricate sul dispositivo) che potrebbero mostrare overlay sull'app che richiede l'autorizzazione.
	Vuoto (valore vuoto)	Il rischio di accesso alle app non viene valutato se non è stato soddisfatto un requisito necessario. In questo caso, il campo `appAccessRiskVerdict` è vuoto. Ciò 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 Google 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.
Giudizio di Play Protect	`NO_ISSUES`	Play Protect è attivo e non sono stati rilevati 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`	Il verdetto 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

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

Quando invii richieste classiche, per impostazione predefinita i server di Google Play gestiscono la crittografia della risposta utilizzata dalla tua app quando interagisci con l'API Play Integrity. Sebbene ti consigliamo di utilizzare questa opzione predefinita, 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.

Gestisco e scarico le chiavi di crittografia delle mie risposte

Se vuoi decriptare il verdetto di integrità localmente nel 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 utilizzare Play Console e la tua app deve essere disponibile su Google Play, oltre che su altri canali di distribuzione. Segui le istruzioni riportate di seguito per passare dalle chiavi di crittografia delle risposte gestite da Google a quelle gestite autonomamente.

Ricorda di non decriptare o verificare il token ricevuto dall'app client e di non esporre mai le 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 per evitare interruzioni.

Passare dalle chiavi di crittografia delle risposte gestite da Google a quelle gestite autonomamente e viceversa

Se al momento è Google a gestire la crittografia delle risposte e vuoi passare a gestire e scaricare autonomamente le chiavi di crittografia delle risposte, segui questi passaggi:

Accedi a Play Console.
Seleziona un'app che utilizza l'API Play Integrity.
Nella sezione Release del menu a sinistra, vai a Integrità dell'app.
Accanto a API Play Integrity, fai clic su Impostazioni.
Nella sezione Richieste classiche della pagina, accanto a Crittografia della risposta, fai clic su Modifica.
Nella finestra visualizzata, fai clic su Gestisci e scarico le chiavi di crittografia delle mie risposte.
Segui le istruzioni per caricare una chiave pubblica.
Quando la finestra indica che il caricamento è andato a buon fine, fai clic su Salva e le chiavi criptate verranno scaricate automaticamente.
Modifica la logica del server in modo da decriptare e verificare i token di integrità localmente, nel tuo ambiente di server sicuro, utilizzando le chiavi di crittografia della risposta.
(Facoltativo) Quando gestisci autonomamente le chiavi di crittografia delle risposte, la tua app può comunque fare affidamento sul server di Google Play per decriptare e verificare la risposta.

Se gestisci autonomamente le chiavi di crittografia delle risposte e vuoi passare alla gestione da parte di Google, segui questi passaggi:

Modifica la logica del server in modo da decriptare e verificare solo sui server di Google.
Accedi a Play Console.
Seleziona un'app che utilizza l'API Play Integrity.
Nella sezione Release del menu a sinistra, vai a Integrità dell'app.
Accanto a API Play Integrity, fai clic su Impostazioni.
Nella sezione Richieste classiche della pagina, accanto a Crittografia della risposta, fai clic su Modifica.
Nella finestra visualizzata, fai clic su Consenti a Google di gestire la crittografia delle mie risposte (opzione consigliata).
Fai clic su Salva modifiche.

Indietro

Panoramica

Avanti

Effettua una richiesta standard