Configuração

Esta página explica como configurar seu app ou jogo para usar a API Play Integrity. É necessário ativar as respostas da API e integrá-la ao app e ao servidor de back-end dele. Outras opções de configuração, recursos de teste e relatórios ficam disponíveis depois que você vincula o projeto do Google Cloud que está usando para a API Play Integrity no Google Play Console.

Ativar as respostas da API Play Integrity

Todo app ou SDK que chama a API Play Integrity precisa usar um projeto do Google Cloud para monitorar o uso da API. Os apps no Google Play podem vincular um projeto do Google Cloud no Google Play Console para ativar as respostas da API Play Integrity. Se você quiser criar um novo projeto do Google 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.

Configurar no Google Play Console (recomendado)

Ao ativar as respostas da API Play Integrity no Google Play Console, você terá acesso a outras opções de configuração, recursos de teste e relatórios da API. Essa opção está disponível apenas para apps distribuídos no Google Play. Navegue até Versão > Integridade do app. Em API Play Integrity, selecione Vincular um projeto do Cloud. Escolha o projeto do Cloud que você quer vincular ao app. Isso vai ativar as respostas da API Play Integrity. Agora você pode integrar a API Play Integrity ao app.

Configurar no console do Google Cloud

No console do Google Cloud, crie um novo projeto do Cloud ou escolha um projeto existente que você queira usar com a API Play Integrity. Navegue até APIs e serviços. Selecione Ativar APIs e serviços. Pesquise API Play Integrity e ative-a. Agora você pode integrar a API Play Integrity ao app.

Configurar instruções para provedores de SDK

Os provedores de SDK precisam usar o próprio projeto do Google Cloud para chamar a API Play Integrity para que o uso dela seja atribuído ao SDK, e não a apps individuais que usam o SDK. Isso significa que os apps que usam seu SDK não precisam configurar a API Play Integrity individualmente. As solicitações para a API Play Integrity são contabilizadas automaticamente no uso da API no SDK, e não no app.

Os desenvolvedores de SDKs têm duas opções para configurar a API Play Integrity: o Google Play SDK Console ou o console do Google Cloud.

Ao ativar as respostas da API Play Integrity no Google Play SDK Console, você tem acesso a outras opções de configuração. Navegue até Integridade do SDK e clique em Configurações. Em "Configuração do projeto", selecione Vincular um projeto do Cloud. Escolha o projeto do Cloud que você quer vincular ao SDK. Isso vai ativar as respostas da API Play Integrity. Agora você pode integrar a API Play Integrity ao SDK. O acesso ao Google Play SDK Console está sujeito a critérios de qualificação.

Usar o console do Google Cloud

É possível ativar as respostas da API Play Integrity no console do Google Cloud. No console do Google Cloud, crie um novo projeto do Cloud ou escolha um projeto existente que você queira usar com a API Play Integrity. Navegue até APIs e serviços. Selecione Ativar APIs e serviços. Pesquise API Play Integrity e ative-a. Agora você pode integrar a API Play Integrity ao SDK.

Aumentar o número diário de solicitações da API Play Integrity no seu SDK

Os provedores de SDK que quiserem aumentar o número máximo de solicitações diárias vão precisar preencher o formulário de solicitação de cota. Na seção de comentários abertos, especifique que você está fazendo uma solicitação para o SDK e inclua suas coordenadas do Maven (groupId:artifactId) ou um URL para o SDK em questão.

Aumentar o número diário de solicitações 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 seguindo as instruções abaixo.

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. Mesmo com um aumento no limite máximo, continue a limitar as solicitações clássicas por usuário a ações pouco frequentes e de alto valor para preservar os dados do usuário e a bateria do dispositivo.

Para pedir um aumento no número máximo diário de solicitações, faça o seguinte:

  1. Vincule o projeto do Google Cloud que você está usando para a API Play Integrity no Play Console.
  2. Verifique se você está implementando a lógica da API corretamente, incluindo a estratégia de repetição recomendada.
  3. 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 de solicitações clássicas serão aplicados automaticamente a chamadas de clientes para gerar tokens de integridade e a chamadas do servidor para descriptografar e verificar tokens de integridade. Os aumentos de cota de solicitações padrão serão aplicados a chamadas do servidor para descriptografar e verificar tokens de integridade.

