Interfejs API Bezpieczne przeglądanie w ramach SafetyNet

SafetyNet Safe Browsing API to biblioteka oparta na Usługach Google Play, która umożliwia sprawdzanie, czy adres URL został oznaczony przez Google jako znane zagrożenie.

Twoja aplikacja może używać tego interfejsu API, aby sprawdzić, czy dany adres URL został sklasyfikowany przez Google jako znane zagrożenie. Wewnętrznie SafetyNet implementuje klienta protokołu Bezpiecznego przeglądania sieci w wersji 4 opracowanego przez Google. Zarówno kod klienta, jak i protokół sieciowy v4 zostały zaprojektowane tak, aby chronić prywatność użytkowników i minimalizować zużycie baterii oraz przepustowości. Użyj tego interfejsu API, aby w pełni wykorzystać usługę Bezpieczne przeglądanie Google na Androidzie w sposób najbardziej zoptymalizowany pod kątem zasobów i bez implementowania protokołu sieciowego.

Nowa aktualizacja wersji 5 (v5) wprowadza znaczące ulepszenia w zakresie aktualności danych i prywatności dzięki zastosowaniu Oblivious HTTP.

Z tego dokumentu dowiesz się, jak używać interfejsu SafetyNet Safe Browsing Lookup API do sprawdzania adresów URL pod kątem znanych zagrożeń.

Warunki korzystania z usługi

Korzystając z interfejsu Safe Browsing API, wyrażasz zgodę na przestrzeganie Warunków korzystania z usługi. Zanim uzyskasz dostęp do interfejsu Bezpieczne przeglądanie API, przeczytaj i zrozum wszystkie obowiązujące warunki i zasady.

Żądanie i rejestrowanie klucza interfejsu Android API

Zanim zaczniesz korzystać z interfejsu Safe Browsing API, utwórz i zarejestruj klucz interfejsu Android API. Szczegółowe instrukcje znajdziesz na stronie Pierwsze kroki z Bezpiecznym przeglądaniem.

W wersji 5 ten klucz interfejsu API podajesz podczas tworzenia instancji SafeBrowsingClient.

Dodawanie zależności od interfejsu SafetyNet API

Zanim zaczniesz korzystać z interfejsu Bezpieczne przeglądanie API, dodaj do projektu interfejs SafetyNet API. Jeśli używasz Android Studio, dodaj tę zależność do pliku Gradle na poziomie aplikacji. Więcej informacji znajdziesz w artykule Ochrona przed zagrożeniami bezpieczeństwa za pomocą SafetyNet.

Inicjowanie interfejsu API

Aby korzystać z interfejsu Safe Browsing API, musisz go zainicjować, wywołując initSafeBrowsing i czekając na zakończenie. Poniższy fragment kodu zawiera przykład:

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

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

W wersji 5 GmsCore udostępnia klienta Bezpiecznego przeglądania. Musisz uzyskać instancję SafeBrowsingClient. Uprościliśmy interfejs API, aby zwiększyć wydajność i zmniejszyć rozmiar.

// Draft interface for the new client
public interface SafeBrowsingClient extends HasApiKey<SafeBrowsingApiOptions> {
  Task<SafeBrowsingResponse> lookupUri(String uri, @ThreatType List<Integer> threatTypes, @Protocol int protocol);
  Task<SupportedThreatTypesResponse> getSupportedThreatTypes();
}

Żądanie sprawdzenia adresu URL

Użyj metody lookupUri, aby sprawdzić, czy identyfikator URI stanowi zagrożenie. Musisz określić zamierzony protokół, którym może być lokalna lista zablokowanych (wersja 4) lub ochrona w czasie rzeczywistym (wersja 5) .

Wysyłanie żądania sprawdzenia adresu URL

Interfejs API jest niezależny od używanego schematu, więc możesz przekazać adres URL ze schematem lub bez niego. Na przykład oba te adresy są prawidłowe:

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

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

i

var url = "www.google.com"

String url = "www.google.com";

Poniższy kod pokazuje, jak wysłać żądanie sprawdzenia adresu 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());
               }
           }
   });

Zaktualizowana sygnatura lookupUri przyjmuje identyfikator URI, listę typów zagrożeń i protokół.

