将 reCAPTCHA Enterprise 与 Android 应用集成

本页介绍了如何在您的 Android 应用中集成 reCAPTCHA Enterprise。由于移动设备在屏幕尺寸、性能以及应用界面方面存在差异，视觉 reCAPTCHA 挑战（我不是机器人）不适用于移动应用。有关替代的摩擦方法，请参阅配置多重身份验证 (MFA)。

准备工作

  1. 选择在您的环境中设置 reCAPTCHA Enterprise 的最佳方法，并完成设置。

  2. reCAPTCHA Enterprise Android SDK 在经过安全审核后才能访问。请与我们的销售团队联系，在您的网站上启用此功能。

  3. 为 Android 应用平台创建 reCAPTCHA 密钥。

  4. 下载并安装最新版本的 Android Studio，以准备开发环境。

将 reCAPTCHA Enterprise 与 Android 应用集成

如需将 reCAPTCHA Enterprise 与您的 Android 应用集成，请执行以下操作：

  1. 通过启动新的 Android Studio 项目创建一个测试应用。创建项目时，请选择空活动，将语言设置为 Java，并将最低 SDK 设置为 API 16: Android 4.1 (Jelly Bean）。

  2. 确保 Google 的 Maven 代码库 google() 位于项目级层 build.gradle 文件的代码库列表中，如以下代码段所示：

    allprojects {
    repositories {
        google()
    }
}

    如需了解详情，请参阅 Google 的 Maven 存储库。

  3. 如需添加 reCAPTCHA Enterprise API 依赖项，请将以下构建规则添加到应用级层 build.gradle 文件的 dependencies 部分。

       implementation 'com.google.android.gms:play-services-recaptcha:17.0.1'

    如需详细了解 Android 应用中的 API 依赖项，请参阅设置 Google Play 服务。

  4. 在应用的清单文件（例如 AndroidManifest.xml）中的第一个 <manifest> 标记与第一个 <application> 标记之间添加互联网权限。您需要此权限，因为 reCAPTCHA Enterprise API 涉及网络操作。

    <manifest ...>

    <uses-permission android:name="android.permission.INTERNET" />

    <application ...>
    ...
  </application>
</manifest>

  5. 如果您想在新项目中使用 AndroidX 库，请将 SDK 编译为 Android 9.0 或更高版本，并将以下代码段添加到 gradle.properties。

    android.useAndroidX=true
android.enableJetifier=true

    如需了解详情，请参阅迁移至 AndroidX。

  6. 在您的应用 (MainActivity.java) 中，按以下顺序调用 init()、execute() 和 close() 方法，以调用 reCAPTCHA Enterprise API：

    1. 当您启动应用或包含您要保护的操作的 Activity 时，请调用 init()。
    2. 在您希望保护的操作完成后，请调用 execute()。例如，点击登录按钮后。然后，execute() 会返回 RecaptchaResultData 令牌。
    3. 如果没有要验证的操作，请调用 close()。

    在您的应用中调用这三种方法时，请替换 onSuccess() 和 onFailure() 方法以处理 API 调用的两种可能结果。具体来说，如果 API 将 ApiException的实例传入 onFailure()，您必须处理使用 getStatusCode() 可检索到的每个可能的状态代码。如需了解详情，请参阅处理通信错误。

以下示例代码段展示了如何调用 init()、execute() 和 close() 方法：

public final class MainActivity extends Activity {
   private RecaptchaHandle handle;

   @Override
   protected void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     setContentView(R.layout.activity_main);

     // Step 1: Call init() once the activity starts.
     Recaptcha.getClient(this)
         .init("YOUR_SITE_KEY")
         .addOnSuccessListener(
             this,
             new OnSuccessListener<RecaptchaHandle>() {
               @Override
               public void onSuccess(RecaptchaHandle handle) {
                 // Handle success ...
                 MainActivity.this.handle = handle;
               }
             })
         .addOnFailureListener(
             this,
             new OnFailureListener() {
               @Override
               public void onFailure(@NonNull Exception e) {
                 if (e instanceof ApiException) {
                   ApiException apiException = (ApiException) e;
                   Status apiErrorStatus = apiException.getStatusCode();
                   // Handle api errors ...
                 } else {
                   // Handle other failures ...
                 }
               }
             });
   }

   public void onClick(View v) {
     // Step 2: call execute() when there is an action to protect.
     Recaptcha.getClient(this)
         .execute(this.handle, new RecaptchaAction(new RecaptchaActionType(RecaptchaActionType.LOGIN)))
         .addOnSuccessListener(
             this,
             new OnSuccessListener<RecaptchaResultData>() {
               @Override
               public void onSuccess(RecaptchaResultData response) {
                 String token = response.getTokenResult();
                 // Handle success ...
                 if (!token.isEmpty()) {
                   Log.d(TAG, "reCAPTCHA response token: " + token);
                   // Validate the response token by following the instructions
                   // when creating an assessment.
                 }
               }
             })
         .addOnFailureListener(
             this,
             new OnFailureListener() {
               @Override
               public void onFailure(@NonNull Exception e) {
                 if (e instanceof ApiException) {
                   ApiException apiException = (ApiException) e;
                   Status apiErrorStatus = apiException.getStatusCode();
                   // Handle api errors ...
                 } else {
                   // Handle other failures ...
                 }
               }
             });
   }

  @Override
  protected void onDestroy() {
    // Step 3: call close() when there is no more action to verify.
   Recaptcha.getClient(this)
       .close(handle)
       .addOnSuccessListener(
           this,
           new OnSuccessListener<Boolean>() {
             @Override
             public void onSuccess(Boolean gotClosed) {
               // Handle success ...
             }
           })
       .addOnFailureListener(
           this,
           new OnFailureListener() {
             @Override
             public void onFailure(@NonNull Exception e) {
               if (e instanceof ApiException) {
                 ApiException apiException = (ApiException) e;
                 Status apiErrorStatus = apiException.getStatusCode();
                 // Handle api errors ...
               } else {
                 // Handle other failures ...
               }
             }
           });
  }
}

处理通信错误

如果您的应用无法成功与 reCAPTCHA 服务通信，则可能是因为 API 遇到了错误。您必须在应用中添加逻辑，以妥善处理此类错误。

如需详细了解常见 API 错误的缓解措施，请参阅 RecaptchaStatusCodes。

API 参考文档

如需 Android 版 reCAPTCHA API 的完整参考信息，请参阅 com.google.android.gms.recaptcha。

后续步骤