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
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:
|
|
| 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 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. 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. | ||
| Solicitações de token de integridade da 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
ocorrer porque:
|
||
| 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:
|
||
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:
|
|
| 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.