Como migrar da API SafetyNet Attestation

Se você já estiver verificando respostas usando um servidor confiável, a migração da API SafetyNet Attestation para a API Play Integrity será bem simples. A API Play Integrity também pode ser usada para substituir verificações de licenciamento de apps realizadas diretamente com o app da Play Store pela AIDL, como as realizadas pela biblioteca Licensing Verification (LVL, na sigla em inglês). A maioria das mudanças necessárias estará no servidor confiável, que precisa ler e analisar o token de resposta da integridade do Google Play. Durante a migração, tanto o aplicativo quanto o servidor precisam aceitar as duas APIs simultaneamente para oferecer suporte a clientes mais antigos que ainda não foram atualizados.

Se o app recebeu limites de cota maiores para a API SafetyNet Attestation, verifique o nível de uso atribuído à API Play Integrity e, se necessário, solicite a migração para o nível elevado.

As mudanças abaixo são necessárias para oferecer suporte à API Play Integrity:

Cliente Android:

  • Verifique se o código está transmitindo o valor de uso único formatado corretamente para o builder IntegrityTokenRequest:
    • String (em vez de uma matriz de bytes)
    • Seguro para URL
    • Codificado como Base64 e sem wrapper
    • Mínimo de 16 caracteres
    • Máximo de 500 caracteres
  • Revise a lógica de repetição e verifique se o aplicativo gerencia os erros corretamente.
  • Verifique se os dados de resposta enviados ao servidor confiável permitem distinguir entre as respostas da API SafetyNet Attestation e as respostas da API Play Integrity.

Servidor confiável:

  • Revise a lógica de geração de valor de uso único e verifique se ela atende aos requisitos da API Play Integrity.
  • Verifique se o código do servidor pode diferenciar as respostas da API SafetyNet Attestation e as respostas da API Play Integrity. Verifique se o código analisa e valida essas respostas corretamente.
  • Adicione lógica para validar e analisar as respostas da API Play Integrity.
  • Como a nova resposta da API Play Integrity fornece mais detalhes, pode ser necessário melhorar a lógica da tomada de decisões e os dados de feedback enviados para os dispositivos do cliente. Para mais informações, consulte a seção Mapeamento de resposta de API neste tópico.

Codificação de valor de uso único

Um valor de uso único relacionado à integridade precisa ser transmitido para a API Play Integrity como uma String de codificação Base64, segura para URL e sem wrapper. Esse formato é diferente da API SafetyNet Attestation, que exige byte[].

  • "Seguro para URL" significa usar a variante "URL e nome de arquivo seguros" de Base64 (consulte a seção 5 do RFC 4648), em que "-" e "_" são usados em vez de "+" e "/". Para mais informações sobre a codificação Base64, consulte o RFC 4648 (link em inglês).
  • "Sem wrapper" significa omitir todos os terminadores de linha. Isso significa que a saída é uma única linha longa.
.setNonce(Base64.encodeToString(NONCE_BYTES,
        Base64.URL_SAFE | Base64.NO_WRAP))

Além disso, verifique se a geração de valores de uso único está alinhada com as diretrizes da API Play Integrity.

Mapeamento de resposta de API

A tabela abaixo correlaciona os campos da API SafetyNet Attestation com os equivalentes da API Play Integrity.

API SafetyNet Attestation API Play Integrity Anotações
timestampMs requestDetails.timestampMillis
nonce requestDetails.nonce
apkPackageName appIntegrity.packageName
apkCertificateDigestSha256 appIntegrity.certificateSha256Digest Verifique se appRecognitionVerdict está definido como PLAY_RECOGNIZED
ctsProfileMatch Combinado com deviceIntegrity.deviceRecognitionVerdict
basicIntegrity Combinado com deviceIntegrity.deviceRecognitionVerdict
evaluationType Combinado com deviceIntegrity.deviceRecognitionVerdict
advice Not available
error Not available A lista de identificadores de integridade do dispositivo estará vazia.

Mapeamento de vereditos de integridade do dispositivo

API SafetyNet Attestation API Play Integrity
ctsProfileMatch basicIntegrity evaluationType deviceRecognitionVerdict
FALSE FALSE Sem identificadores
FALSE TRUE MEETS_BASIC_INTEGRITY
TRUE FALSE Sem identificadores
TRUE TRUE BASIC MEETS_DEVICE_INTEGRITY, MEETS_BASIC_INTEGRITY
TRUE TRUE HARDWARE_BACKED MEETS_STRONG_INTEGRITY, MEETS_DEVICE_INTEGRITY, MEETS_BASIC_INTEGRITY

Talvez seja necessário configurar o conjunto de respostas de integridade do dispositivo se o aplicativo usar uma estratégia de aplicação complexa e precisar de todos os valores possíveis.

Lógica de repetição da API Play Integrity

Um app precisa repetir chamadas de API no caso de determinados códigos de erro. Revise todos os códigos de erro e garanta que o aplicativo tente de novo após esses erros quando necessário com espera exponencial. Verifique se o atraso mínimo é de pelo menos cinco segundos, aumentando exponencialmente (5 s, 10 s, 20 s, 40 s e assim por diante), para fornecer à API tempo suficiente para avaliar a integridade do dispositivo e do aplicativo.

Substituição opcional da API App Licensing

Se você estiver usando a API App Licensing, como opção, poderá migrar para usar a API Play Integrity, porque um token da API Play Integrity inclui as informações de licenciamento do aplicativo. Assim como acontece com a migração da API SafetyNet Attestation, é esperado que vários dispositivos mantenham uma versão mais antiga do aplicativo. Seu servidor confiável precisa ser capaz de processar as respostas da API App Licensing e da API Play Integrity.

Receber respostas até a desativação completa

Se você ainda não migrou para a API Play Integrity nem removeu a SafetyNet Attestation até o prazo de migração (31 de janeiro de 2024), preencha este formulário (em inglês) para pedir uma extensão. Se for aprovado para uma extensão, seu app continuará recebendo respostas da SafetyNet Attestation até o prazo completo de desativação (31 de janeiro de 2025).