Integrar a API Play Integrity ao app

Para integrar a API Play Integrity ao app ou SDK, siga um dos procedimentos abaixo, dependendo do ambiente de desenvolvimento usado:

Kotlin ou Java

A biblioteca Android mais recente da API Play Integrity está disponível no Repositório Maven do Google. Adicione a dependência abaixo ao arquivo build.gradle do seu app:

implementation 'com.google.android.play:integrity:1.4.0'

Unity

Instale o Plug-in da API Play Integrity para Unity 1.3.0 ou mais recente. Para instruções, consulte como instalar pacotes do Google para Unity.

  • Todas as versões 2019.x, 2020.x e mais recentes têm suporte.
  • Se você usar o Unity 2018.x, há suporte para a versão 2018.4 ou mais recente.
  • O Unity 2017.x e versões anteriores não têm suporte.

Nativo

Instale o SDK nativo da Play Core 1.13.0 ou mais recente. Para instruções, consulte o guia de configuração do ambiente de desenvolvimento do SDK nativo da Play Core.

Configurar respostas da API (opcional)

A resposta da API inclui vereditos padrão retornados em cada solicitação. Se você configurar a integração da API Play Integrity no Play Console, poderá personalizar a resposta da API.

Respostas padrão

Os vereditos de integridade abaixo são retornados na resposta da API Play Integrity por padrão:

Campo de resposta Valor 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.
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 (como um emulador rejeitado pelas verificações de integridade do Google Play).
Detalhes da conta do Google Play 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 está ausente. Isso pode acontecer por vários motivos, incluindo:
  • O dispositivo não é confiável o suficiente.
  • O usuário não está conectado ao Google Play.
  • A versão do app instalada no dispositivo é desconhecida para o Google Play.
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.

Respostas condicionais

Se você distribuir o app para o Google Play Games para PC, o recebimento de um identificador extra no veredito de integridade do dispositivo será ativado automaticamente:

Campo de resposta Identificador Descrição
Integridade do dispositivo MEETS_VIRTUAL_INTEGRITY O app está sendo executado em um emulador Android com o Google Play Services. O emulador foi aprovado nas verificações de integridade do sistema e atende aos principais requisitos de compatibilidade do Android.

Respostas opcionais

Se você configurar a integração da API Play Integrity no Play Console ou no Play SDK Console, poderá ativar o recebimento de informações na resposta da API.

Para fazer mudanças nas suas respostas de API, acesse o Play Console e navegue até Versão > Integridade do app. Em Respostas, edite e salve as mudanças.

Informações opcionais do dispositivo

Apps e SDKs podem ativar outros identificadores no veredito de integridade do dispositivo. Depois que você aceita receber outros identificadores, a resposta de integridade passa a incluir vários identificadores do mesmo dispositivo, desde que sejam atendidos os critérios de cada um. 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 três identificadores (MEETS_STRONG_INTEGRITY, MEETS_DEVICE_INTEGRITY e MEETS_BASIC_INTEGRITY) pode ser mais confiável que um dispositivo que retorna apenas um (MEETS_BASIC_INTEGRITY).

Você também pode ativar a atividade recente do dispositivo. A atividade recente do dispositivo retorna um nível que varia de LEVEL_1 (baixo número de solicitações) a LEVEL_4 (alto número de solicitações). Por exemplo, um dispositivo que retorna um nível de atividade significativamente maior do que o normal para seu app pode estar tentando gerar um grande número de tokens de integridade para distribuição a dispositivos não confiáveis.

