A API Play Integrity para PC ajuda a verificar se as interações e solicitações do servidor vêm de um PC legítimo. Ao detectar interações possivelmente perigosas e fraudulentas, o servidor de back-end do app pode responder com as ações adequadas para evitar ataques e reduzir abusos.
A API retorna vereditos que ajudam a detectar possíveis ameaças, incluindo:
- Dispositivos e ambientes de risco:o veredito
deviceIntegrityajuda a determinar se o app está sendo executado em um dispositivo PC genuíno ou em uma instância genuína do Google Play Games para PC.
Integrar com a API
Para integrar a API Play Integrity para PC ao seu app, primeiro faça a configuração inicial no console do Google Cloud. Depois disso, siga as etapas abaixo para cada verificação de integridade:
- Preparar o token de integridade
- Solicitar seu token de integridade
- Solicitar dados de token
Configuração inicial no console do Google Cloud
Todo app ou SDK que chama a API Play Integrity precisa usar um projeto do Google Cloud para autenticar as chamadas e monitorar o uso da API. Se você quiser criar um novo projeto do Cloud ou caso seu app seja distribuído exclusivamente fora do Google Play, ative as respostas da API Play Integrity no console do Google Cloud.
No Console do Google Cloud, crie um projeto do Cloud ou escolha um projeto atual que você queira usar com a API Play Integrity para PC. Navegue até APIs e serviços. Selecione Ativar APIs e serviços. Pesquise API Play Integrity e ative. Agora você pode integrar a API Play Integrity ao app.
Etapa 1: preparar o token de integridade
void PrepareIntegrityToken( const PrepareIntegrityTokenParams & params, PrepareIntegrityTokenContinuation continuation )
Antes de solicitar um token de integridade (consulte RequestIntegrityToken), é necessário preparar (ou "aquecer") a API Play Integrity. Isso 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.
Se a operação for bem-sucedida, a continuação será chamada com um PrepareIntegrityTokenResultValue que contém 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 de RequestIntegrityToken. Só faça uma chamada para PrepareIntegrityToken se o aplicativo determinar que é necessário reavaliar totalmente o veredito de integridade.
| Detalhes | |
|---|---|
| Parâmetros | params: parâmetros que contêm um número de projeto do Google Cloud. continuation: o callback assíncrono para retornar ao provedor de token de integridade. |
Etapa 2: solicitar seu token de integridade
void RequestIntegrityToken( const RequestIntegrityTokenParams & params, RequestIntegrityTokenContinuation continuation )
Os tokens de integridade são um mecanismo para seu aplicativo verificar se o dispositivo não foi violado. Por exemplo, seu servidor de back-end pode usar o token de integridade para verificar:
- Dispositivo genuíno: determina se o aplicativo está sendo executado em um dispositivo genuíno que contém uma instância genuína do Google Play Games para PC e não foi adulterado.
Ao verificar uma ação do usuário no app com a API Play Integrity para
PC, use o campo RequestIntegrityTokenParams::request_hash
para mitigar ataques de adulteração. Por exemplo, um jogo 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 API Play Integrity retorna
o valor definido deste 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.
Para atenuar isso 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.
| Detalhes | |
|---|---|
| Parâmetros | params: parâmetros que contêm o RequestTokenData preparado e o hash da solicitação de verificação de integridade. continuation: o callback assíncrono para retornar os dados. |
Etapa 3: solicitar dados do token
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. Para fazer isso, siga estas etapas:
- Crie uma conta de serviço no projeto do Google Cloud vinculado ao app.
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>" }'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. O formato do token é o seguinte:
{
"requestDetails": { ... },
"deviceIntegrity": { ... },
}
Primeiro, confira se os valores no campo requestDetails correspondem aos
da solicitação original antes de verificar cada veredito de integridade. As seções
abaixo descrevem cada campo em mais detalhes.
Campo de detalhes da solicitação
O campo requestDetails contém informações sobre a solicitação, incluindo
informações fornecidas pelo desenvolvedor no requestHash para solicitações padrão e
no nonce para solicitações clássicas.
"requestDetails": {
// Application package name this attestation was requested for.
// Note that this field might be spoofed in the middle of the request.
"requestPackageName": "com.package.name",
// The timestamp when the integrity token was requested.
"requestTime": "1675655009345"
// Request hash provided by the developer.
"requestHash": "aGVsbG8gd29scmQgdGhlcmU",
}
Esses valores precisam corresponder aos da
solicitação original. Portanto, verifique a parte
requestDetails do payload JSON, garantindo que
requestPackageName e requestHash correspondam ao que foi enviado na solicitação
original.
Campo de integridade do dispositivo
O campo deviceIntegrity pode conter um único valor,
deviceRecognitionVerdict, que tem um ou mais identificadores que representam a capacidade de um
dispositivo de garantir a integridade do app. Se um dispositivo não atender aos critérios de algum
identificador, o campo deviceIntegrity vai omitir deviceRecognitionVerdict.
"deviceIntegrity": {
"deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}
Por padrão, deviceRecognitionVerdict pode conter o seguinte:
MEETS_PC_INTEGRITY- Retorna um veredito se o app estiver sendo executado em um ambiente de PC genuíno, em que nenhuma violação no dispositivo foi detectada.
- Vazio (um valor em branco)
- O app está sendo executado em um dispositivo que tem sinais de ataque, como hooks de API, ou comprometimentos do sistema, como acesso root, ou o app não está sendo executado em um dispositivo físico, mas sim, por exemplo, em um emulador que falha nas verificações de integridade do Google Play.
Limites de uso
Limites de uso da API Play Integrity
No total, seu app estará sujeito a um máximo de 10.000 solicitações por dia. Caso ele precise processar um número maior de usuários, você pode solicitar o aumento do limite diário seguindo as instruções abaixo.
| Ação | Cota diária por app | Observações |
|---|---|---|
| Solicitações de token | 10.000 | Compartilhada entre a API Play Integrity para PC e a API Play Integrity para solicitações clássicas e padrão |
| Descriptografias de token nos servidores do Google | 10.000 | Compartilhada entre a API Play Integrity para PC e a API Play Integrity para solicitações clássicas e padrão |
Aumentar o número diário máximo de solicitações
Para se qualificar para um aumento do número máximo de solicitações por dia, o app precisa estar disponível no Google Play além de outros canais de distribuição.
Para pedir um aumento no número máximo diário de solicitações, faça o seguinte:
- Vincule o projeto do Google Cloud que você está usando para a API Play Integrity no Play Console.
- Verifique se você está implementando a lógica da API corretamente, incluindo a estratégia de repetição recomendada.
- Use este formulário para solicitar um aumento de cota.
Pode levar até uma semana para aumentar a cota da API Play Integrity. Recomendamos monitorar o uso da API no Google Play Console ou no console do Google Cloud, em que também é possível definir alertas de cota para evitar interrupções no serviço.
Os aumentos de cota são aplicados automaticamente à chamada do cliente para gerar tokens de integridade e à chamada do servidor para descriptografar e verificar tokens de integridade.
Considerações sobre segurança
A API Play Integrity oferece um melhor resultado quando você segue estas práticas recomendadas:
Tenha uma estratégia contra abusos
A API Play Integrity funciona melhor quando usada em conjunto com outros sinais como parte da sua estratégia geral contra abuso, e não como o único mecanismo antiabuso. Use a API em conjunto com outras práticas recomendadas de segurança adequadas para seu app. Por padrão, o app pode fazer até 10.000 solicitações por dia em todas as instalações. É possível solicitar o aumento do seu limite diário.
Coletar dados de telemetria e entender o público-alvo antes de agir
Antes de mudar o comportamento do app com base nos vereditos da API Play Integrity, é possível entender a situação atual com o público implementando a API sem restrições. Depois de saber quais vereditos a base instalada atual está retornando, é possível estimar o impacto de qualquer medida que você planeja tomar e ajustar sua estratégia contra abuso de forma adequada.
Solicitar um veredito de integridade em um momento adequado
Faça solicitações de API o mais próximo possível do momento da ação ou solicitação do servidor que você quer proteger.
Torne as solicitações de API difíceis de replicar
As solicitações de API têm um campo chamado "requestHash", que é usado para proteger contra adulteração e ataques semelhantes. Nesse campo, inclua um resumo de todos os valores relevantes da solicitação do app. Siga as orientações sobre como usar a vinculação de conteúdo para proteger as solicitações padrão do app.
Evite armazenar vereditos de integridade em cache
Armazenar vereditos de integridade em cache aumenta o risco de proxy, que é um ataque em que um usuário de má-fé reutiliza um veredito de um dispositivo genuíno para fins abusivos em outro ambiente.
Envie outros tipos de respostas do servidor ao app
Ter vários resultados de decisão é mais difícil do que enviar uma resposta binária de Permitir / Negar do servidor de volta ao app para cada resposta. Por exemplo, você pode usar uma série de respostas relacionadas, como Permitir, Permitir com limites, Permitir com limites após o preenchimento do CAPTCHA e Negar.
Mostrar mensagens de erro acionáveis
Quando possível, forneça mensagens de erro úteis aos usuários e informe o que pode ser feito para corrigir o problema.
Antecipar problemas ou falhas inesperadas
O painel de status do Google Play mostra o status do serviço da API Play Integrity, além de informações sobre quaisquer interrupções e falhas temporárias. Planeje com antecedência como você quer que o servidor de back-end funcione no caso improvável de uma interrupção do serviço em grande escala da API Play Integrity.
Termos de Serviço e segurança dos dados
Ao acessar ou usar a API Play Integrity para PC, você concorda com os Termos de Serviço da API Play Integrity. Leia e entenda todos os termos e políticas aplicáveis antes de acessar a API.
O Google Play tem uma seção "Segurança dos dados" para que os desenvolvedores divulguem as práticas de coleta, compartilhamento e segurança de dados dos apps para manter os usuários informados. Para ajudar você a preencher o formulário de dados, consulte estas informações sobre como a API Play Integrity lida com dados.