Integrar a API Play Integrity para PC ao app

A Play Integrity para PC ajuda a verificar se os eventos do jogo e as solicitações do servidor vêm de uma instância genuína do Google Play Games para PC em um dispositivo de PC genuíno. Ao detectar dispositivos potencialmente arriscados e emuladores desconhecidos, o servidor de back-end do jogo pode responder com as ações adequadas para evitar trapaças, acesso não autorizado, tráfego fraudulento e abusos.

Pré-requisitos

• Conclua a configuração do SDK.
• Analise as considerações de segurança da API Integrity.
• Leia e entenda os Termos de Serviço da API Integrity e as informações sobre o tratamento de dados.
• No Console do Google Cloud, crie um projeto na nuvem ou escolha um projeto na nuvem atual que você queira usar com a Play Integrity para PC. Acesse APIs e serviços e ative a API Google Play Integrity.
• Se você espera fazer mais de 10 mil solicitações da Play Integrity para PC por dia, você deve pedir para aumentar seu limite diário.

Etapa 1: decidir como você vai usar a Play Integrity para PC no jogo

Decida quando você vai chamar a Play Integrity para PC para receber um veredito de integridade sobre o ambiente. Por exemplo, você pode solicitar um veredito quando o jogo é aberto, quando um jogador faz login ou quando um jogador entra em um jogo multiplayer. Em seguida, decida como você vai lidar com diferentes respostas de integridade. Por exemplo, você pode:

• Coletar a resposta sem nenhuma ação de aplicação e analisar os dados internamente para entender se é um sinal útil de abuso.
• Coletar a resposta e implementar a lógica no servidor de back-end para permitir que dispositivos que passam nos vereditos de integridade joguem normalmente, ao mesmo tempo em que desafiam ou negam o acesso ao tráfego de ambientes suspeitos.
• Coletar a resposta e implementar a lógica no back-end para combinar jogadores em dispositivos que passam nas verificações de integridade, ao mesmo tempo em que combinam o tráfego de ambientes suspeitos.

Etapa 2: solicitar tokens de integridade no jogo

Preparar a Play Integrity para PC

Prepare (ou "aqueça") a Play Integrity para PC, que permite que o Google Play armazene em cache de forma inteligente informações parciais de atestado no dispositivo para diminuir a latência no caminho crítico quando você faz uma solicitação de veredito de integridade. Você pode fazer isso de forma assíncrona assim que o jogo for aberto para fazer solicitações de integridade sob demanda quando precisar.

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

Em caso de sucesso, a continuação será chamada com um PrepareIntegrityTokenResultValue contendo um RequestTokenData que deve ser usado para solicitar um token de integridade. Esses dados precisam ser armazenados em cache na memória e reutilizados durante a sessão do aplicativo para chamadas para RequestIntegrityToken.

Só será feita uma chamada para PrepareIntegrityToken se o aplicativo determinar que é necessário reavaliar totalmente o veredito de integridade.

Confira um snippet de código que mostra como a ação PrepareIntegrityToken precisa ser chamada:

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();
}

Solicitar um token de integridade

Os tokens de integridade são um mecanismo para o jogo verificar se o dispositivo não foi adulterado. Sempre que o jogo fizer uma solicitação de servidor que você queira verificar se é genuína, solicite um token de integridade e o envie ao servidor de back-end do jogo para descriptografia e verificação.

Ao verificar uma ação do usuário no app com a API Play Integrity para PC, você pode usar o campo RequestIntegrityTokenParams::request_hash para mitigar ataques de adulteração. Por exemplo, você pode querer informar a pontuação do jogador ao servidor de back-end do jogo, e seu servidor quer verificar se ela não foi adulterada por um servidor proxy. A Play Integrity para PC pode retornar o valor definido nesse campo na resposta de integridade assinada. Sem o requestHash, o token de integridade será vinculado apenas ao dispositivo, mas não à solicitação específica, o que abre a possibilidade de ataque.

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

Para mitigar a possibilidade de um ataque, ao solicitar um veredito de integridade:

• Calcule um resumo de todos os parâmetros de solicitação relevantes (por exemplo, SHA256 de uma serialização de solicitações estável) da ação do usuário ou da solicitação do servidor que estiver acontecendo.
• Defina o campo RequestIntegrityTokenParams::request_hash como o resumo.

Confira um snippet de código que mostra como a ação RequestIntegrityToken pode ser chamada:

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();
}

Etapa 3: descriptografar e verificar os tokens de integridade no servidor de back-end do jogo

Descriptografar um token de integridade

Depois de solicitar um veredito de integridade, a API Play Integrity fornece um token de resposta criptografado. Para extrair os vereditos de integridade do dispositivo, é necessário descriptografar o token de integridade nos servidores do Google:

1. Crie uma conta de serviço no projeto do Google Cloud que está vinculado ao app.

