SafetyNet Safe Browsing API

SafetyNet 会提供相应的服务，用于确定某个网址是否已被 Google 标记为已知威胁。

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

本文档介绍了如何使用 SafetyNet 来检查某个网址是否属于已知威胁。

服务条款

使用 Safe Browsing API 即表示您同意遵守服务条款。请先阅读并了解所有适用的条款及政策，然后再使用 Safe Browsing API。

请求并注册 Android API 密钥

如需创建 API 密钥，请按以下步骤操作：

转到 Google Developers Console。
在上方的工具栏中，依次选择选择项目 > your-project-name。
在搜索框中输入 Safe Browsing API；当 Safe Browsing API 名称出现在表格中时，选择该名称。
当页面重新显示后，选择启用，然后选择转到凭据。
当系统显示“向项目中添加凭据”窗口时，选择您的参数，然后选择我需要什么样的凭据？。
输入 API 密钥的名称，然后选择创建 API 密钥。
系统会显示您的新 API 密钥；复制并保存此密钥以供将来使用。

注意：您可以通过该 API 密钥每天执行 10000 次网址检查。在本例中，该密钥应该只是一个十六进制字符串，而不是某个网址的一部分。
选择完成以完成此过程。

如需更多帮助，请查看 Google Developers Console 帮助中心。

初始化 API

要使用 Safe Browsing API，您必须初始化 API，具体方法是调用 initSafeBrowsing() 并等待其完成。以下代码段提供了一个示例：

Kotlin

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

Java

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

注意：为了尽量减少应用初始化的影响，请尽早在 Activity 的 onResume() 方法中调用 initSafeBrowsing()。

请求检查网址

您的应用可以进行网址检查，以确定某个网址是否属于已知威胁。某些威胁类型可能与您的具体应用无关。您可以通过该 API 视需要选择哪些威胁类型是重要的。您可以指定多种已知的威胁类型。

指定相关威胁类型

SafeBrowsingThreat 类中的常量包含当前支持的威胁类型：

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

使用该 API 时，您必须使用未标记为弃用的常量。您可以将威胁类型常量作为参数添加到 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，请检查应用中的所有必要网址，然后使用 shutdownSafeBrowsing() 方法关闭安全浏览会话：

Kotlin

    SafetyNet.getClient(this).shutdownSafeBrowsing()

Java

    SafetyNet.getClient(this).shutdownSafeBrowsing();

我们建议您在 Activity 的 onPause() 方法中调用 shutdownSafeBrowsing()，在 Activity 的 onResume() 方法中调用 initSafeBrowsing()。不过，在调用 lookupUri() 之前，请确保 initSafeBrowsing() 已执行完毕。确保您的会话始终处于最新状态，这有助于减少应用中的内部错误。

建议的警告语言

如需查看建议的警告语言，请参阅 Safe Browsing API 开发者指南。