此页面由 Cloud Translation API 翻译。

将 reCAPTCHA Enterprise 与 Android 应用集成

本页介绍了如何在 Android 应用中集成 reCAPTCHA Enterprise。由于移动设备在屏幕尺寸、性能和界面方面的差异，移动设备的视觉复选框 reCAPTCHA 验证（我不是机器人）不适用于移动应用。您可以改为实施自己的分层强制执行策略（如 MFA 流程），为可疑流量提供备选兑换路径。

准备工作

选择在环境中设置 reCAPTCHA Enterprise 的最佳方法并完成设置。
为 Android 应用平台创建 reCAPTCHA 密钥。

准备环境

下载并安装最新版本的 Android Studio，以准备开发环境。
确保您有一个应用的最低 Android SDK 值设为 API 19: Android 4.4 (KitKat)。您可以将应用的最低 SDK 设置为 API 19，也可以创建新的移动应用。
如果要创建新的移动应用，请启动新的 Android Studio 项目来创建测试应用：
1. 选择 Empty Activity。如果您要在应用中使用 Jetpack Compose，请选择 Empty Compose Activity。
2. 将语言设置为 kotlin。
3. 将最低 SDK 值设置为 API 19: Android 4.4 (KitKat)。
确保 Google 的 Maven 代码库 google() 位于项目级 build.gradle 文件的代码库列表中，如以下代码段所示：
```
allprojects {
    repositories {
        google()
    }
}
```
如需了解详情，请参阅 Google 的 Maven 代码库。
如需添加 reCAPTCHA Enterprise API 依赖项，请将以下构建规则添加到应用级层 build.gradle 文件的 dependencies 部分。
```
   implementation 'com.google.android.recaptcha:recaptcha:18.1.1'
```
如需详细了解如何在 Android 应用中添加依赖项，请参阅添加 build 依赖项。
在应用清单中的第一个 <manifest> 标记和第一个 <application> 标记之间添加互联网权限（例如 AndroidManifest.xml）。此权限是必需的，因为 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。

将 reCAPTCHA Enterprise 与 Android 应用集成

使用您为 Android 应用创建的 SITE_KEY 来实例化客户端。

Kotlin

class MainActivity : AppCompatActivity() {

    private lateinit var recaptchaClient: RecaptchaClient

    override fun onCreate(savedInstanceState: Bundle?) {
      super.onCreate(savedInstanceState)
      setContentView(R.layout.activity_main)
      initializeRecaptchaClient()
      // ... rest of onCreate code
    }

    private fun initializeRecaptchaClient() {
      lifecycleScope.launch {
        Recaptcha.getClient(application, "YOUR_SITE_KEY")
          .onSuccess { client ->
            recaptchaClient = client
          }
          .onFailure { exception ->
            // Handle communication errors ...
            // See "Handle communication errors" section
          }
      }
    }

    // ... rest of activity code.
}

Java

public final class MainActivity extends Activity {
  @Nullable private RecaptchaTasksClient recaptchaTasksClient = null;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    initializeRecaptchaClient();
    // ... rest of onCreate code
  }

  private void initializeRecaptchaClient() {
    Recaptcha
      .getTasksClient(getApplication(), "YOUR_SITE_KEY")
      .addOnSuccessListener(
          this,
          new OnSuccessListener<RecaptchaTasksClient>() {
            @Override
            public void onSuccess(RecaptchaTasksClient client) {
              MainActivity.this.recaptchaTasksClient = client;
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle communication errors ...
              // See "Handle communication errors" section
            }
          });
  }

  // ... rest of activity code.
}

对于使用 reCAPTCHA Enterprise 保护的应用的每项操作，请调用 execute 方法以传递 RecaptchaAction。reCAPTCHA Enterprise 提供了一组内置操作，如有必要，您可以创建自定义操作。

以下代码段展示了如何使用 execute 保护 LOGIN 操作。

Kotlin

private fun executeLoginAction() {
  lifecycleScope.launch {
    recaptchaClient
      .execute(RecaptchaAction.LOGIN)
      .onSuccess { token ->
        // Handle success ...
        // See "What's next" section for instructions
        // about handling tokens.
      }
      .onFailure { exception ->
        // Handle communication errors ...
        // See "Handle communication errors" section
      }
  }
}

Java

