Visão geral da API Play Integrity

A API Play Integrity ajuda a verificar se as ações do usuário e as solicitações do servidor vêm do seu app original, instalado pelo Google Play e executado em um dispositivo Android genuíno. Ao detectar interações perigosas, como as de versões adulteradas do app, dispositivos não confiáveis ou ambientes emulados, o servidor de back-end pode responder com as ações adequadas para evitar abusos e acesso não autorizado, combater fraudes e trapaças e proteger os usuários contra ataques.

A API retorna vereditos que ajudam a detectar possíveis ameaças, incluindo:

• Acesso não autorizado: o veredito accountDetails ajuda a determinar se o usuário instalou ou pagou pelo app ou jogo no Google Play.
• Adulteração de código: o veredito appIntegrity ajuda a determinar se você está interagindo com o binário não modificado reconhecido pelo Google Play.
• Dispositivos de risco e ambientes emulados: o veredito deviceIntegrity ajuda a determinar se o app está sendo executado em um dispositivo Android genuíno certificado pelo Play Protect ou em uma instância genuína do Google Play Games para PC.

Importante: quando a API Play Integrity avalia um ambiente, ela usa indicadores de segurança protegidos por hardware que são altamente resilientes a ataques e evasão. A API Play Integrity simplifica o trabalho de integração do desenvolvedor e o gerenciamento contínuo, abstraindo a complexidade dos indicadores e a mitigação de problemas em versões do SDK do Android, chaves provisionadas pelo fabricante do dispositivo e modelos de dispositivos.

Os desenvolvedores do Google Play também podem ativar o recebimento de outros vereditos para detectar uma variedade maior de possíveis ameaças, incluindo:

• Dispositivos sem patch: a resposta MEETS_STRONG_INTEGRITY no veredito deviceIntegrity ajuda a determinar se um dispositivo aplicou atualizações de segurança recentes (para dispositivos com Android 13 e versões mais recentes).
• Acesso arriscado por outros apps:o appAccessRiskVerdict ajuda você a determinar se há apps em execução que podem ser usados para capturar a tela, mostrar sobreposições ou controlar o dispositivo (por exemplo, usando de forma indevida a permissão de acessibilidade).
• Malware conhecido:o playProtectVerdict ajuda a determinar se o Google Play Protect está ativado e se encontrou apps de risco ou perigosos instalados no dispositivo.
• Hiperatividade:o nível recentDeviceActivity ajuda a determinar se um dispositivo fez um volume anormalmente alto de solicitações recentemente, o que pode indicar tráfego automatizado e ser um sinal de ataque.
• Abuso repetido e dispositivos reutilizados:o deviceRecall (Beta) ajuda a determinar se você está interagindo com um dispositivo que já sinalizou, mesmo que o app tenha sido reinstalado ou o dispositivo tenha sido redefinido.

A API pode ser usada em todos os formatos do Android, incluindo smartphones, tablets, dobráveis, Android Auto, Android TV, Android XR, ChromeOS, Wear OS e no Google Play Games para PC.

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 o 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 limite máximo 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.

Decida como solicitar vereditos de integridade

A API Play Integrity oferece duas opções para solicitar e receber vereditos de integridade. Se você fizer solicitações padrão, solicitações clássicas ou uma combinação dos dois tipos de solicitação, a resposta do veredito de integridade será retornada no mesmo formato.

As solicitações de API padrão são adequadas para todos os apps ou jogos e podem ser feitas sob demanda para verificar se uma ação do usuário ou solicitação do servidor é genuína. As solicitações padrão têm a menor latência (algumas centenas de milissegundos, em média) e uma alta confiabilidade de um veredito utilizável. As solicitações padrão usam o armazenamento em cache inteligente no dispositivo e delegam proteção ao Google Play contra certos tipos de ataque.

As solicitações de API clássicas, a forma original de solicitar vereditos de integridade, também continuarão disponíveis. As solicitações clássicas têm maior latência (alguns segundos, em média) e você é responsável por reduzir o risco de determinados tipos de ataques. As solicitações clássicas usam mais dados e bateria do usuário do que as padrão porque iniciam uma nova avaliação e, por isso, não devem ser feitas com frequência. Elas são úteis para conferir se uma ação altamente confidencial ou valiosa é genuína. Se estiver pensando em fazer uma solicitação clássica e armazená-la em cache para uso futuro, faça uma solicitação padrão para reduzir o risco de ataques.

A tabela abaixo destaca as principais diferenças entre os dois tipos de solicitações:

	Solicitação de API padrão	Solicitação de API clássica
Versão mínima do SDK do Android exigida	Android 5.0 (nível 21 da API) ou mais recente	Android 4.4 (nível 19 da API) ou mais recente
Aquecimento da API necessário	✔️ (alguns segundos)	❌
Latência de solicitação típica	Algumas centenas de milissegundos	Alguns segundos
Possível frequência de solicitação	Frequente (verificação sob demanda de qualquer ação ou solicitação)	Infrequente (verificação única para ações de maior valor ou solicitações mais sensíveis)
Mitigação de ataques de repetição e semelhantes	Mitigação automática do Google Play	Use o campo nonce com a lógica do lado do servidor

Consulte uma tabela com mais diferenças nas considerações sobre solicitações clássicas.

Solicitar um veredito de integridade em um momento adequado

Solicite um veredito de risco de acesso ao app o mais próximo possível do momento da ação ou da solicitação do servidor que você quer proteger contra o acesso, para evitar que os golpistas ignorem a verificação de integridade realizada pelo app.

Torne as solicitações de API difíceis de replicar

As solicitações de API padrão 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.

