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á direta. A API Play Integrity também pode ser usada para substituir verificações de licenciamento de apps realizadas diretamente com o app Play Store por meio da 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.

Os apps que receberam limites de cota maiores para a API SafetyNet Attestation, que também são qualificados para um uso maior da API Play Integrity, serão automaticamente colocados no nível "Raised". para cobrir os custos.

As seguintes mudanças 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 requer 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 a RFC 4648.
  • "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 a seguir 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 rótulos de integridade do dispositivo estará vazia.

Mapeamento de resultados de integridade do dispositivo

API SafetyNet Attestation API Play Integrity
ctsProfileMatch basicIntegrity evaluationType device_recognition_verdict
FALSE FALSE Empty labels
FALSE TRUE MEETS_BASIC_INTEGRITY
TRUE FALSE Empty labels
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. Certifique-se de revisar todos os códigos de erro e garantir que o aplicativo tente novamente 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, poderá migrar opcionalmente 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.