Campo de resposta Identificador 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 com a tecnologia do Google Play Services e tem uma forte garantia de integridade do sistema, como uma prova de integridade da inicialização protegida por hardware. O dispositivo é aprovado nas verificações de integridade do sistema e atende aos requisitos de compatibilidade do Android.
Atividade recente do dispositivo Solicitações de token de integridade de API padrão neste dispositivo na última hora por app Solicitações clássicas de token de integridade da API neste dispositivo na última hora por app
LEVEL_1 (mais baixo) 10 ou menos 5 ou menos
LEVEL_2 Entre 11 e 25 Entre 6 e 10
LEVEL_3 Entre 26 e 50 Entre 11 e 15
LEVEL_4 (mais alta) Mais de 50 Mais de 15
UNEVALUATED A atividade recente do dispositivo não foi avaliada. Isso pode acontecer porque:
  • O dispositivo não é confiável o suficiente.
  • A versão do app instalada no dispositivo é desconhecida para o Google Play.
  • Houve problemas técnicos no dispositivo.

Detalhes opcionais do ambiente

Os apps podem aceitar receber outros vereditos sobre o ambiente. O risco de acesso a apps informa se outros apps estão em execução e podem capturar a tela, mostrar sobreposições ou controlar o dispositivo. O veredito do Play Protect informa se ele está ativado no dispositivo e se encontrou malware conhecido.

Depois de ativar o recebimento desses vereditos, a resposta da API vai incluir o campo de detalhes do ambiente com o veredito:

Campo de resposta Valor Descrição
Veredito de risco de acesso ao app KNOWN_INSTALLED Os apps são instalados pelo Google Play ou pré-carregados na partição do sistema pelo fabricante do dispositivo.
KNOWN_CAPTURING Apps instalados pelo Google Play ou pré-carregados no dispositivo estão em execução e podem ser usados para ler ou capturar entradas e saídas do app solicitante. Por exemplo, apps de gravação de tela.
KNOWN_CONTROLLING Os apps instalados pelo Google Play ou pré-carregados no dispositivo estão em execução e podem ser usados para controlar o dispositivo e as entradas e saídas do app solicitante. Por exemplo, apps de controle remoto.
KNOWN_OVERLAYS Apps instalados pelo Google Play ou pré-carregados no dispositivo estão em execução e podem estar mostrando sobreposições no app solicitante.
UNKNOWN_INSTALLED Outros apps estão instalados e não foram instalados pelo Google Play ou pré-carregados na partição do sistema pelo fabricante do dispositivo.
UNKNOWN_CAPTURING Outros apps estão em execução (não instalados pelo Google Play ou pré-carregados no dispositivo) que podem ser usados para ler ou capturar entradas e saídas do app solicitante, como apps de gravação de tela.
UNKNOWN_CONTROLLING Outros apps estão em execução (não instalados pelo Google Play nem pré-carregados no dispositivo) e podem ser usados para controlar o dispositivo e as entradas e saídas do app solicitante. Por exemplo, apps de controle remoto.
UNKNOWN_OVERLAYS Outros apps estão em execução (não instalados pelo Google Play nem pré-carregados no dispositivo) e podem estar mostrando sobreposições no app solicitante.
EMPTY (um valor em branco) O indicador de risco de acesso a apps não é avaliado se um requisito necessário estiver ausente. Nesse caso, o campo appAccessRiskVerdict está vazio. Isso pode acontecer por vários motivos, incluindo:
  • O dispositivo não é confiável o suficiente.
  • O formato do dispositivo não é um smartphone, tablet ou dobrável.
  • O dispositivo não está executando o Android 6 (nível 23 da API) ou mais recente.
  • A versão do app instalada no dispositivo é desconhecida para o Google Play.
  • A versão da Google Play Store no dispositivo está desatualizada.
  • Somente para jogos: a conta de usuário não tem uma licença do Google Play para o jogo.
  • Uma solicitação padrão foi usada com o parâmetro verdictOptOut.
  • Uma solicitação padrão foi usada com uma versão da biblioteca da API Play Integrity que ainda não oferece suporte ao indicador de risco de acesso a apps para solicitações padrão.
