Integrare Play Integrity per PC nella tua app

Play Integrity per PC ti aiuta a verificare che gli eventi di gioco e le richieste del server provengano da un'istanza originale di Google Play Giochi per PC su un dispositivo PC originale. Rilevando dispositivi potenzialmente rischiosi ed emulatori sconosciuti, il server di backend del tuo gioco può rispondere con azioni appropriate per prevenire imbrogli, accessi non autorizzati, traffico fraudolento e abusi.

Prerequisiti

• Completa la configurazione dell'SDK.
• Esamina le considerazioni sulla sicurezza dell'API Integrity.
• Leggi e comprendi i Termini di servizio dell'API Integrity e le informazioni sulla gestione dei dati.
• Nella console Google Cloud, crea un progetto Cloud o scegli un progetto Cloud esistente che vuoi utilizzare con Play Integrity per PC. Vai ad API e servizi e abilita l'API Google Play Integrity.
• Se prevedi di effettuare più di 10.000 richieste di Play Integrity per PC al giorno, devi richiedere un aumento del limite massimo giornaliero.

Passaggio 1: decidi come utilizzerai Play Integrity per PC nel tuo gioco

Decidi quando chiamare Play Integrity per PC per ottenere un esito relativo all'integrità dell'ambiente. Ad esempio, potresti richiedere un esito quando il gioco viene aperto, quando un giocatore esegue l'accesso o quando un giocatore partecipa a un gioco multigiocatore. Poi, decidi come gestire le diverse risposte relative all'integrità. Ad esempio, potresti:

• Raccogliere la risposta senza intraprendere azioni di applicazione e analizzare i dati internamente per capire se si tratta di un segnale utile di abuso.
• Raccogliere la risposta e implementare la logica sul server di backend per consentire ai dispositivi che superano gli esiti relativi all'integrità di riprodurre il gioco normalmente, sfidando o negando l'accesso al traffico proveniente da ambienti sospetti.
• Raccogliere la risposta e implementare la logica sul backend per abbinare i giocatori sui dispositivi che superano i controlli di integrità, abbinando al contempo il traffico proveniente da ambienti sospetti.

Passaggio 2: richiedi token di integrità nel tuo gioco

Prepara Play Integrity per PC

Prepara (o "riscalda") Play Integrity per PC, che consente a Google Play di memorizzare nella cache in modo intelligente le informazioni di attestazione parziale sul dispositivo per ridurre la latenza sul percorso critico quando effettui una richiesta di esito relativo all'integrità. Puoi farlo in modo asincrono non appena il gioco si apre, in modo da poter effettuare richieste di integrità on demand quando ne hai bisogno.

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

Se l'operazione va a buon fine, la continuazione verrà chiamata con un PrepareIntegrityTokenResultValue contenente un RequestTokenData che deve essere utilizzato per richiedere un token di integrità. Questi dati devono essere memorizzati nella cache in memoria e riutilizzati per la durata della sessione dell'applicazione per le chiamate a RequestIntegrityToken.

Una chiamata a PrepareIntegrityToken deve essere effettuata solo se l'applicazione determina che è necessario rivalutare completamente l'esito relativo all'integrità.

Di seguito è riportato uno snippet di codice che mostra come chiamare l'azione PrepareIntegrityToken:

google::play::integrity::IntegrityClient client_;

google::play::integrity::PrepareIntegrityTokenResult
IntegrityInterface::PrepareIntegrityToken(int64_t cloud_project_number) {
  google::play::integrity::PrepareIntegrityTokenParams params;
  params.cloud_project_number = cloud_project_number;

  auto promise = std::make_shared<
      std::promise<google::play::integrity::PrepareIntegrityTokenResult>>();
  client_.PrepareIntegrityToken(
      params,
      [promise](
          google::play::integrity::PrepareIntegrityTokenResult result) {
        promise->set_value(std::move(result));
      });

  return promise->get_future().get();
}

Richiedi un token di integrità

I token di integrità sono un meccanismo che consente al tuo gioco di verificare che il dispositivo non sia stato manomesso. Ogni volta che il gioco effettua una richiesta del server di cui vuoi verificare l'autenticità, puoi richiedere un token di integrità e inviarlo al server di backend del gioco per la decrittografia e la verifica.

