此页面由 Cloud Translation API 翻译。

将 reCAPTCHA Enterprise 与 Android 应用集成

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

准备工作

选择在您的环境中设置 reCAPTCHA Enterprise 的最佳方法，并完成设置。
reCAPTCHA Enterprise Android SDK 在经过安全审核后才能访问。请与我们的销售团队联系，在您的网站上启用此功能。

注意：Google Play 商店要求您填写 Google Play 的数据安全表单，然后才能将应用上传到 Play 商店。查看 Google Play 的数据披露要求，了解填写数据安全表单所需的 reCAPTCHA Enterprise Android SDK 相关信息。
为 Android 应用平台创建 reCAPTCHA 密钥。
下载并安装最新版本的 Android Studio，以准备开发环境。

将 reCAPTCHA Enterprise 与 Android 应用集成

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

通过启动新的 Android Studio 项目创建一个测试应用。创建项目时，请选择空活动，将语言设置为 Java，并将最低 SDK 设置为 API 16: Android 4.1 (Jelly Bean）。
确保 Google 的 Maven 代码库 google() 位于项目级层 build.gradle 文件的代码库列表中，如以下代码段所示：
```
allprojects {
    repositories {
        google()
    }
}
```
如需了解详情，请参阅 Google 的 Maven 存储库。
如需添加 reCAPTCHA Enterprise API 依赖项，请将以下构建规则添加到应用级层 build.gradle 文件的 dependencies 部分。
```
   implementation 'com.google.android.gms:play-services-recaptcha:17.0.1'
```
如需详细了解 Android 应用中的 API 依赖项，请参阅设置 Google Play 服务。
在应用的清单文件（例如 AndroidManifest.xml）中的第一个 <manifest> 标记与第一个 <application> 标记之间添加互联网权限。您需要此权限，因为 reCAPTCHA Enterprise API 涉及网络操作。
```
<manifest ...>

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

    <application ...>
    ...
  </application>
</manifest>
```
如果您想在新项目中使用 AndroidX 库，请将 SDK 编译为 Android 9.0 或更高版本，并将以下代码段添加到 gradle.properties。
```
android.useAndroidX=true
android.enableJetifier=true
```
如需了解详情，请参阅迁移至 AndroidX。
在您的应用 (MainActivity.java) 中，按以下顺序调用 init()、execute() 和 close() 方法，以调用 reCAPTCHA Enterprise API：

注意：每次 API 调用都使用 Recaptcha.getClient(this)，而不是维持对 RecaptchaClient 的引用。
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。

后续步骤

要评估 reCAPTCHA 响应令牌，请创建评估。