API SafetyNet Safe Browsing

A API SafetyNet Safe Browsing, uma biblioteca com tecnologia do Google Play Services, oferece serviços para determinar se um URL foi marcado como uma ameaça conhecida pelo Google.

Seu app pode usar essa API para determinar se um URL específico foi classificado pelo Google como ameaça conhecida. Internamente, a SafetyNet implementa um cliente para o protocolo de rede v4 da Navegação segura desenvolvido pelo Google. O código do cliente e o protocolo de rede v4 foram desenvolvidos para preservar a privacidade dos usuários e manter o consumo da bateria e da largura de banda em um nível mínimo. Use essa API para aproveitar ao máximo o serviço da Navegação segura do Google no Android da maneira mais otimizada possível para recursos e sem implementar o protocolo de rede.

Este documento explica como usar a API SafetyNet Safe Browsing Lookup para verificar se há ameaças conhecidas em um URL.

Termos de Serviço

Ao usar a API Safe Browsing, você aceita os Termos de Serviço. Leia e entenda todos os termos e políticas aplicáveis antes de acessar a API Safe Browsing.

Solicitar e registrar uma chave de API do Android

Antes de usar a API Safe Browsing, crie e registre uma chave de API para Android. Para etapas específicas, consulte a página sobre como usar a Navegação segura.

Adicionar a dependência da API SafetyNet

Antes de usar a API Safe Browsing, adicione a API SafetyNet ao seu projeto. Se você estiver usando o Android Studio, adicione essa dependência ao arquivo do Gradle no nível do app. Para mais informações, consulte Proteger-se contra ameaças de segurança com a SafetyNet.

Inicializar a API

Para usar a API Safe Browsing, você precisa inicializar a API chamando initSafeBrowsing() e esperar a conclusão do processo. O snippet de código abaixo mostra um exemplo:

Tasks.await(SafetyNet.getClient(this).initSafeBrowsing())

Tasks.await(SafetyNet.getClient(this).initSafeBrowsing());

Solicitar uma verificação de URL

Seu app pode usar uma verificação de URL para determinar se um URL representa uma ameaça conhecida. Alguns tipos de ameaça podem não ser relevantes para seu app. A API permite escolher quais tipos de ameaça são importantes para suas necessidades. Você pode especificar vários tipos de ameaça conhecidos.

Enviar a solicitação de verificação de URL

A API é independente do esquema usado, então você pode transmitir o URL com ou sem um esquema. Por exemplo, tanto

var url = "https://www.google.com"

String url = "https://www.google.com";

quanto

var url = "www.google.com"

String url = "www.google.com";

são válidos.

O código abaixo demonstra como enviar uma solicitação de verificação de URL:

SafetyNet.getClient(this).lookupUri(
       url,
       SAFE_BROWSING_API_KEY,
       SafeBrowsingThreat.TYPE_POTENTIALLY_HARMFUL_APPLICATION,
       SafeBrowsingThreat.TYPE_SOCIAL_ENGINEERING
)
       .addOnSuccessListener(this) { sbResponse ->
           // Indicates communication with the service was successful.
           // Identify any detected threats.
           if (sbResponse.detectedThreats.isEmpty()) {
               // No threats found.
           } else {
               // Threats found!
           }
       }
       .addOnFailureListener(this) { e: Exception ->
           if (e is ApiException) {
               // An error with the Google Play Services API contains some
               // additional details.
               Log.d(TAG, "Error: ${CommonStatusCodes.getStatusCodeString(e.statusCode)}")

               // Note: If the status code, s.statusCode,
               // is SafetyNetStatusCode.SAFE_BROWSING_API_NOT_INITIALIZED,
               // you need to call initSafeBrowsing(). It means either you
               // haven't called initSafeBrowsing() before or that it needs
               // to be called again due to an internal error.
           } else {
               // A different, unknown type of error occurred.
               Log.d(TAG, "Error: ${e.message}")
           }
       }

SafetyNet.getClient(this).lookupUri(url,
         SAFE_BROWSING_API_KEY,
         SafeBrowsingThreat.TYPE_POTENTIALLY_HARMFUL_APPLICATION,
         SafeBrowsingThreat.TYPE_SOCIAL_ENGINEERING)
   .addOnSuccessListener(this,
       new OnSuccessListener<SafetyNetApi.SafeBrowsingResponse>() {
           @Override
           public void onSuccess(SafetyNetApi.SafeBrowsingResponse sbResponse) {
               // Indicates communication with the service was successful.
               // Identify any detected threats.
               if (sbResponse.getDetectedThreats().isEmpty()) {
                   // No threats found.
               } else {
                   // Threats found!
               }
        }
   })
   .addOnFailureListener(this, new OnFailureListener() {
           @Override
           public void onFailure(@NonNull Exception e) {
               // An error occurred while communicating with the service.
               if (e instanceof ApiException) {
                   // An error with the Google Play Services API contains some
                   // additional details.
                   ApiException apiException = (ApiException) e;
                   Log.d(TAG, "Error: " + CommonStatusCodes
                       .getStatusCodeString(apiException.getStatusCode()));

                   // Note: If the status code, apiException.getStatusCode(),
                   // is SafetyNetStatusCode.SAFE_BROWSING_API_NOT_INITIALIZED,
                   // you need to call initSafeBrowsing(). It means either you
                   // haven't called initSafeBrowsing() before or that it needs
                   // to be called again due to an internal error.
               } else {
                   // A different, unknown type of error occurred.
                   Log.d(TAG, "Error: " + e.getMessage());
               }
           }
   });

Ler a resposta de verificação de URL

Usando o objeto SafetyNetApi.SafeBrowsingResponse retornado, chame o método getDetectedThreats(), que retorna uma lista de objetos SafeBrowsingThreat. Se a lista retornada estiver vazia, isso significa que a API não detectou nenhuma ameaça conhecida. Se a lista não estiver vazia, chame getThreatType() em cada elemento da lista para determinar quais ameaças conhecidas a API detectou.

Para conferir o texto de alerta sugerido, consulte o Guia da API Safe Browsing para desenvolvedores.

Especificar tipos de ameaças

As constantes da classe SafeBrowsingThreat contêm os tipos de ameaça atualmente com suporte:

Ao usar a API, você adiciona constantes de tipo de ameaça como argumentos. Você pode adicionar quantas constantes de tipo de ameaça o app exigir, mas só é possível usar constantes que não estejam marcadas como descontinuadas.

Encerrar sua sessão de Navegação segura

Se o app não precisar usar a API Safe Browsing por um período prolongado, verifique todos os URLs necessários no app e encerre a sessão de Navegação segura usando o método shutdownSafeBrowsing():

SafetyNet.getClient(this).shutdownSafeBrowsing()

SafetyNet.getClient(this).shutdownSafeBrowsing();

Recomendamos que você chame shutdownSafeBrowsing() no método onPause() e initSafeBrowsing() no método onResume() da atividade. No entanto, confira se a execução de initSafeBrowsing() terminou antes de chamar lookupUri(). Ao garantir que sua sessão esteja sempre atualizada, você reduz a possibilidade de erros internos no app.

Dados coletados pela API SafetyNet Safe Browsing

A API SafetyNet Safe Browsing coleta os dados abaixo automaticamente quando se comunica com esse serviço no Android:

Nosso objetivo é oferecer o máximo de transparência possível, mas você é o único responsável por decidir como responder ao formulário da seção "Segurança dos dados" do Google Play com relação à coleta, ao compartilhamento e às práticas de segurança dos dados do usuário do seu app.