2. No servidor do app, busque o token de acesso nas credenciais da conta de serviço usando o escopo playintegrity e faça esta solicitação:

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

3. Leia a resposta JSON.

O payload resultante é um token de texto simples que contém vereditos e detalhes de integridade, além de informações fornecidas pelo desenvolvedor. Um token de integridade descriptografado tem esta aparência:

{
  "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"
  }
}

Verificar o token de integridade

O campo requestDetails do token de integridade decodificado contém informações sobre a solicitação, incluindo informações fornecidas pelo desenvolvedor no requestHash.

Os campos requestHash e packageName precisam corresponder aos da solicitação original. Verifique a parte requestDetails do payload JSON, garantindo que o requestPackageName e o requestHash correspondam ao que foi enviado na solicitação original, conforme mostrado no snippet de código abaixo:

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.

Etapa 4: decidir qual ação tomar com base no veredito de integridade

O campo deviceIntegrity pode conter um único valor, deviceRecognitionVerdict. Você pode usar esse valor para determinar se o jogo está sendo executado em um PC que passa nas verificações de integridade do Google Play (que é uma resposta MEETS_PC_INTEGRITY). O campo accountDetails contém um único valor, appLicensingVerdict. Você pode usar esse valor para determinar se o usuário recebeu a licença do Google Play. O servidor de back-end do jogo pode coletar essas informações e usá-las para determinar qual ação o jogo precisa realizar, como permitir que um evento do jogo continue ou negar o acesso a tráfego arriscado.

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

Vereditos de integridade do dispositivo

deviceRecognitionVerdict pode ter estes valores:

MEETS_PC_INTEGRITY

O jogo está sendo executado em um ambiente de PC genuíno, em que nenhuma adulteração no dispositivo foi detectada.

Vazio (um valor em branco)

O jogo está sendo executado em um dispositivo que tem sinais de ataque (como hook de API) ou comprometimento do sistema (como um dispositivo que executa uma versão adulterada dos Serviços do Google Desktop) ou o app não está sendo executado em um dispositivo físico (como um emulador que não passa nas verificações de integridade do Google Play).

Vereditos dos detalhes da conta

appLicensingVerdict pode ter estes valores:

LICENSED

O usuário tem titularidade do app. Em outras palavras, o usuário instalou ou atualizou o app no dispositivo pelo Google Play.

UNLICENSED

O usuário não tem a titularidade do app. Isso acontece quando, por exemplo, o usuário transfere o app por sideload ou não o adquire do Google Play.

UNEVALUATED

Os detalhes de licenciamento não foram avaliados porque um requisito necessário está ausente. Isso pode acontecer por vários motivos, incluindo os seguintes:

• O dispositivo não é confiável o suficiente.
• A versão do app instalada no dispositivo é desconhecida para o Google Play.
• O usuário não está conectado ao Google Play.

Etapa 5: processar códigos de erro

Se o jogo fizer uma solicitação da Play Integrity para PC e a chamada falhar, ele vai receber um código de erro. Esses erros podem acontecer por vários motivos, como problemas ambientais, como uma conexão de rede ruim, problemas com a integração da API ou atividades maliciosas e ataques ativos.

Códigos de erros que aceitam novas tentativas

Às vezes, a causa desses erros é devido a condições temporárias. Portanto, você precisa repetir a chamada com uma estratégia de espera exponencial.

Confira mais recomendações sobre estratégias de repetição aqui.

Códigos de erros que não aceitam novas tentativas

É improvável que novas tentativas automáticas ajudem nesses casos. No entanto, uma nova tentativa manual pode ajudar se o usuário resolver a condição que causou o problema.

Testar diferentes respostas da API Play Integrity no app

É possível criar testes para avaliar como a API Play Integrity interage com o app.

1. Configure um Grupo do Google (ou quantos quiser) com endereços de e-mail de usuários. Você pode selecionar os vereditos de integridade ou o código de erro que esses usuários precisam receber no app dos servidores do Google Play. Assim, você testa como o app reage a todas as respostas e erros possíveis.

2. Crie um tíquete aqui e informe qual Grupo do Google vai receber qual resposta da API. Cada grupo é atribuído para receber uma das seguintes opções:

   	Aprovar o veredito de licenciamento	Reprovar o veredito de licenciamento	Não foi possível avaliar o veredito de licenciamento
   Aprovar a integridade do dispositivo	ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_LICENSED	ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_UNLICENSED	ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_LICENSING_UNEVALUATED
   Reprovar a integridade do dispositivo	N/A	N/A	ALLOWLIST_CONFIG_NO_PC_INTEGRITY_LICENSING_UNEVALUATED

   Se você reprovar o veredito de integridade do dispositivo, o veredito de licenciamento sempre retornará UNEVALUATED.

3. Você será notificado quando a solicitação for processada e os usuários de teste estiverem na lista de permissões para receber os vereditos de integridade predefinidos para testes.