概述与资源

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

环境需求

条目	资源
开发目标	`Android 4.4+`
开发环境	`Android Studio 4.1`
编译工具	`gradle` （`ant` 编译请解压提取 `jar` 和资源文件）
系统依赖	无
`SDK` 三方依赖	无
包增量	`60K`

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

安装

集成 `SDK`

手动下载集成

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

导入 `SDK`

将 zip 包中的 .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" />
<!--可选-6.0或以上需动态申请（存储日志方便分析报错，日志路径 /sdcard/Android/data/Your PackageName/files/Geetest/captcha_log.txt）-->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

混淆规则

极验 SDK 已做混淆处理，集成时请带上混淆规则，勿再次混淆 SDK

-dontwarn com.geetest.captcha.**
-keep class com.geetest.captcha.**{*;}

若使用资源混淆工具，请添加白名单配置

"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 GTCaptcha4Client addOnSuccessListener(OnSuccessListener listener);
public GTCaptcha4Client addOnFailureListener(OnFailureListener 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) {
    }
})

销毁资源

在 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-cn")
            .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-cn")
            .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`	设置背景颜色，默认透明
`build`	构建 `GTCaptcha4Config` 对象

可通过 setParams 接口配置参数有

功能	参数	说明
当前主题样式	`displayMode`	整型，0：跟随系统，1：普通，2：暗黑，3：色盲。默认为 0
验证展示位置	`displayArea`	字符串，`center`：居中，`bottom`：底部，默认为 `center`
协议	`protocol`	字符串，`https://` 或者 `http://`，默认 `https://`
验证窗口向下偏移大小	`barHeight`	整型，单位：逻辑像素，如 14，默认不配置
`H5` 蒙层背景色	`bgColor`	字符串，遵循 `css` 规则，如 `#000000ff`，默认不配置
自定义 loading	`loading`	字符串，本地加载中间页 `loading` 相对路径，如 `./loading.gif`。注意：若远程加载不传此字段，默认不配置

setParams 接口配置示例

HashMap<String, Object> hashMap = new HashMap<>();
// 配置当前主题样式
hashMap.put("displayMode", 0);
GTCaptcha4Config build = new GTCaptcha4Config.Builder()
        .setParams(hashMap)
        .build();

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