val threatTypes = listOf(ThreatType.TYPE_SOCIAL_ENGINEERING, ThreatType.TYPE_MALWARE)
val protocol = Protocol.REAL_TIME // or Protocol.LOCAL_BLOCK_LIST

safeBrowsingClient.lookupUri(url, threatTypes, protocol)
    .addOnSuccessListener { response ->
        if (response.detectedThreats.isEmpty()) {
            // No threats found
        } else {
            // Threats detected!
        }
    }

Odczytywanie odpowiedzi na żądanie sprawdzenia adresu URL

Używając zwróconego SafetyNetApi.SafeBrowsingResponse obiektu, wywołaj jego getDetectedThreats metodę, która zwraca listę SafeBrowsingThreat obiektów. Jeśli zwrócona lista jest pusta, interfejs API nie wykrył żadnych znanych zagrożeń. Jeśli lista nie jest pusta, wywołaj getThreatType dla każdego elementu na liście, aby określić, które znane zagrożenia wykrył interfejs API.

Sugerowane ostrzeżenia znajdziesz w Przewodniku dla programistów korzystających z interfejsu Safe Browsing API.

Określanie typów zagrożeń, które Cię interesują

Stałe w klasie SafeBrowsingThreat zawierają obecnie obsługiwane typy zagrożeń:

Podczas korzystania z interfejsu API dodajesz stałe typu zagrożenia jako argumenty. Możesz dodać tyle stałych typu zagrożenia, ile wymaga Twoja aplikacja, ale możesz używać tylko stałych, które nie są oznaczone jako wycofane.

Wyłączanie sesji Bezpiecznego przeglądania

Jeśli Twoja aplikacja nie musi używać interfejsu Safe Browsing API przez dłuższy czas, sprawdź wszystkie niezbędne adresy URL w aplikacji, a następnie wyłącz sesję Bezpiecznego przeglądania za pomocą shutdownSafeBrowsing metody:

SafetyNet.getClient(this).shutdownSafeBrowsing()

SafetyNet.getClient(this).shutdownSafeBrowsing();

Zalecamy wywołanie shutdownSafeBrowsing w metodzie onPause aktywności oraz wywołanie initSafeBrowsing w metodzie onResume aktywności. Zanim wywołasz lookupUri upewnij się jednak, że initSafeBrowsing zakończyło działanie przed wywołaniem Dzięki temu, że sesja jest zawsze aktualna, zmniejszasz prawdopodobieństwo wystąpienia błędów wewnętrznych w aplikacji.

Szczegóły ochrony w czasie rzeczywistym

Aktualizacja do wersji 5 wprowadza tryb ochrony w czasie rzeczywistym , który eliminuje problemy z nieaktualnymi danymi (w wersji 4 mogły one sięgać 20–50 minut). Przechodzi z protokołu domyślnie dozwolonego na protokół domyślnie sprawdzany , co zwiększa ochronę przed szybko rozprzestrzeniającymi się zagrożeniami. W trybie rzeczywistym klienci utrzymują lokalną bazę danych i globalną pamięć podręczną prawdopodobnie bezpiecznych witryn, aby zapewnić ochronę w czasie rzeczywistym z najnowszymi danymi o zagrożeniach.

Obsługiwane typy zagrożeń

Interfejs API umożliwia wybranie typów zagrożeń, które są dla Ciebie ważne. Interfejs API w wersji 5 obsługuje szerszy zakres typów zagrożeń:

Dane zbierane przez SafetyNet Safe Browsing API

SafetyNet Safe Browsing API automatycznie zbiera te dane, gdy komunikuje się z usługą Bezpieczne przeglądanie na Androidzie:

SafetyNet Safe Browsing API zbiera prefiks skrótu adresów URL w celu wykrywania złośliwych adresów URL. Wersja 5 implementuje Oblivious HTTP , aby dodatkowo chronić dane użytkowników podczas tych wyszukiwań.

Dążymy do prezentowania informacji w jak najbardziej przejrzysty sposób. Jednak jako deweloper aplikacji ponosisz wyłączną odpowiedzialność za decyzje związane z sekcją Bezpieczeństwo danych w formularzu Google Play dotyczące zbierania, udostępniania i zabezpieczania danych użytkowników przez Twoją aplikację.