将 reCAPTCHA Enterprise 与 Android 应用集成

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

准备工作

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

  2. 进行安全审核后,可访问 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:16.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

后续步骤