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.
• Consulta 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 scegline uno esistente da utilizzare con Play Integrity per PC. Vai ad API e servizi e attiva l'API Google Play Integrity.
• Se prevedi di effettuare più di 10.000 richieste al giorno per Play Integrity per PC, devi richiedere un aumento del limite massimo giornaliero.

Passaggio 1: decidi come utilizzare 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, puoi richiedere un verdetto quando il gioco viene aperto, quando un giocatore esegue l'accesso o quando un giocatore partecipa a una partita multiplayer. Poi decidi come gestire le diverse risposte di 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.
• Raccogli la risposta e implementa la logica sul server di backend per consentire ai dispositivi che superano i verdetti di integrità di giocare normalmente, mentre metti in discussione o nega l'accesso al traffico proveniente da ambienti sospetti.
• Raccogli la risposta e implementa la logica nel backend per abbinare i giocatori su dispositivi che superano i controlli di integrità, mentre abbina il traffico proveniente da ambienti sospetti.

Passaggio 2: richiedi i 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 in modo intelligente nella cache le informazioni di attestazione parziale sul dispositivo per ridurre la latenza nel percorso critico quando effettui una richiesta di un verdetto di integrità. Puoi farlo in modo asincrono non appena il gioco si apre, in modo da poter effettuare richieste di integrità on demand quando necessario.

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

In caso di esito positivo, 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 e riutilizzati per la durata della sessione dell'applicazione per le chiamate a RequestIntegrityToken.

Solo se la tua applicazione determina che è necessario rivalutare completamente il verdetto di integrità, deve essere effettuata una chiamata a PrepareIntegrityToken.

Di seguito è riportato uno snippet di codice che mostra come deve essere chiamata 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();
}

Richiedere il 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 tuo gioco effettua una richiesta al server che vuoi verificare come autentica, puoi richiedere un token di integrità e inviarlo al server di backend del gioco per la decrittografia e la verifica.

Quando verifichi un'azione dell'utente nella tua app con l'API Play Integrity per PC, puoi utilizzare il campo RequestIntegrityTokenParams::request_hash per ridurre il rischio di attacchi di manomissione. Ad esempio, potresti voler segnalare il punteggio del giocatore al server di backend del tuo gioco e il tuo server vuole verificare che questo 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à verrà associato solo al dispositivo, ma non alla richiesta specifica, il che apre la possibilità di attacchi.

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 della 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 può essere chiamata 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

Decriptare 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 dell'integrità del dispositivo, devi decriptare il token di integrità sui server di Google:

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

2. Sul server della tua app, recupera il token di accesso dalle credenziali del service account utilizzando l'ambito playintegrity ed esegui 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 non crittografato che contiene esiti relativi all'integrità e dettagli insieme 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"
    ]
  },
}

Verificare il token di integrità

Il campo requestDetails del token di integrità decodificato contiene informazioni sulla richiesta, incluse le informazioni fornite dallo sviluppatore nel 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 quanto inviato 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 al risultato del controllo dell'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à Play (ovvero una risposta MEETS_PC_INTEGRITY). Il server di backend del tuo gioco può raccogliere queste informazioni e utilizzarle per determinare quale azione deve intraprendere il gioco, ad esempio consentire a un evento di gioco di procedere o negare l'accesso al traffico rischioso.

"deviceIntegrity": {
  "deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}

deviceRecognitionVerdict può avere i seguenti valori:

MEETS_PC_INTEGRITY

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

Vuoto (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 un dispositivo che 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).

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 non irreversibili

La causa di questi errori è a volte dovuta a condizioni temporanee, pertanto devi riprovare la chiamata con una strategia di backoff esponenziale.

Consulta questa pagina per altri consigli sulle strategie di ripetizione.

Codici di errore non riproducibili

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.