SafetyNet Safe Browsing API

SafetyNet Safe Browsing API 是採用 Google Play 服務的程式庫，可用於判斷網址是否標示為 Google 已知的威脅。

應用程式可以使用這個 API，判斷 Google 是否已將特定網址歸類為已知的威脅。SafetyNet 會在內部，為 Google 開發的安全瀏覽網路通訊協定第 4 版實作用戶端。用戶端程式碼和第 4 版網路通訊協定都是為了保護使用者隱私而設計，還可將電池和頻寬的消耗量降到最低。只要使用此 API，就能以最有效率的方式調度資源，充分運用 Android 上的 Google 安全瀏覽服務，而且不必實作其網路通訊協定。

本文說明如何使用 SafetyNet Safe Browsing Lookup API，檢查網址是否含有已知威脅。

服務條款

使用 Safe Browsing API，即表示您同意遵守《服務條款》。存取 Safe Browsing API 前，請先詳閱並瞭解所有適用的條款和政策。

要求及註冊 Android API 金鑰

使用 Safe Browsing API 前，請建立並註冊 Android API 金鑰。具體步驟請參閱「開始使用安全瀏覽」頁面。

新增 SafetyNet API 依附元件

使用 Safe Browsing API 前，請先在專案中新增 SafetyNet API。如果您使用的是 Android Studio，請將這個依附元件新增至應用程式層級的 Gradle 檔案。詳情請參閱「透過 SafetyNet 防範安全威脅」一文。

初始化 API

如要使用 Safe Browsing API，您必須呼叫 initSafeBrowsing() 並等待其作業完成，藉此初始化 API。以下程式碼片段提供了初始化示例：

Kotlin

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

Java

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

要求網址檢查

應用程式可透過網址檢查，判斷網址是否存在已知的威脅。某些威脅類型可能與您的特定應用程式無關。您可以使用此　API，視需要選擇您認為重要的威脅類型。您可以指定多個已知的威脅類型。

傳送網址檢查要求

此 API 與所使用的配置無關，因此您可以傳送包含/不包含配置的網址。例如：

Kotlin

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

Java

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

和

Kotlin

var url = "www.google.com"

Java

String url = "www.google.com";

都是有效的網址。

下列程式碼示範如何傳送網址檢查要求：

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());
               }
           }
   });

讀取網址檢查回應

請使用傳回的 SafetyNetApi.SafeBrowsingResponse 物件，呼叫其 getDetectedThreats() 方法，以傳回 SafeBrowsingThreat 物件清單。如果傳回的清單沒有任何內容，表示 API 沒有偵測到任何已知威脅。如果清單並非空白，請對清單中的每個元素呼叫 getThreatType()，判斷 API 偵測到哪些已知威脅。

如要查看建議的警告語言，請參閱 Safe Browsing API 開發人員指南。

指定相關的威脅類型

SafeBrowsingThreat 類別中的常數包含目前支援的威脅類型：

威脅類型	定義
`TYPE_POTENTIALLY_HARMFUL_APPLICATION`	此威脅類型會辨識遭標記為含有可能有害應用程式的網頁網址。
`TYPE_SOCIAL_ENGINEERING`	此威脅類型會辨識遭標記為含有社交工程威脅的網頁網址。

使用此 API 時，您可以新增威脅類型常數做為引數。您可以視應用程式需求新增多個威脅類型常數，但只能使用未標示為已淘汰的常數。

關閉安全瀏覽工作階段

如果您的應用程式不需要長時間使用 Safe Browsing API，請檢查應用程式中所有必要網址，然後使用 shutdownSafeBrowsing() 方法關閉安全瀏覽工作階段：

Kotlin

SafetyNet.getClient(this).shutdownSafeBrowsing()

Java

SafetyNet.getClient(this).shutdownSafeBrowsing();

建議您在活動的 onPause() 方法中呼叫 shutdownSafeBrowsing()，並在活動的 onResume() 方法中呼叫 initSafeBrowsing()。不過，請先確認 initSafeBrowsing() 已執行完畢，再呼叫 lookupUri()。請確保工作階段會持續更新，降低應用程式發生內部錯誤的可能性。

SafetyNet Safe Browsing API 收集的資料

當 SafetyNet Safe Browsing API 與 Android 的安全瀏覽服務通訊時，會自動收集以下資料：

資料	說明
應用程式活動	在本機雜湊前置字串相符後，收集網址雜湊前置字串，用於偵測惡意網址。

雖然我們力求盡可能維持透明公開，但您必須全權決定如何回覆 Google Play 資料安全性專區中針對應用程式的資料收集、分享和安全性做法的表單。