Novidade:ative os vereditos mais fortes da API Play Integrity em dispositivos com o Android 13 ou versões mais recentes. Saiba mais sobre as mudanças futuras que vão melhorar a segurança, o desempenho e a privacidade.

Esta página foi traduzida pela API Cloud Translation.

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.

Usar o Google Play SDK Console (recomendado)

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:

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 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

As seções a seguir descrevem como integrar e configurar a API Google Play Integrity para projetos do Unity, cobrindo as versões do Unity com suporte, os métodos de instalação e a configuração do ambiente.

Versões do Unity com suporte

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.

Configurar seu ambiente de desenvolvimento

OpenUPM-CLI

Se você tiver a CLI do OpenUPM instalada, poderá instalar o registro do OpenUPM com o seguinte comando:

openupm add com.google.play.integrity

OpenUPM

Abra as configurações do gerenciador de pacotes selecionando a opção de menu do Unity Edit > Project Settings > Package Manager.

Adicione o OpenUPM como um registro de escopo à janela do Gerenciador de pacotes:

Name: package.openupm.com
URL: https://package.openupm.com
Scopes: com.google.external-dependency-manager
  com.google.play.common
  com.google.play.core
  com.google.play.integrity

Abra o menu do gerenciador de pacotes selecionando a opção de menu do Unity Window > Package Manager.
Defina o menu suspenso "Escopo do administrador" para selecionar Meus registros.
Selecione o pacote Google Play Integrity plugin for Unity na lista de pacotes e pressione Install.

Importar do GitHub

Faça o download da versão mais recente do .unitypackage no GitHub.
Importe o arquivo .unitypackage selecionando a opção de menu do Unity Assets > Import package > Custom Package e importando todos os itens.

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 de dispositivo 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 rótulos (MEETS_STRONG_INTEGRITY, MEETS_DEVICE_INTEGRITY e MEETS_BASIC_INTEGRITY) pode ser mais confiável do 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.

Você também pode ativar os atributos do dispositivo, que informam a versão do SDK do Android OS em execução no dispositivo. No futuro, ele poderá ser estendido com outros atributos de dispositivo.

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 e, para dispositivos com Android 13 ou mais recente, exige o atestado de chave da plataforma Android. 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, uma inicialização não verificada ou não ter sido certificado pelo fabricante.
	`MEETS_STRONG_INTEGRITY`	O app está sendo executado em um dispositivo Android com o Google Play Services e tem uma forte garantia de integridade do sistema, como uma prova de integridade da inicialização protegida por hardware. Para dispositivos com Android 13 ou mais recente, é necessário ter uma atualização de segurança no último ano. O dispositivo é aprovado nas verificações de integridade do sistema e atende aos requisitos de compatibilidade do Android.
		Solicitações de token de integridade de API padrão neste dispositivo na última hora por app	Solicitações de token de integridade de API clássicas neste dispositivo na última hora por app
Atividade recente do dispositivo	`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.
Atributos do dispositivo	`sdkVersion: 19, 20, ..., 35`	A versão do SDK do SO Android em execução no dispositivo. O número retornado é mapeado para `Build.VERSION_CODES`.
	Vazio (um valor em branco)	A versão do SDK não é avaliada porque um requisito necessário está ausente. Nesse caso, o campo `sdkVersion` não está definido. Portanto, o campo `deviceAttributes` está vazio. 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 o Play Protect está ativado no dispositivo e se ele 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`	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 nem pré-carregados no dispositivo) e podem ser usados para ler ou capturar entradas e saídas do app solicitante. Por exemplo, 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.
	Vazio (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:

Faça login no Play Console.
Selecione um app que usa a API Play Integrity.
Na seção Versão do menu à esquerda, acesse Integridade do app.
Ao lado de API Play Integrity, clique em Configurações.
Na seção Solicitações clássicas da página, ao lado de Criptografia de resposta, clique em Editar.
Na janela que aparecer, clique em Gerenciar e fazer o download das minhas próprias chaves de criptografia de resposta.
Siga as instruções para fazer upload de uma chave pública.
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.
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.
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:

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

Visão geral

Fazer uma solicitação padrão