> >

概述与资源

行为验证 Android SDK 提供给集成 Android 原生客户端开发的开发者使用。

环境需求

条目 资源
开发目标 Android 5.0+（minSdk 21）
开发环境 Android Studio 4.2+
编译工具 Gradle （ant 编译请解压提取 jar 和资源文件）
系统依赖 无
SDK 三方依赖 无
包增量 验证 SDK: 60K

相关资源

条目 资源地址
产品结构流程 通讯流程， 交互流程
常见问题 Error Code 列表
SDK 资源包 请进入后台下载

安装

集成 SDK

手动下载集成

从 SDK 资源包链接下载 .zip 文件获取最新的 sdk。

导入 SDK

将 zip 包中的 .aar 文件（包括 geetest_captcha_android_vx.y.z_date.aar ）拖拽到工程中的 libs 文件夹下，在拖入 .aar 到 libs 文件夹后，还要检查 .aar 是否被添加到 Library，要在项目的 build.gradle 下添加如下代码：

repositories {
    flatDir {
        dirs 'libs'
    }
}

并且要手动将 aar 包添加依赖 (AAR 默认不传递第三方依赖，需要您手动添加)：

implementation(name: 'geetest_captcha_android_vx.y.z_date', ext: 'aar')
非 Kotlin 工程配置

在根目录 build.gradle 配置

ext.kotlin_version = "1.4.10"

dependencies {
    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
}

在引入模块 build.gradle 配置

apply plugin: 'kotlin-android'
dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
}

若 kotlin 版本存在冲突，剔除 kotlin 依赖即可 exclude(group: 'org.jetbrains.kotlin')

添加权限

<!--必选-默认申请-->
<uses-permission android:name="android.permission.INTERNET" />
<!--兼容到api 23（不含）以下必须声明（即需要运行在4.x和5.x的应用需要声明）-默认没有申请-->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!--可选-6.0或以上需动态申请（存储日志方便分析报错，日志路径 /sdcard/Android/data/Your PackageName/files/Geetest/captcha_log.txt）-->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

混淆规则

SDK 的 aar 包已做混淆处理，两次混淆会导致不可预期的错误，默认情况下 aar 包内包含当前 SDK 的混淆配置，远端依赖或者本地 aar 依赖都能确保 SDK 不被二次混淆。如有解压 aar 包单独集成 jar 与 资源文件的需求，请务必将解压目录中的 proguard.txt 文件内容拷贝到应用的混淆配置中，跳过对 SDK 的二次混淆操作。

如果使用了 andRes 进行资源混淆，请将 SDK 内部包含资源排除混淆，避免因找不到资源而报错。排除配置如下：

"R.string.gt4_*",
"R.style.gt4_*",

配置接口

调用逻辑

  1. 配置初始化
  2. 启动验证
  3. 获取验证回调
  4. 销毁资源

参考行为验证的产品结构流程, 必须要先在您的后端搭建相应的服务端接口（请参考服务端部署文档），并配置从极验管理后台 获取的 captchaId 和 Key

初始化

SDK 初始化配置信息，可放在 onCreate 或者 onCreateView 方法进行初始化

方法描述

public static GTCaptcha4Client getClient(Context context);
public GTCaptcha4Client init(String captchaId);
public GTCaptcha4Client init(String captchaId, GTCaptcha4Config config)

参数说明

参数 类型 说明
context Context 上下文对象，必须为 Activity 实例
appId String APP_ID，必须参数
config GTCaptcha4Config 参数配置对象，非必须

init() 方法启动预加载，若在 onCreate 或者 onCreateView 方法进行初始化，则会提前加载验证流程，可更快唤起验证。若在需要唤起验证时机再 init()，则加载速度比预加载慢，建议在 onCreate 或者 onCreateView 方法进行初始化。

启动验证

开始验证流程

方法描述

public void verifyWithCaptcha();

取消验证

取消验证流程，关闭验证窗口

方法描述

public void cancel();

开启/关闭日志监控

设置开启或关闭日志打印监控

方法描述

public void setLogEnable(boolean enable);

获取验证回调

public GTCaptcha4Client addOnSuccessListener(OnSuccessListener listener);
public GTCaptcha4Client addOnFailureListener(OnFailureListener listener);
public GTCaptcha4Client addOnWebViewShowListener(OnWebViewShowListener listener);

代码示例

gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener() {
    @Override
    public void onSuccess(boolean status, String response) {
        if(status){
            // TODO 开启二次验证
        }else {
            // TODO 用户答案验证错误
        }
    }
}).addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {
    @Override
    public void onFailure(String error) {
    }
}).addOnWebViewShowListener(new GTCaptcha4Client.OnWebViewShowListener() {
      @Override
      public void onWebViewShow() {
      }
  })

销毁资源

在 onDestroy 生命周期销毁资源

public void onDestroy(){
    super.onDestroy();
    if(gtCaptcha4Client != null){
        gtCaptcha4Client.destroy();
    }
}
横竖屏切换
@Override
public void onConfigurationChanged(Configuration newConfig) {
    super.onConfigurationChanged(newConfig);
    if(gtCaptcha4Client != null){
        gtCaptcha4Client.configurationChanged(newConfig);
    }
}
预加载代码示例
@Override
public void onViewCreated(View view, Bundle savedInstanceState){
    super.onViewCreated(view, savedInstanceState);
    GTCaptcha4Config config = new GTCaptcha4Config.Builder()
            .setDebug(true) // TODO 线上务必关闭
            .setLanguage("zh")
            .setTimeOut(10000)
            .setCanceledOnTouchOutside(true)
            .build();
    gtCaptcha4Client = GTCaptcha4Client.getClient(activity)
            .init("your captcha_id", config);
}

private void click(){
    gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener {
                @Override
                public void onSuccess(boolean status, String response) {
                    if(status){
                        // TODO 开启二次验证
                    }else {
                        // TODO 用户答案验证错误
                    }
                }
            })
            .addOnFailureListener(new GTCaptcha4Client.OnFailureListener {
                @Override
                public void onFailure(String error) {
                }
            })
            .verifyWithCaptcha();
}
正常加载代码示例
private void click(){
    GTCaptcha4Config config = new GTCaptcha4Config.Builder()
            .setDebug(true) // TODO 线上务必关闭
            .setLanguage("zh")
            .setTimeOut(10000)
            .setCanceledOnTouchOutside(true)
            .build();
    gtCaptcha4Client = GTCaptcha4Client.getClient(activity)
            .init("your captcha_id", config)
            .addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener {
                @Override
                public void onSuccess(boolean status, String response) {
                    if(status){
                        // TODO 开启二次验证
                    }else {
                        // TODO 用户答案验证错误
                    }
                }
            })
            .addOnFailureListener(new GTCaptcha4Client.OnFailureListener {
                @Override
                public void onFailure(String error) {
                }
            })
            .verifyWithCaptcha();
}

示例代码细节参考官方提供的 Demo

参数配置

通过 GTCaptcha4Config.Builder 类配置参数

定义 说明
setParams 额外的参数，会被会传递到前端 js 中使用
setDebug 是否 debug 模式，默认 false，线上请置为 false
setLanguage 指定语言，默认跟随应用语言
setCanceledOnTouchOutside 点击区域外是否消失，默认 true
setTimeOut 设置超时，单位 ms，默认 10000
setResourcePath 设置中间地址，默认加载本地 html 文件
setBackgroundColor 设置背景颜色，默认透明
setDialogStyle 设置对话框的主题样式，默认值gt4_captcha_dialog_style
setDialogShowListener 设置验证窗口显示的监听回调
build 构建 GTCaptcha4Config 对象

可通过 setParams 接口配置参数见接口文档

setParams 接口只能接收基本数据类型、字符串、JSONArray 类型的数据

处理错误

验证过程中可能发生一些预料之外的错误, 您可以通过实现 addOnFailureListener接口后, 在下面的回调方法中进行处理:

注意：错误回调包括用户主动取消验证，可单独过滤掉

gtCaptcha4Client.addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {
    @Override
    public void onFailure(String error){
        // 返回error内容示例
        // {"code":"-14460","msg":"验证会话已取消","desc":{"description":"User cancelled 'Captcha'"}}
        // 可对error做json解析，自行替换错误描述，保留错误码
        Toast.makeText(context, "验证错误: $error", Toast.LENGTH_SHORT).show()
    }

强烈建议在向用户展示验证错误原因时，同时展示错误码，方便后续排查线上问题。

可能遇到的错误码请参考后面的列表: Error Code 列表

对以上内容做个评价吧：

您是否在阅读文档中遇到以下问题？

写下您的建议：

提交成功

非常感谢您的反馈!