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. Una volta collegato il progetto Google Cloud che utilizzi per l'API Play Integrity in Google Play Console, diventano disponibili opzioni di configurazione aggiuntive, funzionalità di test e report.
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 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 (consigliato)
Se attivi le risposte dell'API Play Integrity in Google Play Console, avrai accesso a opzioni di configurazione aggiuntive, funzionalità di test e report 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.
Configurare 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 fornitori 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 sia 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 tue richieste all'API Play Integrity vengono conteggiate automaticamente nell'utilizzo dell'API dell'SDK e non dell'app.
Gli sviluppatori di SDK hanno due opzioni per configurare l'API Play Integrity: Google Play SDK Console o Google Cloud Console.
Utilizzare Google Play SDK Console (consigliato)
Se attivi le risposte dell'API Play Integrity in Google Play SDK Console, ottieni l'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 che vuoi 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 ad 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 il numero massimo di richieste giornaliere devono compilare
il modulo di richiesta di quota. Nella sezione dei commenti aperti, specifica che stai
inviando una richiesta di SDK e includi le coordinate Maven (groupId:artifactId
)
o un URL al tuo SDK.
Limiti di utilizzo dell'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 massimo giornaliero se la tua app deve gestire un numero maggiore di utenti seguendo le istruzioni riportate di seguito.
Azione | Quota giornaliera per app | Note |
---|---|---|
Richieste di token | 10.000 | Condiviso tra le richieste classiche e le preparazioni dei token standard |
Decrittografia dei token sui server di Google | 10.000 | Condiviso tra richieste classiche e standard |
Aumentare il numero massimo di richieste giornaliere
Per avere diritto a 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 massimo giornaliero aumentato, devi continuare a limitare le richieste classiche per utente ad azioni rare e di alto valore per preservare i dati utente e la batteria.
Per richiedere un aumento del numero massimo giornaliero di richieste:
- 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 in Google Cloud Console, dove puoi anche configurare avvisi relativi alle quote, per evitare interruzioni del servizio.
Gli aumenti della quota vengono applicati automaticamente sia alla chiamata client per generare token di integrità sia alla chiamata 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, 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.4.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 l'interfaccia a riga di comando OpenUPM, puoi installare il registro OpenUPM con il seguente comando:
openupm add com.google.play.integrity
OpenUPM
Apri le impostazioni di Package Manager selezionando l'opzione del menu Unity Modifica > Impostazioni progetto > Package Manager.
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
Apri il menu del Package Manager selezionando l'opzione di menu Unity Window > Package Manager.
Imposta il menu a discesa dell'ambito del gestore in modo da selezionare I miei registri.
Seleziona il pacchetto Plug-in Google Play Integrity per Unity dall'elenco dei pacchetti e premi Installa.
Importa da GitHub
Scarica l'ultima release 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 cartellaPlugins
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.
Riavvia il progetto di gioco e attiva una build.
Apri il file
Build.cs
del progetto e aggiungi il moduloPlayIntegrity
aPublicDependencyModuleNames
:using UnrealBuildTool; public class MyGame : ModuleRules { public MyGame(ReadOnlyTargetRules Target) : base(Target) { // ... PublicDependencyModuleNames.Add("PlayIntegrity"); // ... } }
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.
(Facoltativo) Configurare le risposte dell'API
La risposta dell'API include i verdetti 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 originale con certificazione Play Protect. 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:
|
|
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 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 in Play SDK Console, puoi attivare la ricezione di informazioni nella risposta dell'API.
Per apportare modifiche alle risposte API, visita Play Console e vai a Release > Integrità dell'app. In Risposte, modifica e salva le modifiche.
Informazioni facoltative sul dispositivo e richiamo del dispositivo
Le app e gli SDK possono attivare le etichette del dispositivo aggiuntive nel verdetto di 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 più attendibile di un dispositivo che restituisce una sola etichetta
(MEETS_BASIC_INTEGRITY
).
Puoi attivare gli attributi del dispositivo, che indicano la versione dell'SDK Android del sistema operativo Android in esecuzione sul dispositivo. In futuro, potrebbe essere esteso con altri attributi del dispositivo.
Puoi attivare l'opzione Attività recente 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). Ad esempio, un dispositivo che restituisce un livello di attività
significativamente superiore a quello tipico della tua app potrebbe tentare di
generare un numero elevato di token di integrità da distribuire a dispositivi
non attendibili.
Le app possono anche attivare il richiamo del dispositivo. Il recupero dei dati 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.
Dopo aver attivato le informazioni facoltative sul dispositivo e il ritiro del dispositivo, la risposta dell'API includerà nuovi campi e risposte relativi all'integrità del dispositivo 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 avere la certificazione Play
Protect, 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 con certificazione Play Protect
con un aggiornamento della sicurezza recente.
|
||
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ò potrebbe accadere perché:
|
||
Richieste di token di integrità 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 (minima) |
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. Questo potrebbe
accadere perché:
|
||
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 facoltativi
Le app possono attivare la ricezione di esiti aggiuntivi sull'ambiente. Rischio di accesso all'app ti consente di sapere se sono in esecuzione altre app che potrebbero acquisire la schermata, mostrare overlay o controllare il dispositivo. L'esito di Play Protect indica se Play Protect è attivato sul dispositivo e se ha rilevato malware noti.
Dopo aver attivato la ricezione di questi esiti, la risposta dell'API includerà il campo dei dettagli dell'ambiente con l'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 Google 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:
|
|
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 è 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.
Quando effettui richieste classiche, per impostazione predefinita i server di Google Play gestiscono la crittografia delle risposte utilizzata dalla tua app quando interagisce con l'API Play Integrity. Anche se 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.
Consento a Google di gestire la crittografia delle mie risposte (opzione 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 in modo autonomo
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 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.
Ricorda di non decriptare o verificare il token ricevuto dall'interno dell'app client e di non esporre mai le chiavi di decriptazione all'app client.
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 delle risposte gestite da Google a quelle autogestite e viceversa
Se al momento Google gestisce la crittografia delle risposte e vuoi passare alla gestione e al download autonomi delle 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 ad API Play Integrity, fai clic su Impostazioni.
- Nella sezione Richieste classiche della pagina, accanto a Crittografia delle risposte, fai clic su Modifica.
- Nella finestra visualizzata, fai clic su Gestisco e scarico le chiavi di crittografia delle mie risposte in modo autonomo.
- Segui le istruzioni per caricare una chiave pubblica.
- Dopo che la finestra mostra che il caricamento è andato a buon fine, fai clic su Salva e le chiavi criptate vengono scaricate automaticamente.
- Modifica la logica del server in modo da decriptare e verificare i token di integrità localmente, nel tuo ambiente server sicuro, utilizzando le chiavi di crittografia delle risposte.
- (Facoltativo) Quando gestisci autonomamente le chiavi di crittografia delle risposte, la tua app può comunque eseguire il fallback al server di Google Play per decriptare e verificare la risposta.
Se gestisci autonomamente le chiavi di crittografia delle risposte e vuoi passare alla gestione della crittografia delle risposte 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 ad API Play Integrity, fai clic su Impostazioni.
- Nella sezione Richieste classiche della pagina, accanto a Crittografia delle risposte, fai clic su Modifica.
- Nella finestra visualizzata, fai clic su Consento a Google di gestire la crittografia delle mie risposte (opzione consigliata).
- Fai clic su Salva modifiche.