Você pode usar a API Play Integrity para proteger apps e jogos contra interações arriscadas. Ao identificar essas interações, o app pode responder adequadamente para reduzir o risco de ataques e abuso.
Como funciona
A API Integrity unifica os recursos contra abuso do Google Play com uma coleção de indicadores de integridade para ajudar os desenvolvedores de apps e jogos Android a detectar tráfego potencialmente arriscado e fraudulento. Esse tráfego pode ser proveniente de versões modificadas do seu app ou jogo, de dispositivos não confiáveis ou de outros ambientes não confiáveis. Ao detectar esse tráfego, é possível responder com a ação adequada para reduzir ataques e abusos, como em casos de fraude, trapaça e acesso não autorizado.
Quando um usuário realiza uma ação definida pelo app ou jogo, o servidor instrui o código do lado do cliente a invocar a API Integrity. O servidor do Google Play retorna uma resposta criptografada com um veredito de integridade informando se você pode confiar neste dispositivo e no binário dele. O app encaminha essa resposta ao servidor para verificação. O servidor pode decidir o que o app ou jogo fará a seguir.
A API fornece um veredito de integridade em uma resposta que inclui as seguintes informações:
- Integridade do aplicativo: informa se você está interagindo com seu binário não modificado reconhecido pelo Google Play.
- Detalhes da conta: informa se a conta de usuário atual é licenciada, o que significa que o usuário comprou ou instalou o app ou jogo no Google Play.
- Integridade do dispositivo: informa se o app está sendo executado em um dispositivo Android genuíno com o Google Play Services.
Dica: a API Integrity tem um melhor resultado quando você segue todas as práticas recomendadas na documentação do site para desenvolvedores Android.
Configurar e gerenciar a API Play Integrity
Ativar a API Integrity para seu app
Para ativar as respostas da API Integrity para seu app, é necessário vincular um projeto do Google Cloud ao Play Console. Para vincular o projeto, siga estas etapas:
- Abra o Play Console e acesse a página Integridade do app (Versão > Configuração > Integridade do app).
- Clique na guia API Integrity.
- Escolha "Vincular projeto existente" e o projeto a que você quer vincular ou clique em "Criar novo projeto".
- Clique em Vincular projeto.
Para começar a integrar a API Integrity ao app, faça o seguinte:
- Para apps em Java/Kotlin, instale a biblioteca Android mais recente disponível para a API Play Integrity no repositório Maven do Google.
- Para jogos do Unity, instale a versão mais recente dos plug-ins do Google Play para Unity. Todas as versões 2019.x, 2020.x e mais recentes são compatíveis. Se você usar a Unity 2018.x, instale a versão 2018.4 ou mais recente. Caso use a Unity 2017.x, instale a versão 2017.4.40 ou mais recente. As versões Unity 5.x e mais antigas não são compatíveis.
- Para apps e jogos nativos, instale o SDK nativo do Play Core mais recente.
Siga estas etapas no site para desenvolvedores Android para começar a usar a API Play Integrity no seu app ou jogo.
(Opcional) Escolher como a criptografia de resposta é gerenciada
Por padrão, o Google gerencia sua criptografia de resposta, mas você tem a opção de fazer isso por conta própria.
Importante: alternar entre a criptografia de resposta gerenciada pelo Google e autogerenciada exige alterações de código no servidor de back-end.
Para gerenciar por conta própria a criptografia de resposta, faça o seguinte:
- Abra o Play Console e acesse a página Integridade do app (Versão > Configuração > Integridade do app).
- Clique na guia API Integrity.
- Role a tela até a seção "Configurações".
- Ao lado de "Criptografia de resposta", o status será "Gerenciadas pelo Google" por padrão. Clique em Alterar.
- Escolha "Gerenciar e fazer o download das minhas próprias chaves de criptografia de resposta." e clique em Salvar alterações. O Google gera chaves de criptografia de resposta para você fazer o download e gerenciar. É preciso atualizar a lógica do servidor de back-end para descriptografar as respostas com as chaves.
- Siga as instruções na tela para gerar um arquivo .pem e faça upload dele para fazer o download das chaves de API.
- Uma mensagem na tela confirmará que o gerenciamento da criptografia de resposta foi atualizado.
- Faça o download das novas chaves de criptografia de resposta e atualize o servidor de back-end para descriptografar as respostas com elas na produção. Volte à guia API Integrity na página Integridade do app para permitir que o Google Play comece a usar as novas chaves de criptografia de resposta em vez das chaves legadas. Essa mudança é imediata.
Se quiser reverter da opção autogerenciada para a gerenciada pelo Google, siga estas etapas:
- Abra o Play Console e acesse a página Integridade do app (Versão > Configuração > Integridade do app).
- Clique na guia API Integrity.
- Role a tela até a seção "Configurações".
- Ao lado de "Criptografia de resposta", o status será "Autogerenciada", porque foi alterado anteriormente. Clique em Alterar.
- Escolha "Permitir que o Google gerencie minhas chaves de criptografia de resposta (recomendado)." e clique em Salvar alterações. O Google criará e gerenciará as chaves de criptografia de resposta. O servidor de back-end chamará o servidor do Google Play para descriptografar as respostas.
(Opcional) Configurar respostas da API Integrity
As respostas da API a seguir são configuradas por padrão:
| Resposta da API | Rótulo | Descrição |
| Integridade do dispositivo | MEETS_DEVICE_INTEGRITY |
O app está sendo executado em um dispositivo Android com o Google Play Services e o dispositivo é aprovado nas verificações de integridade do sistema e atende aos requisitos de compatibilidade do Android. |
| Nenhum rótulo (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 (como um emulador rejeitado pelas verificações de integridade do Google Play). |
|
| Detalhes da conta | LICENSED |
O usuário tem titularidade do app. Em outras palavras, o usuário instalou ou comprou seu app no 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 estes:
|
|
| Integridade do aplicativo | PLAY_RECOGNIZED |
O app e o certificado correspondem às versões distribuídas pelo Google Play. |
UNRECOGNIZED_VERSION |
O nome do certificado ou do pacote não corresponde aos registros do Google Play. |
|
UNEVALUATED |
A integridade do aplicativo não foi avaliada. Um requisito necessário está ausente, por exemplo, o dispositivo não é confiável o suficiente. |
Também é possível ativar o recebimento das seguintes respostas de API:
| Resposta da API | Rótulo | Descrição |
| Integridade do dispositivo | MEETS_BASIC_INTEGRITY |
O app está sendo executado em um dispositivo que é aprovado nas verificações básicas de integridade do sistema. O dispositivo pode não atender aos requisitos de compatibilidade do Android e não ser aprovado para executar o Google Play Services. Por exemplo, o dispositivo pode estar executando uma versão não reconhecida do Android, ter um carregador de inicialização desbloqueado ou não ter sido certificado pelo fabricante. |
MEETS_STRONG_INTEGRITY |
O app está sendo executado em um dispositivo Android que usa o Google Play Services e tem uma forte garantia de integridade do sistema, como um keystore protegido por hardware. O dispositivo é aprovado nas verificações de integridade do sistema e atende aos requisitos de compatibilidade do Android. |
Depois que você aceita receber outros identificadores, a resposta de integridade passa a incluir vários identificadores do mesmo dispositivo, desde que os critérios de cada identificador sejam atendidos. Assim você pode preparar seu servidor de back-end para se comportar de maneira diferente dependendo do intervalo de respostas possíveis. Por exemplo, um dispositivo que retorna MEETS_BASIC_INTEGRITY, MEETS_DEVICE_INTEGRITY e MEETS_STRONG_INTEGRITY pode ser mais confiável do que um dispositivo que retorna somente MEETS_BASIC_INTEGRITY. Você pode adaptar o servidor para responder de acordo com isso.
Para editar suas respostas da API, faça o seguinte:
- Abra o Play Console e acesse a página Integridade do app (Versão > Configuração > Integridade do app).
- Clique na guia API Integrity.
- Role a tela até a seção "Respostas".
- Clique em Editar.
- Marque ou desmarque as caixas de seleção ao lado das respostas de API que você quer mudar.
- Clique em Salvar alterações.
Importante: as mudanças nas respostas da API entrarão em vigor imediatamente após serem salvas, inclusive quando seu app estiver em produção. Antes de mudar o conjunto de respostas da API no Play Console, confira se o servidor está preparado para aceitar essas respostas.
Monitorar o uso da API Play Integrity e mudar o nível
Os apps estão sujeitos a um número máximo de solicitações por dia para a API com base no nível de uso do app. Os apps no nível Padrão podem fazer até 10.000 solicitações por dia para a API Integrity.
Para ver o nível de uso do app, siga estas etapas:
- Abra o Play Console e acesse a página Integridade do app (Versão > Configuração > Integridade do app).
- Clique na guia API Integrity.
- Role a tela até a seção "Configurações".
- Veja o nível de uso.
Para ver o volume de solicitações diárias do app, confira o projeto do Cloud vinculado no Console do Google Cloud.
Você pode exceder 10.000 solicitações por dia ao mudar o nível de uso do app para Elevado. Para se qualificar para o nível Elevado, é preciso fazer o seguinte:
- Confirmar a implementação correta da lógica da API, incluindo novas tentativas
- Publicar o app no Google Play, além de em outros canais de distribuição
Para mudar o nível de uso do app, preencha este formulário.
Testar a integração da API Play Integrity
Você pode configurar uma lista de contas do Gmail para testar a integração da API Integrity. Primeiro confira se os testadores têm acesso à sua versão:
- Publique o app na faixa de teste interno ou na faixa em que você pretende fazer o teste. Em seguida, siga as instruções para gerenciar testadores por endereço de e-mail ou use os Grupos do Google. Assim os testadores poderão acessar sua versão.
Para configurar um teste, siga estas etapas:
- Abra o Play Console e acesse a página Integridade do app (Versão > Configuração > Integridade do app).
- Clique na guia API Integrity.
- Role a tela até a seção "Teste".
- Clique em Criar novo teste.
- Selecione uma lista de e-mails ou crie uma nova.
- Clique em Criar teste.
Configurar a exclusão de dispositivos no Google Play
É possível excluir dispositivos da distribuição do seu app no Google Play com base na resposta da API Integrity enviada à Play Store. Os dispositivos excluídos não poderão ver nem instalar seu app no Google Play. A exclusão do dispositivo não impede que os usuários acessem o app de outra forma, por exemplo, por outro canal de distribuição ou por sideload.
Importante: a exclusão de dispositivos usa uma resposta da API Integrity recebida pelo app Play Store. Ela não está relacionada à resposta recebida pelo seu app após a integração da API.
Existem três opções de exclusão de dispositivos na API Integrity:
- Não excluir: não exclui dispositivos com base na API Integrity.
- Excluir somente falhas básicas: exclui dispositivos não confiáveis que não atendem aos critérios básicos de integridade.
- Excluir todos os dispositivos com problemas de integridade e sem certificação do Google: exclui dispositivos não confiáveis que não atendem aos critérios de integridade do dispositivo.
Dica: consulte as definições de integridade básica e integridade do dispositivo na documentação da API Play Integrity no site para desenvolvedores Android.
Veja como mudar a configuração de exclusão de dispositivos no Play Console:
- Abra o Play Console e acesse a página Integridade do app (Versão > Configuração > Integridade do app).
- Clique na guia API Integrity.
- Ao lado de "Exclusão de dispositivos", escolha se você quer excluir dispositivos da distribuição do seu app com base na resposta da API Integrity. Os dispositivos excluídos não poderão ver nem instalar seu app no Google Play.
- Salve as mudanças.
Importante: essa ação atualizará automaticamente as regras de exclusão do catálogo de dispositivos.