> >

概述与资源

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

环境需求

条目	资源
开发目标	`Android 5.0+`
开发环境	`Android Studio 4.1`
编译工具	`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_*",

配置接口

调用逻辑

配置初始化
启动验证
获取验证回调
销毁资源

参考行为验证的产品结构流程, 必须要先在您的后端搭建相应的服务端接口（请参考服务端部署文档），并配置从极验管理后台获取的 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 列表

概述与资源

环境需求

相关资源

安装

集成 SDK

手动下载集成

导入 SDK

非 Kotlin 工程配置

添加权限

混淆规则

配置接口

调用逻辑

初始化

启动验证

取消验证

开启/关闭日志监控

获取验证回调

销毁资源

横竖屏切换

预加载代码示例

正常加载代码示例

参数配置

处理错误

集成 `SDK`

导入 `SDK`

非 `Kotlin` 工程配置

`添加权限`