本页介绍了如何在您的 Android 应用中集成 reCAPTCHA Enterprise。由于移动设备在屏幕尺寸、性能以及应用界面方面存在差异,视觉 reCAPTCHA 挑战(我不是机器人)不适用于移动应用。有关替代的摩擦方法,请参阅配置多重身份验证 (MFA)。
准备工作
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:- 当您启动应用或包含您要保护的操作的 Activity 时,请调用
init()
。 - 在您希望保护的操作完成后,请调用
execute()
。例如,点击登录按钮后。然后,execute()
会返回RecaptchaResultData
令牌。 - 如果没有要验证的操作,请调用
close()
。
在您的应用中调用这三种方法时,请替换
onSuccess()
和onFailure()
方法以处理 API 调用的两种可能结果。具体来说,如果 API 将ApiException
的实例传入onFailure()
,您必须处理使用getStatusCode()
可检索到的每个可能的状态代码。如需了解详情,请参阅处理通信错误。- 当您启动应用或包含您要保护的操作的 Activity 时,请调用
以下示例代码段展示了如何调用 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 响应令牌,请创建评估。