API SafetyNet Safe Browsing

A SafetyNet oferece serviços para determinar se um URL foi marcado como 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 de v4 do "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 do "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 SafetyNet 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

Para criar uma chave de API, siga as seguintes etapas:

  1. Acesse o Google Developers Console.
  2. Na barra de ferramentas superior, escolha Selecionar um projeto > nome-do-projeto.
  3. Na caixa de pesquisa, digite APIs Safe Browsing. Quando o nome da API Safe Browsing aparecer na tabela, selecione-o.
  4. Depois que a página for exibida novamente, selecione Ativar e, em seguida, selecione Acessar credenciais.
  5. Quando a janela Adicione credenciais a seu projeto for exibida, escolha seus parâmetros e selecione Preciso de quais credenciais?.
  6. Digite um nome para sua chave de API e selecione Criar chave de API.
  7. Sua nova chave de API será exibida. Copie e salve essa chave para uso futuro.

    Observação: sua chave de API permite que você realize verificações de URL 10.000 vezes por dia. A chave, nesse caso, será apenas uma string hexadecimal, e não parte de um URL.

  8. Selecione Concluir para encerrar o processo.

Se precisar de mais ajuda, consulte a Central de Ajuda do Google Developers Console.

Inicializar a API

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

Kotlin

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

Java

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

Observação: para minimizar o impacto da inicialização do seu app, chame initSafeBrowsing() o quanto antes no método onResume() da sua atividade.

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 representar riscos para seu app. A API permite que você escolha que tipos de ameaça são importantes para suas necessidades. Você pode especificar vários tipos de ameaça conhecidos.

Especificar tipos de ameaças

As constantes da classe SafeBrowsingThreat contêm os tipos de ameaça compatíveis atualmente:

    package com.google.android.gms.safetynet;

    public class SafeBrowsingThreat {

      /**
       * This threat type identifies URLs of pages that are flagged as containing potentially
       * harmful applications.
       */
      public static final int TYPE_POTENTIALLY_HARMFUL_APPLICATION = 4;

      /**
       * This threat type identifies URLs of pages that are flagged as containing social
       * engineering threats.
       */
      public static final int TYPE_SOCIAL_ENGINEERING = 5;
    }
    

Ao usar a API, use constantes que não foram marcadas como obsoletas. Adicione constantes de tipo de ameaça à API como argumentos. Você pode adicionar quantas constantes de tipo de ameaça seu app exigir.

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

Kotlin

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

Java

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

quanto

Kotlin

    var url = "www.google.com"
    

Java

    String url = "www.google.com";
    

são válidos.

Kotlin

    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}")
                }
            }
    

Java

    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. No entanto, se a lista não estiver vazia, chame getThreatType() em cada elemento da lista para determinar quais ameaças conhecidas a API detectou.

Encerrar sua sessão do Navegação segura

Se seu app não for usar a API Safe Browsing por um longo período, verifique todos os URLs necessários dentro do seu app e, em seguida, encerre a sessão do Navegação segura usando o método shutdownSafeBrowsing():

Kotlin

    SafetyNet.getClient(this).shutdownSafeBrowsing()
    

Java

    SafetyNet.getClient(this).shutdownSafeBrowsing();
    

Recomendamos que você chame shutdownSafeBrowsing() no método onPause() da sua atividade e initSafeBrowsing() no método onResume() da atividade. No entanto, é necessário que initSafeBrowsing() tenha concluído a execução antes de você chamar lookupUri(). Ao garantir que sua sessão esteja sempre atualizada, você ajudará a reduzir a ocorrência de erros internos no seu app.

Texto de alerta sugerido

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