Veredito do Play Protect NO_ISSUES O Play Protect está ativado e não encontrou problemas de apps no dispositivo.
NO_DATA O Play Protect está ativado, mas nenhuma verificação foi realizada ainda. O dispositivo ou o app da Play Store pode ter sido redefinido recentemente.
POSSIBLE_RISK O Play Protect está desativado.
MEDIUM_RISK O Play Protect está ativado e encontrou apps potencialmente nocivos instalados no dispositivo.
HIGH_RISK O Play Protect está ativado e encontrou apps perigosos instalados no dispositivo.
UNEVALUATED O veredito do Play Protect não foi avaliado. Um requisito necessário está ausente, por exemplo, o dispositivo não é confiável o suficiente.

Definir as configurações de solicitações clássicas (opcional)

Pule esta seção se você quiser fazer apenas solicitações de API padrão.

Ao fazer solicitações clássicas, por padrão, os servidores do Google Play gerenciam a criptografia de resposta que o app usa ao interagir com a API Play Integrity. Recomendamos que você use essa opção padrão, mas também é possível gerenciar e fazer o download das chaves de criptografia de resposta seguindo as instruções abaixo.

Permitir que o Google gerencie sua criptografia de resposta (padrão e recomendado)

Para proteger a segurança do app, é recomendável permitir que o Google gere e gerencie as chaves de criptografia de resposta. O servidor de back-end vai chamar o servidor do Google Play para descriptografar as respostas.

Gerenciar e fazer o download das minhas próprias chaves de criptografia de resposta

Se você quiser descriptografar o veredito de integridade localmente no próprio ambiente de servidor seguro, poderá gerenciar e fazer o download das chaves de criptografia de resposta. Para gerenciar e fazer o download das chaves de criptografia de resposta, use o Play Console. Além disso, seu app precisa estar disponível no Google Play e em outros canais de distribuição. Siga as instruções abaixo para mudar de chaves de criptografia de resposta gerenciadas pelo Google para autogerenciadas.

Lembre-se de não descriptografar ou verificar o token recebido no app cliente e de nunca expor nenhuma chave de descriptografia ao app cliente.

Antes de mudar sua estratégia de gerenciamento de criptografia de resposta no Play Console, verifique se o servidor está configurado corretamente para descriptografar e verificar os tokens de integridade nos servidores do Google Play para evitar interrupções.

Alternar entre chaves de criptografia de resposta gerenciadas pelo Google e autogerenciadas

Se atualmente o Google gerencia sua criptografia de resposta e você quer passar a gerenciar e fazer o download das chaves de criptografia de resposta por conta própria, siga estas etapas:

  1. Faça login no Play Console.
  2. Selecione um app que usa a API Play Integrity.
  3. Na seção Versão do menu à esquerda, acesse Integridade do app.
  4. Ao lado de API Play Integrity, clique em Configurações.
  5. Na seção Solicitações clássicas da página, ao lado de Criptografia de resposta, clique em Editar.
  6. Na janela que aparecer, clique em Gerenciar e fazer o download das minhas próprias chaves de criptografia de resposta.
  7. Siga as instruções para fazer upload de uma chave pública.
  8. Após a janela mostrar que o upload foi concluído, clique em Salvar e o download das chaves de API criptografadas vai ser iniciado automaticamente.
  9. Mude a lógica do servidor para descriptografar e verificar os tokens de integridade localmente no seu próprio ambiente de servidor seguro usando as chaves de criptografia de resposta.
  10. Opcional - quando você gerencia suas chaves de criptografia de resposta por conta própria, o app ainda pode acessar o servidor do Google Play para descriptografar e verificar a resposta.

Se você gerencia suas próprias chaves de criptografia de resposta e quiser que o Google passe a fazer isso por você, siga estas etapas:

  1. Mude a lógica do servidor para passar a descriptografar e verificar somente nos servidores do Google.
  2. Faça login no Play Console.
  3. Selecione um app que usa a API Play Integrity.
  4. Na seção Versão do menu à esquerda, acesse Integridade do app.
  5. Ao lado de API Play Integrity, clique em Configurações.
  6. Na seção Solicitações clássicas da página, ao lado de Criptografia de resposta, clique em Editar.
  7. Na janela mostrada, clique em Permitir que o Google gerencie minhas chaves de criptografia de resposta (recomendado).
  8. Clique em Salvar alterações.