Quando controlli un'azione dell'utente nella tua app con l'API Play Integrity per PC, puoi utilizzare il campo RequestIntegrityTokenParams::request_hash per mitigare gli attacchi di manomissione. Ad esempio, potresti voler segnalare il punteggio del giocatore al server di backend del gioco e il server vuole verificare che il punteggio non sia stato manomesso da un server proxy. Play Integrity per PC può restituire il valore impostato in questo campo all'interno della risposta di integrità firmata. Senza requestHash, il token di integrità sarà vincolato solo al dispositivo, ma non alla richiesta specifica, il che apre la possibilità di attacco.

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

Per ridurre la possibilità di un attacco, quando richiedi un esito relativo all'integrità:

• Calcola un digest di tutti i parametri di richiesta pertinenti (ad es. SHA256 di una serializzazione di richiesta stabile) dall'azione dell'utente o dalla richiesta del server in corso.
• Imposta il campo RequestIntegrityTokenParams::request_hash sul digest.

Di seguito è riportato uno snippet di codice che mostra come chiamare l'azione RequestIntegrityToken:

absl::StatusOr<google::play::integrity::RequestIntegrityTokenResult>
IntegrityInterface::RequestIntegrityToken(
    const google::play::integrity::PrepareIntegrityTokenResult&
        prepare_integrity_token_result,
    const std::string& request_hash) {
  // Check if the prepare_integrity_token_result is OK
  if (!prepare_integrity_token_result.ok()) {
    return absl::FailedPreconditionError(
        absl::StrCat("PrepareIntegrityTokenResult is not OK. Error code: ",
                     prepare_integrity_token_result.error_code));
  }

  google::play::integrity::RequestIntegrityTokenParams params{
      .request_token_data =
          prepare_integrity_token_result.request_token_data,
      .request_hash = request_hash};

  auto promise = std::make_shared<std::promise<
      google::play::integrity::RequestIntegrityTokenResult>>();
  client_.RequestIntegrityToken(
      params,
      [promise](google::play::integrity::RequestIntegrityTokenResult result) {
        promise->set_value(std::move(result));
      });

  return promise->get_future().get();
}

Passaggio 3: decripta e verifica i token di integrità sul server di backend del gioco

Decripta un token di integrità

Dopo aver richiesto un esito relativo all'integrità, l'API Play Integrity fornisce un token di risposta criptato. Per ottenere gli esiti relativi all'integrità del dispositivo, devi decriptare il token di integrità sui server di Google:

1. Crea un account di servizio nel progetto Google Cloud collegato alla tua app.

2. Sul server dell'app, recupera il token di accesso dalle credenziali del tuo account di servizio utilizzando l'ambito playintegrity ed effettua la seguente richiesta:

   playintegrity.googleapis.com/v1/<var>PACKAGE_NAME</var>:decodePcIntegrityToken -d \
    '{ "integrity_token": "<var>INTEGRITY_TOKEN</var>" }'
   

3. Leggi la risposta JSON.

Il payload risultante è un token di testo normale che contiene esiti relativi all'integrità e dettagli, oltre alle informazioni fornite dallo sviluppatore. Un token di integrità decriptato ha il seguente aspetto:

{
  "requestDetails": {
    "requestPackageName": "com.your.package.name",
    "requestTime": "2025-08-29T13:10:37.285Z",
    "requestHash": "your_request_hash_string"
  },
  "deviceIntegrity": {
    "deviceRecognitionVerdict": [
      "MEETS_PC_INTEGRITY"
    ]
  },
  "accountDetails": {
    "appLicensingVerdict": "LICENSED"
  }
}

Verifica il token di integrità

Il campo requestDetails del token di integrità decodificato contiene informazioni sulla richiesta, incluse le informazioni fornite dallo sviluppatore in requestHash.

I campi requestHash e packageName devono corrispondere a quelli della richiesta originale. Pertanto, verifica la parte requestDetails del payload JSON assicurandoti che requestPackageName e requestHash corrispondano a quelli inviati nella richiesta originale, come mostrato nel seguente snippet di codice:

const auto& request_details = json_payload["requestDetails"];

if (request_details.value("requestPackageName", "") != <YOUR_PACKAGE_NAME>) {
  // Don't trust the verdicts.
}

