SafetyNet reCAPTCHA API

SafetyNet 服务包含一个 reCAPTCHA API，您可以使用它来保护您的应用程序免受恶意流量的影响。

reCAPTCHA 是一项免费服务，它使用先进的风险分析引擎来保护您的应用程序免受垃圾邮件和其他滥用行为的影响。如果该服务怀疑与您的应用程序交互的用户可能是机器人而不是人类，它会提供一个 CAPTCHA，人类必须在您的应用程序继续执行之前解决。

本文档说明了如何将 SafetyNet 中的 reCAPTCHA API 集成到您的应用程序中。

其他服务条款

通过访问或使用 reCAPTCHA API，您同意 Google API 服务条款 和以下 reCAPTCHA 服务条款。在访问 API 之前，请阅读并了解所有适用的条款和政策。

注册 reCAPTCHA 密钥对

要注册用于 SafetyNet reCAPTCHA API 的密钥对，请导航到 reCAPTCHA Android 注册网站，然后完成以下步骤序列

1. 在出现的表单中，提供以下信息

   • 标签：您的密钥的唯一标签。通常，您使用公司的名称或组织的名称。
   • reCAPTCHA 类型：选择 reCAPTCHA v2，然后选择 reCAPTCHA Android。
   • 软件包： 提供每个使用此 API 密钥的应用程序的软件包名称。 为了让应用程序使用 API，您输入的软件包名称必须与应用程序的软件包名称完全匹配。 将每个软件包名称单独放在一行上。
   • 所有者： 添加组织中每个监控应用程序 reCAPTCHA 评估的个人的电子邮件地址。

2. 选中接受 reCAPTCHA 服务条款复选框。

3. 向所有者发送警报： 如果您希望收到有关 reCAPTCHA API 的电子邮件，请选择此复选框，然后单击提交。

4. 在出现的下一页上，您的公钥和私钥分别显示在网站密钥和私钥下。 您在发送验证请求时使用网站密钥，并在验证用户响应令牌时使用私钥。

添加 SafetyNet API 依赖项

在使用 reCAPTCHA API 之前，请将 SafetyNet API 添加到您的项目中。 如果您使用的是 Android Studio，请将此依赖项添加到您的应用程序级 Gradle 文件中。 有关更多信息，请参阅SafetyNet API 设置。

使用 reCAPTCHA API

本部分介绍如何调用 reCAPTCHA API 来发送 CAPTCHA 验证请求并接收用户响应令牌。

发送验证请求

要调用 SafetyNet reCAPTCHA API，您需要调用verifyWithRecaptcha()方法。 通常，此方法对应于用户在您的活动中选择 UI 元素（例如按钮）。

在您的应用程序中使用verifyWithRecaptcha()方法时，您必须执行以下操作：

• 将您的 API 网站密钥作为参数传入。
• 覆盖onSuccess()和onFailure()方法以处理验证请求任务的两种可能结果。 特别是，如果 API 将ApiException的实例传入onFailure()，则需要处理使用getStatusCode()可以检索到的每个可能的状态代码。

以下代码片段展示了如何调用此方法

fun onClick(view: View) {
    SafetyNet.getClient(this).verifyWithRecaptcha(YOUR_API_SITE_KEY)
            .addOnSuccessListener(this as Executor, OnSuccessListener { response ->
                // Indicates communication with reCAPTCHA service was
                // successful.
                val userResponseToken = response.tokenResult
                if (response.tokenResult?.isNotEmpty() == true) {
                    // Validate the user response token using the
                    // reCAPTCHA siteverify API.
                }
            })
            .addOnFailureListener(this as Executor, OnFailureListener { e ->
                if (e is ApiException) {
                    // An error occurred when communicating with the
                    // reCAPTCHA service. Refer to the status code to
                    // handle the error appropriately.
                    Log.d(TAG, "Error: ${CommonStatusCodes.getStatusCodeString(e.statusCode)}")
                } else {
                    // A different, unknown type of error occurred.
                    Log.d(TAG, "Error: ${e.message}")
                }
            })
}

public void onClick(View v) {
    SafetyNet.getClient(this).verifyWithRecaptcha(YOUR_API_SITE_KEY)
        .addOnSuccessListener((Executor) this,
            new OnSuccessListener<SafetyNetApi.RecaptchaTokenResponse>() {
                @Override
                public void onSuccess(SafetyNetApi.RecaptchaTokenResponse response) {
                    // Indicates communication with reCAPTCHA service was
                    // successful.
                    String userResponseToken = response.getTokenResult();
                    if (!userResponseToken.isEmpty()) {
                        // Validate the user response token using the
                        // reCAPTCHA siteverify API.
                    }
                }
        })
        .addOnFailureListener((Executor) this, new OnFailureListener() {
                @Override
                public void onFailure(@NonNull Exception e) {
                    if (e instanceof ApiException) {
                        // An error occurred when communicating with the
                        // reCAPTCHA service. Refer to the status code to
                        // handle the error appropriately.
                        ApiException apiException = (ApiException) e;
                        int statusCode = apiException.getStatusCode();
                        Log.d(TAG, "Error: " + CommonStatusCodes
                                .getStatusCodeString(statusCode));
                    } else {
                        // A different, unknown type of error occurred.
                        Log.d(TAG, "Error: " + e.getMessage());
                    }
                }
        });
}

验证用户响应令牌

当 reCAPTCHA API 执行onSuccess()方法时，用户已成功完成 CAPTCHA 挑战。 但是，此方法仅表明用户已正确解决了 CAPTCHA。 您仍然需要从您的后端服务器验证用户的响应令牌。

要了解如何验证用户的响应令牌，请参阅验证用户的响应。