As solicitações de API clássicas têm um campo chamado nonce (abreviação de "number once"), que é usado para proteção contra certos tipos de ataque, como ataques de repetição e adulteração. Siga as orientações sobre como gerar valores de uso único para proteger as solicitações clássicas do app.

Cuidado: os dados usados nos campos requestHash e nonce ficam visíveis em texto não criptografado para o app e para o Google. É necessário criptografar ou gerar hash dos dados antes de transmiti-los à API Play Integrity.

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. Em vez de armazenar as respostas em cache, faça uma solicitação de API padrão para receber um veredito sob demanda.

Tenha uma estratégia de aplicação em níveis

O veredito de integridade da API Play Integrity tem várias respostas possíveis, o que possibilita criar uma estratégia antiabuso com vários níveis de aplicação. Você pode fazer isso configurando o servidor de back-end do app para se comportar de maneira diferente dependendo de cada resposta possível ou de cada grupo de respostas.

Também é possível classificar sua estratégia de aplicação com base na confiabilidade do dispositivo, ativando o recebimento de outros rótulos de dispositivo na resposta da API no Play Console. Cada dispositivo retornará todos os rótulos que atendem aos critérios. Por exemplo, depois de ativar o recebimento de todos os identificadores de dispositivo, você pode confiar mais em um dispositivo que retorna MEETS_STRONG_INTEGRITY, MEETS_DEVICE_INTEGRITY e MEETS_BASIC_INTEGRITY do que um dispositivo que só retorna MEETS_BASIC_INTEGRITY. É possível usar respostas diferentes do servidor para cada cenário.

Dica: o identificador MEETS_STRONG_INTEGRITY oferece a maior resiliência porque exige que o dispositivo tenha indicadores de segurança protegidos por hardware além de, no Android 13 e versões mais recentes, uma atualização de segurança recente. Menos dispositivos retornam esse rótulo em comparação com o MEETS_DEVICE_INTEGRITY. Por isso, recomendamos usá-lo como parte de uma estratégia de restrição em níveis para alcançar mais usuários.

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.

Detecte abusos recorrentes usando o reconhecimento do dispositivo, preservando a privacidade do usuário

O reconhecimento do dispositivo permite que os apps armazenem e recuperem alguns dados personalizados associados a um dispositivo específico de uma forma que preserva a privacidade do usuário. Os dados são armazenados nos servidores do Google, permitindo que o app recupere de forma confiável os dados de cada dispositivo, mesmo após a reinstalação do app ou a redefinição do dispositivo. Assim, você tem uma maneira confiável de reidentificar um dispositivo que foi abusivo no passado para tomar medidas e impedir que ele seja usado para abuso novamente. Você pode definir seu próprio significado para os três valores que compõem os dados de recall de dispositivo:

• É possível usá-los como até três flags ou booleanos separados. Por exemplo, os valores podem representar se um dispositivo criou ou não uma conta, se resgatou ou não um teste sem custo financeiro ou se é conhecido ou não por abuso de alta gravidade.
• Outra opção é combinar todos os estados dos valores em até oito rótulos personalizados. Por exemplo, um rótulo para o estado padrão quando todos os três valores não são modificados e sete rótulos com significados personalizados. Isso permite segmentar todos os dispositivos em até oito grupos com base em comportamentos ou ações que você define. Nesse cenário, o writeDates mais recente dos três indica quando você atualizou o rótulo pela última vez.

Também tenha em mente os pré-requisitos e outras considerações ao trabalhar com dados de recall de dispositivos.

Detectar abuso em grande escala usando a atividade recente do dispositivo

Use o recurso Atividade recente do dispositivo na API Play Integrity para encontrar dispositivos que solicitam um grande número de tokens de integridade. Os infratores de atividade de alto volume normalmente geram resultados de atestado válidos usando dispositivos reais e os fornecem a bots para automatizar ataques em dispositivos e emuladores com acesso root. Use o nível de atividade recente do dispositivo para verificar quantos atestados foram gerados pelo app nesse dispositivo na última hora.

Mostrar mensagens de erro acionáveis

Quando possível, forneça mensagens de erro úteis aos usuários e os informe sobre o que pode ser feito para corrigir o problema, como tentar de novo, ativar a conexão de Internet ou conferir se o app da Play Store está atualizado.

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. Observe que o servidor de back-end também precisa estar pronto para funcionar caso as chaves de atestado de chave da plataforma Android específicas para dispositivos sejam revogadas.

Considere soluções completas contra fraude empresarial

Clientes empresariais que procuram uma solução completa de gerenciamento de fraudes e bots podem adquirir o reCAPTCHA Enterprise para dispositivos móveis, que conta com SDKs para Android com pontuações de risco de fraude. O reCAPTCHA Enterprise inclui automaticamente os indicadores da API Play Integrity e os combina com a rede reCAPTCHA e indicadores de aplicativos para clientes, fornecendo uma solução de gerenciamento de fraudes simples e descomplicada. Ele também pode fornecer proteção para apps Android em que a API Play Integrity não está disponível.

Contestar tráfego arriscado ao acessar recursos sensíveis ou de alto valor

Identifique ações sensíveis ou de alto valor no app ou jogo para proteger com a API Play Integrity em vez de negar o acesso imediatamente. Sempre que possível, conteste o tráfego arriscado antes de permitir ações de alto valor. Por exemplo, quando o risco de acesso indicar que um app que pode capturar a tela está em execução, peça para o usuário desativar ou desinstalar apps que conseguem fazer isso antes de permitir que ele prossiga para a funcionalidade que você quer proteger.

Termos de Serviço e segurança dos dados

Ao acessar ou usar a API Play Integrity, você concorda com os Termos de Serviço da API Play Integrity. Leia e entenda todos os termos e políticas relevantes 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.