// Check for the existence of the request_hash.
// If you set a request hash in the request and it's not present, you shouldn't
// trust the verdicts.
if (!request_details.contains("requestHash")) {
    // Don't trust the verdicts.
}


// The requestHash from request_details needs to match the request hash your
// app provided.
if (request_details.value("requestHash", "") != <PROVIDED_REQUEST_HASH>) {
    // Don't trust the verdicts.
}

// You can read the rest of payload's fields.

Passaggio 4: decidi quale azione intraprendere in base all'esito relativo all'integrità

Il campo deviceIntegrity può contenere un singolo valore, deviceRecognitionVerdict. Puoi utilizzare questo valore per determinare se il tuo gioco è in esecuzione su un PC che supera i controlli di integrità di Play (ovvero una risposta MEETS_PC_INTEGRITY). Il campo accountDetails contiene un singolo valore, appLicensingVerdict. Puoi utilizzare questo valore per determinare se l'utente ha ottenuto la licenza da Play. Il server di backend del tuo gioco può raccogliere queste informazioni e utilizzarle per determinare l'azione che il gioco deve intraprendere, ad esempio consentire il proseguimento di un evento di gioco o negare l'accesso al traffico rischioso.

"deviceIntegrity": {
  "deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}
"accountDetails": {
  "appLicensingVerdict": "LICENSED"
}

Esiti integrità del dispositivo

deviceRecognitionVerdict può avere i seguenti valori:

MEETS_PC_INTEGRITY

Il gioco è in esecuzione in un ambiente PC originale, in cui non è stata rilevata alcuna manomissione sul dispositivo.

Vuoto (un valore vuoto)

Il gioco è 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 dispositivo esegue una versione manomessa di Google Desktop Services) 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).

Esiti dettagli account

appLicensingVerdict può avere i seguenti valori:

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 suo 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 necessario. Questo può accadere per diversi motivi, tra cui i seguenti:

• Il dispositivo non è abbastanza attendibile.
• La versione dell'app installata sul dispositivo non è nota a Google Play.
• L'utente non ha eseguito l'accesso a Google Play.

Passaggio 5: gestisci i codici di errore

Se il tuo gioco effettua una richiesta di Play Integrity per PC e la chiamata non va a buon fine, il gioco riceve un codice di errore. Questi errori possono verificarsi per vari motivi, ad esempio problemi ambientali come una connessione di rete scadente, problemi con l'integrazione dell'API o attività dannose e attacchi attivi.

Codici di errore riprovabili

A volte questi errori sono causati da situazioni temporanee, quindi devi riprovare a effettuare la chiamata con una strategia di backoff esponenziale.

Per ulteriori consigli sulle strategie di ripetizione , fai clic qui.

Codici di errore non riprovabili

I tentativi automatici non sono utili in questi casi. Tuttavia, un nuovo tentativo manuale potrebbe essere utile se l'utente risolve la condizione che ha causato il problema.

Testa le diverse risposte dell'API Play Integrity all'interno dell'app

Puoi creare test per valutare l'interazione dell'API Play Integrity con la tua app.

1. Configura un gruppo Google (o tutti quelli che vuoi) con gli indirizzi email degli utenti. Puoi selezionare gli esiti relativi all'integrità o il codice di errore che questi utenti devono ricevere nella tua app dai server di Google Play. In questo modo puoi testare la reazione della tua app a tutte le possibili risposte ed errori.

2. Crea un ticket qui e segnala quale gruppo Google riceverà quale risposta dell'API. A ogni gruppo viene assegnata una delle seguenti opzioni:

   	Esito relativo all'autorizzazione superato	Esito relativo all'autorizzazione non superato	Impossibile valutare l'esito relativo all'autorizzazione
   Integrità del dispositivo superata	ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_LICENSED	ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_UNLICENSED	ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_LICENSING_UNEVALUATED
   Integrità del dispositivo non superata	N/D	N/D	ALLOWLIST_CONFIG_NO_PC_INTEGRITY_LICENSING_UNEVALUATED

   Se l'esito relativo all'integrità del dispositivo non viene superato, l'esito relativo all'autorizzazione restituirà sempre UNEVALUATED.

3. Riceverai una notifica quando la richiesta sarà stata elaborata e gli utenti di test saranno inclusi nella lista consentita per ricevere gli esiti relativi all'integrità predefiniti per i test.