private void executeLoginAction(View v) {
  assert recaptchaTasksClient != null;
  recaptchaTasksClient
    .executeTask(RecaptchaAction.LOGIN)
    .addOnSuccessListener(
        this,
        new OnSuccessListener<String>() {
          @Override
          public void onSuccess(String token) {
            // Handle success ...
            // See "What's next" section for instructions
            // about handling tokens.
          }
        })
    .addOnFailureListener(
        this,
        new OnFailureListener() {
          @Override
          public void onFailure(@NonNull Exception e) {
            // Handle communication errors ...
            // See "Handle communication errors" section
          }
        });
}

以下示例代码段显示了单个 Activity 应用中的 getClient() 和 execute() 方法的完全集成：

Kotlin

class MainActivity : AppCompatActivity() {

  private lateinit var recaptchaClient: RecaptchaClient

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    initializeRecaptchaClient()
    findViewById<View>(R.id.btn_login).setOnClickListener { executeLoginAction() }
    findViewById<View>(R.id.btn_redeem).setOnClickListener { executeRedeemAction() }
  }

  private fun initializeRecaptchaClient() {
    lifecycleScope.launch {
      Recaptcha.getClient(application, "YOUR_SITE_KEY")
        .onSuccess { client ->
          recaptchaClient = client
        }
        .onFailure { exception ->
          // Handle communication errors ...
          // See "Handle communication errors" section
        }
    }
  }

  private fun executeLoginAction() {
    lifecycleScope.launch {
      recaptchaClient
        .execute(RecaptchaAction.LOGIN)
        .onSuccess { token ->
          // Handle success ...
          // See "What's next" section for instructions
          // about handling tokens.
        }
        .onFailure { exception ->
          // Handle communication errors ...
          // See "Handle communication errors" section
        }
    }
  }

  private fun executeRedeemAction(){
    lifecycleScope.launch {
      recaptchaClient
        .execute(RecaptchaAction.custom("redeem"))
        .onSuccess { token ->
          // Handle success ...
          // See "What's next" section for instructions
          // about handling tokens.
        }
        .onFailure { exception ->
          // Handle communication errors ...
          // See "Handle communication errors" section
        }
    }
  }
}

Java

public final class MainActivity extends Activity {
  @Nullable private RecaptchaTasksClient recaptchaTasksClient = null;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    initializeRecaptchaClient();
    findViewById(R.id.btn_login).setOnClickListener(this::executeLoginAction);
    findViewById(R.id.btn_redeem).setOnClickListener(this::executeRedeemAction);
  }

  private void initializeRecaptchaClient() {
    Recaptcha
      .getTasksClient(getApplication(), "YOUR_SITE_KEY")
      .addOnSuccessListener(
          this,
          new OnSuccessListener<RecaptchaTasksClient>() {
            @Override
            public void onSuccess(RecaptchaTasksClient client) {
              MainActivity.this.recaptchaTasksClient = client;
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle communication errors ...
              // See "Handle communication errors" section
            }
          });
  }

  private void executeLoginAction(View v) {
    assert recaptchaTasksClient != null;
    recaptchaTasksClient
      .executeTask(RecaptchaAction.LOGIN)
      .addOnSuccessListener(
          this,
          new OnSuccessListener<String>() {
            @Override
            public void onSuccess(String token) {
              // Handle success ...
              // See "What's next" section for instructions
              // about handling tokens.
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle communication errors ...
              // See "Handle communication errors" section
            }
          });
  }

  private void executeRedeemAction(View v) {
    assert recaptchaTasksClient != null;
    recaptchaTasksClient
      .executeTask(RecaptchaAction.custom("redeem"))
      .addOnSuccessListener(
          this,
          new OnSuccessListener<String>() {
            @Override
            public void onSuccess(String token) {
              // Handle success ...
              // See "What's next" section for instructions
              // about handling tokens.
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle communication errors ...
              // See "Handle communication errors" section
            }
          });
  }
}

注意：getClient() 和 execute() 可能需要几秒钟时间才能在设备上完成。因此，我们建议您执行以下操作：

在应用启动时初始化客户端。例如，在自定义 Application 类的 onCreate() 调用中。
确保 execute() 调用不会阻止界面事件。在您的应用中集成 execute() 不应阻止界面事件，例如按下按钮。例如，您可以在创建视图时异步调用 execute()。

处理通信错误

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

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

API 参考文档

如需查看适用于 Android 的 reCAPTCHA API 的完整参考，请参阅 com.google.android.recaptcha。

后续步骤

如需评估 reCAPTCHA 响应令牌，请创建评估。
要针对创建的评估的准确性提供反馈，请为评估添加注释。

注意：reCAPTCHA 响应令牌是通过后端服务器（而不是移动设备）进行评估和注释的。