Android CAPTCHA 功能集成指南

产品简介

项目	说明
主要功能	新一代验证码，更智能地解决机器脚本程序自动化攻击带来的业务损失与安全隐患
SDK 隐私政策	政策
SDK 合规指南	指南
SDK 下载链接	下载

环境需求

项目	资源
开发目标	`Android 5.0+`（minSdk 21）
开发环境	`Android Studio 2020.3.1 Arctic Fox+`
编译工具	`Gradle` （Android Gradle Plugin 7+）
系统依赖	无
`SDK` 三方依赖	无
包增量	验证 `SDK`: `60K`

集成 SDK

导入 SDK

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

repositories { flatDir { dirs 'libs' } }

              
              repositories {
    flatDir {
        dirs 'libs'
    }
}

此代码块在浮窗中显示

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

implementation(name: 'engagelab_captcha_android_vx.y.z', ext: 'aar')

              
              implementation(name: 'engagelab_captcha_android_vx.y.z', ext: 'aar')

此代码块在浮窗中显示

非 Kotlin 工程配置

在根目录 build.gradle 配置

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

              
              ext.kotlin_version = "1.6.22"

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" }

              
              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" />  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

              
              <!--必选-默认申请-->
<uses-permission android:name="android.permission.INTERNET" />
<!--兼容到api 23（不含）以下必须声明（即需要运行在4.x和5.x的应用需要声明）-默认没有申请-->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

此代码块在浮窗中显示

混淆规则

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

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

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

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

此代码块在浮窗中显示

配置接口

调用逻辑

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

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

初始化

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

方法描述

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

              
              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 verifyWithCaptcha();

此代码块在浮窗中显示

取消验证

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

方法描述

public void cancel();

              
              public void cancel();

此代码块在浮窗中显示

开启/关闭日志监控

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

方法描述

public void setLogEnable(boolean enable);

              
              public void setLogEnable(boolean enable);

此代码块在浮窗中显示

获取验证回调

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

              
              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() { } })

              
              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(); } }

              
              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 onConfigurationChanged(Configuration newConfig) {
    super.onConfigurationChanged(newConfig);
    if(gtCaptcha4Client != null){
        gtCaptcha4Client.configurationChanged(newConfig);
    }
}

此代码块在浮窗中显示

预加载代码示例

@Override public void onViewCreated(View view, Bundle savedInstanceState){ super.onViewCreated(view, savedInstanceState); String[] apiServers = {"captcha-api.engagelab.com"}; String[] staticServers = {"captcha-stat.engagelab.com/www/js"}; GTCaptcha4Config config = new GTCaptcha4Config.Builder() // 设置服务地址 .setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html") .setApiServers(apiServers) .setStaticServers(staticServers) .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(); }

              
              @Override
public void onViewCreated(View view, Bundle savedInstanceState){
    super.onViewCreated(view, savedInstanceState);
    String[] apiServers = {"captcha-api.engagelab.com"};
    String[] staticServers = {"captcha-stat.engagelab.com/www/js"};
    GTCaptcha4Config config = new GTCaptcha4Config.Builder()
            // 设置服务地址
            .setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html")
            .setApiServers(apiServers)
            .setStaticServers(staticServers)
            .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(){ String[] apiServers = {"captcha-api.engagelab.com"}; String[] staticServers = {"captcha-stat.engagelab.com/www/js"}; GTCaptcha4Config config = new GTCaptcha4Config.Builder() // 设置服务地址 .setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html") .setApiServers(apiServers) .setStaticServers(staticServers) .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(); }

              
              private void click(){
    String[] apiServers = {"captcha-api.engagelab.com"};
    String[] staticServers = {"captcha-stat.engagelab.com/www/js"};
    GTCaptcha4Config config = new GTCaptcha4Config.Builder()
            // 设置服务地址
            .setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html")
            .setApiServers(apiServers)
            .setStaticServers(staticServers)
            .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 类配置参数

定义	说明
`setResourcePath`	必须设置为：https://captcha-stat.engagelab.com/www/gt4-index.html
`setApiServers`	必须设置为：captcha-api.engagelab.com
`setStaticServers`	必须设置为：captcha-stat.engagelab.com/www/js
`setParams`	额外的参数，会被会传递到前端 `js` 中使用
`setDebug`	是否 `debug` 模式，默认 `false`，线上请置为 `false`
`setLanguage`	指定语言，默认跟随应用语言
`setCanceledOnTouchOutside`	点击区域外是否消失，默认 `true`
`setTimeOut`	设置超时，单位 `ms`，默认 10000
`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() }

              
              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 列表