Integrity API do Google Play em 2026: guia passo a passo
A Play Integrity API responde a uma pergunta prática e bem específica para o seu backend: esta requisição vem da cópia do meu app que o Google Play publicou, em um dispositivo que é o que diz ser? Seu servidor pede ao Google um veredito de integridade, recebe um payload assinado e decide — no servidor, nunca no cliente — até onde confiar na interação. É a forma padrão de frear builds adulterados, clientes automatizados, emuladores e cópias instaladas por sideload antes que cheguem à economia do seu jogo, aos direitos de assinatura ou à sua receita com anúncios.
Este guia segue a ordem em que você realmente vai trabalhar: habilitar a API, vincular um projeto Cloud, escolher entre uma solicitação padrão e uma clássica, aquecer o provedor de tokens, solicitar e descriptografar um token, ler os campos de veredito, tratar cotas e códigos de erro e implantar a aplicação de políticas sem bloquear usuários pagantes. Uma regra atravessa tudo isso — a API entrega sinais para as suas próprias decisões, e a única forma duradoura de passar em uma verificação de integridade é publicar um app genuíno pelo canal oficial.
1. O que a API atesta e o que não atesta
Três famílias de veredito voltam por padrão, e cada uma responde a uma pergunta diferente.
- appIntegrity — isto veio do seu binário não modificado? O
appRecognitionVerdictretornaPLAY_RECOGNIZEDquando o pacote e o certificado correspondem ao que o Google Play distribui,UNRECOGNIZED_VERSIONquando o certificado ou o nome do pacote não corresponde aos registros do Play, eUNEVALUATEDquando um pré-requisito foi ignorado. - deviceIntegrity — o dispositivo é genuíno? Por padrão, o
deviceRecognitionVerdictpode conterMEETS_DEVICE_INTEGRITY: um dispositivo Android genuíno e certificado, com comprovação em hardware no Android 13 e superior de que o bootloader está bloqueado e o software carregado é genuíno. Um dispositivo que não atende a nenhum rótulo simplesmente tem o campo omitido. - accountDetails — o usuário tem direito ao app? O
appLicensingVerdictretornaLICENSED(instalado ou atualizado pelo Google Play),UNLICENSEDouUNEVALUATED.
Dois pontos de disciplina importam mais do que a lista de campos. Primeiro, a Google afirma claramente que a API funciona melhor junto com outros sinais, como parte de uma estratégia geral antabuso e não como seu único mecanismo — um veredito é uma entrada, e tratá-lo como a única barreira gera tanto falsos positivos quanto burlas fáceis. Segundo, estes são sinais de risco, não julgamentos sobre seus usuários: um entusiasta em um dispositivo com root não é um criminoso, e a resposta deve ser proporcional ao que está realmente em jogo naquela tela.
2. Etapa 1 — ativar a API e vincular um projeto do Cloud
Todo app ou SDK que chama a API precisa de um projeto no Google Cloud, porque é lá que o uso é monitorado e a cota é gerenciada.
- No Google Cloud Console, crie um novo projeto ou escolha um existente que você queira usar.
- Acesse APIs e serviços → Ativar APIs e serviços, pesquise por Play Integrity API e clique em Ativar.
- Depois, vincule esse projeto ao seu app. No Play Console, abra seu app, vá em Protegido com o Play, encontre Play Integrity API e escolha Começar.
A vinculação é a etapa que destrava todo o resto. Um projeto habilitado no Cloud mas não vinculado no Play Console — ou no Play SDK Console, no caso de SDKs — não é elegível para as opções adicionais de configuração nem para um aumento de cota. O fluxo de vinculação habilita a API para você caso tenha pulado a etapa no console, então qualquer ordem funciona; pular a vinculação, não.
A descriptografia exige uma credencial que seu app nunca deve carregar. Crie uma conta de serviço dentro do projeto Cloud vinculado e chame o endpoint de decodificação a partir do seu servidor com o escopo playintegrity. O cliente pede tokens; só o servidor os abre.
3. Etapa 2 — escolha uma solicitação padrão ou clássica
Existem dois estilos de requisição, e escolher o certo logo de início evita uma reescrita depois.
- As solicitações padrão são a escolha padrão para apps no Google Play. Elas funcionam no Android 5.0 (nível de API 21) e superiores, e são construídas a partir de duas chamadas: prepare o provedor de token de integridade com antecedência e depois solicite um token quando você realmente precisar.
- Solicitações clássicas existem para os casos que as solicitações padrão não cobrem — principalmente apps distribuídos exclusivamente fora do Google Play e SDKs. Estruturalmente, uma solicitação clássica é uma única chamada que recebe um
nonceque você gera, e os apps que não são distribuídos no Play também precisam informar o número do projeto no Cloud comsetCloudProjectNumber(). Os apps no Play são vinculados pelo console e não definem isso na solicitação.
Se o seu app está no Google Play, a resposta é o standard. Opte pelo classic quando a distribuição realmente acontece fora do Play ou quando uma integração específica limita você.
4. Etapa 3 — aquecer o provedor e então solicitar o token
Uma solicitação padrão é deliberadamente dividida em duas para que a parte lenta nunca caia no caminho crítico do usuário.
Prepare, ou aqueça, o provedor de token de integridade. Chame isso bem antes de precisar de um veredito — normalmente na inicialização do app, o que funciona bem porque a chamada é assíncrona e não afeta o tempo de inicialização. O aquecimento permite que o Google Play armazene em cache informações parciais de atestação no dispositivo, para que a solicitação posterior seja rápida; preparar novamente também é uma forma mais leve de tornar o próximo veredito mais atual. O próprio provedor pode expirar se for mantido por muito tempo, o que aparece como INTEGRITY_TOKEN_PROVIDER_INVALID; trate isso solicitando um novo provedor em vez de repetir a chamada com o antigo.
Solicite um token de integridade sob demanda. Quando o app faz uma chamada ao servidor que você quer atestar, solicite um token e envie-o ao seu backend. Anexe um hash de solicitação: calcule um digest — SHA-256 dos parâmetros estáveis, por exemplo — e passe-o, porque a API devolve esse valor dentro da resposta assinada. Sem ele, o token fica vinculado ao dispositivo, mas não à solicitação específica, que é exatamente a brecha que um proxy precisa para reutilizá-lo em outra coisa.
As solicitações clássicas usam um nonce fornecido por você. Ele é repassado à Google sem alteração, então nunca inclua dados pessoais ou sensíveis nele, e ele precisa ser Base64 válido de um comprimento aceito — caso contrário, você recebe NONCE_TOO_SHORT, NONCE_TOO_LONG ou NONCE_IS_NOT_BASE64 em vez de um veredito.
5. Etapa 4 — descriptografe e verifique no seu servidor
O token que chega ao seu backend é criptografado e inútil até que o Google o descriptografe. Usando as credenciais da sua conta de serviço e o escopo playintegrity, seu servidor chama:
POST https://playintegrity.googleapis.com/v1/PACKAGE_NAME:decodeIntegrityToken { "integrity_token": "INTEGRITY_TOKEN" }
O que volta é um payload JSON em texto simples. Antes de olhar um único veredito, valide os detalhes da solicitação, porque o payload só faz sentido se for realmente a resposta à sua solicitação:
requestPackageNamedeve ser igual ao seu nome do pacote;requestHashprecisa ser igual ao hash que você enviou;timestampMillisdeve ser recente — compare-o com uma janela de atualidade (uma janela permitida de milissegundos) e rejeite qualquer coisa mais antiga, já que um token desatualizado é candidato a replay.
Google Play também aplica proteção automática contra replay, impedindo que um token de integridade seja reutilizado muitas vezes. Trate isso como uma rede de segurança, não como substituto da sua própria verificação de atualidade, e decodifique o token no servidor no momento da ação em vez de guardar um em cache por um dia.
6. Ler o payload sem bloquear em excesso
O payload é um JSON contendo requestDetails, appIntegrity, deviceIntegrity, accountDetails e — depois que você adere — environmentDetails. A ordem dos campos não é garantida, então sempre leia pela chave. Uma escada de decisão viável é esta.
- Confirme o app primeiro:
PLAY_RECOGNIZEDsignifica que o binário e o certificado são os que o Play distribui. - Depois, observe o dispositivo:
MEETS_DEVICE_INTEGRITYé o nível padrão. Os rótulos adicionais —MEETS_BASIC_INTEGRITY,MEETS_STRONG_INTEGRITYeMEETS_VIRTUAL_INTEGRITY— são opcionais e fazem parte de uma estratégia em camadas, não de um primeiro lançamento. - Use
accountDetailsonde os direitos importam:UNLICENSEDsignifica que a conta não tem direito ao Play, embora em alguns dispositivos mais antigos um direito possa persistir após a desinstalação, então leia isso como um sinal, não como um fato. - Se você ativou
environmentDetails, oappAccessRiskVerdictinforma se há apps capazes de capturar a tela ou desenhar sobreposições — a listaappsDetectedusa valores comoKNOWN_INSTALLED,UNKNOWN_INSTALLEDeUNKNOWN_CAPTURING— e o veredito do Play Protect resume o estado do Play Protect no dispositivo.
Dois casos nada óbvios merecem atenção de projeto. Emuladores que passam nas verificações de integridade do sistema e atendem aos requisitos centrais de compatibilidade do Android podem receber um rótulo de dispositivo próprio, então "emulador" não significa automaticamente "atacante". E um dispositivo que não atende a nenhum rótulo omite o campo por completo, o que faz o código que presume a chave sempre presente quebrar em vez de falhar de forma segura.
7. Cota, códigos de erro e falha segura
Por padrão, seu app pode fazer até 10.000 solicitações por dia em todas as instalações. Esse teto chega mais rápido do que as equipes esperam após um lançamento, então acompanhe o uso no projeto do Cloud vinculado e solicite um aumento enquanto a linha de tendência ainda deixa margem. Ultrapassá-lo aparece como TOO_MANY_REQUESTS (código de erro -8), que você absorve com backoff exponencial em vez de bloquear usuários.
O tratamento de erros é onde as integrações costumam falhar. Trate estes como transitórios e tente novamente com backoff: NETWORK_ERROR (-3), TOO_MANY_REQUESTS (-8), GOOGLE_SERVER_UNAVAILABLE (-12) e CLIENT_TRANSIENT_ERROR (-18). Os demais são ambientais — sem Play Store, sem Play services, versão desatualizada do Play services, conta do Play ausente, número de projeto do Cloud que a API rejeita. A orientação do Google nesses casos é tratar o resultado como se o cliente tivesse falhado nas verificações, mantendo a interação utilizável sempre que for razoavelmente possível.
Trate os erros como uma questão de política, não apenas como um caminho de código. Bloquear todos cujo dispositivo parece incomum transforma um sinal antiaabuso em um problema de retenção; ignorar silenciosamente toda falha é o erro oposto. Decida por superfície — um ranking pode ser permissivo, uma recarga de carteira pode ser rígida — e registre a decisão para que o próximo engenheiro herde o raciocínio.
O Google também oferece diálogos de correção: fluxos acionados pelo app e guiados pelo Google que ajudam um usuário legítimo a corrigir o problema de base, como instalar o build oficial do Play ou restaurar a conectividade, em vez de deixá-lo sem saída. E se você precisar identificar abuso reincidente do mesmo hardware após uma aplicação de políticas, o recurso de recall de dispositivo (beta) foi feito para isso.
8. Fazendo o lançamento sem quebrar seus usuários
Telemetria antes da aplicação de políticas. Registre os vereditos e sua distribuição por algumas semanas antes de restringir qualquer coisa, para saber a proporção real de resultados UNEVALUATED e UNLICENSED na sua própria base instalada, e não no blog de outra pessoa. Depois, aplique em camadas: primeiro o rótulo padrão do dispositivo, depois rótulos adicionais, e uma superfície por vez. Mantenha o cliente capaz de distinguir "tentar novamente" de "não", e garanta que o app degrade com elegância quando a API simplesmente não estiver disponível — um usuário em uma rede instável não deve perder o acesso a conteúdo que já pagou.
9. Onde o KappS se encaixa
KappS ajuda desenvolvedores a manter contas e lançamentos em um estado que resiste ao escrutínio das plataformas — preparando e enviando material em conformidade, nunca burlando verificações. Na prática, isso significa:
- Higiene de versão. Assinado com Play App Signing, enviado pelo canal oficial, códigos de versão e certificados consistentes com os registros que o Google Play reconhece — as condições sob as quais
PLAY_RECOGNIZEDé sequer possível. - Prontidão da conta. Verificação de identidade do desenvolvedor, perfil de pagamento e registros fiscais alinhados à identidade legal por trás da conta, para que um lançamento não fique travado por uma revisão não relacionada.
- Revisão da integração. Um segundo olhar sobre como o cliente solicita tokens, sobre o que o servidor usa como base e se o nível de aplicação corresponde ao risco do negócio.
Não oferecemos, e não vamos oferecer, contorno de integridade, falsificação de veredito ou ferramentas que escondam um build adulterado do Play. É exatamente isso que esta API existe para detectar, coloca a conta em risco e não é um serviço que prestamos. A única forma duradoura de passar numa verificação de integridade é ser o produto genuíno.
Fontes (Google documentação oficial): Play Integrity API — Visão geral; Configuração; Fazer uma solicitação padrão; Fazer uma solicitação clássica; Sobre os veredictos de integridade; Usar o recall de dispositivo; Tratar códigos de erro; Diálogos de correção (developer.android.com).
Gerencia contas de desenvolvedor em escala? Cuidamos do lado operacional.
Recebemos sua mensagem e responderemos em até 24 horas.
← Voltar para editar