SafetyNet 安全浏览 API

SafetyNet 安全浏览 API 是由 Google Play 服务提供支持的库，可提供服务来确定某个网址是否已被 Google 标记为已知威胁。

您的应用可以使用此 API 来确定特定网址是否已被 Google 归类为已知威胁。SafetyNet 在内部实现了 Google 开发的 Safe Browsing 网络协议 v4 的客户端。客户端代码和 v4 网络协议的设计都旨在保护用户的隐私，并将电池和带宽消耗降至最低。使用此 API，您可以以最优化资源的方式，且无需实现其网络协议，即可充分利用 Android 上的 Google Safe Browsing 服务。

本文档介绍了如何使用 SafetyNet 安全浏览查找 API 来检查网址是否存在已知威胁。

服务条款

使用 Safe Browsing API，即表示您同意接受服务条款的约束。请在访问 Safe Browsing API 之前阅读并理解所有适用的条款和政策。

申请并注册 Android API 密钥

在使用 Safe Browsing API 之前，请创建并注册一个 Android API 密钥。有关具体步骤，请参阅关于开始使用 Safe Browsing 的页面。

添加 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 会话

如果您的应用在长时间内无需使用 Safe Browsing API，请检查应用中所有必要的网址，然后使用 shutdownSafeBrowsing() 方法关闭 Safe Browsing 会话

Kotlin

SafetyNet.getClient(this).shutdownSafeBrowsing()

Java

SafetyNet.getClient(this).shutdownSafeBrowsing();

我们建议您在 Activity 的 onPause() 方法中调用 shutdownSafeBrowsing()，并在 Activity 的 onResume() 方法中调用 initSafeBrowsing()。但是，请确保在调用 lookupUri() 之前，initSafeBrowsing() 已执行完毕。通过确保您的会话始终处于最新状态，您可以减少应用内部错误的发生可能性。