Android 集成

环境要求

项目	要求
开发目标	Android 原生客户端
Kotlin 版本	1.6.22+
第三方依赖	无（AAR 默认不传递第三方依赖）

SDK 提供 AAR 格式，支持本地依赖集成。

安装

导入 AAR 文件

将 zip 包中的 .aar 文件（geelab_captcha_android_vx.y.z_date.aar）拖拽到工程中的 libs 文件夹下。

配置 Gradle

在项目的 build.gradle 下添加如下代码：

build.gradle

repositories {
    flatDir {
        dirs 'libs'
    }
}

添加依赖

手动将 aar 包添加依赖：

build.gradle

implementation(name: 'geelab_captcha_android_vx.y.z_date', ext: 'aar')

请将文件名替换为实际下载的 AAR 文件名。

非 Kotlin 工程配置

如果您的项目不是 Kotlin 工程，需要添加 Kotlin 支持。

在根目录 build.gradle 配置：

build.gradle (Project)

ext.kotlin_version = "1.6.22"

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

在引入模块 build.gradle 配置：

build.gradle (Module)

apply plugin: 'kotlin-android'

dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
}

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

权限配置

在 AndroidManifest.xml 中添加必要权限：

AndroidManifest.xml

<!-- 必选 - 默认申请 -->
<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 文件内容拷贝到应用的混淆配置中。

andRes 资源混淆

如果使用了 andRes 进行资源混淆，请将 SDK 内部包含资源排除混淆：

资源混淆排除

"R.string.geelab_*",
"R.style.geelab_*",

基础集成

在 onCreate 或 onCreateView 方法进行初始化，提前加载验证流程：

预加载集成

@Override
public void onViewCreated(View view, Bundle savedInstanceState) {
    super.onViewCreated(view, savedInstanceState);

    // 1. 配置参数
    GeelabCaptchaConfig config = new GeelabCaptchaConfig.Builder()
            .setDebug(true)  // TODO 线上务必关闭
            .setLanguage("zh")
            .setTimeOut(10000)
            .setCanceledOnTouchOutside(true)
            .build();

    // 2. 初始化客户端
    geelabCaptchaClient = GeelabCaptchaClient.getClient(activity)
            .init("your_captcha_id", config);
}

private void click() {
    // 3. 添加回调监听
    geelabCaptchaClient
            .addOnSuccessListener(new GeelabCaptchaClient.OnSuccessListener() {
                @Override
                public void onSuccess(boolean status, String response) {
                    if (status) {
                        // TODO 开启二次验证
                    } else {
                        // TODO 用户答案验证错误
                    }
                }
            })
            .addOnFailureListener(new GeelabCaptchaClient.OnFailureListener() {
                @Override
                public void onFailure(String error) {
                    // TODO 处理验证失败
                }
            })
            .verifyWithCaptcha();
}

预加载方式可以提升用户体验，减少等待时间。

在需要唤起验证时再进行初始化：

正常加载集成

private void click() {
    // 1. 配置参数
    GeelabCaptchaConfig config = new GeelabCaptchaConfig.Builder()
            .setDebug(true)  // TODO 线上务必关闭
            .setLanguage("zh")
            .setTimeOut(10000)
            .setCanceledOnTouchOutside(true)
            .build();

    // 2. 初始化并启动验证
    geelabCaptchaClient = GeelabCaptchaClient.getClient(activity)
            .init("your_captcha_id", config)
            .addOnSuccessListener(new GeelabCaptchaClient.OnSuccessListener() {
                @Override
                public void onSuccess(boolean status, String response) {
                    if (status) {
                        // TODO 开启二次验证
                    } else {
                        // TODO 用户答案验证错误
                    }
                }
            })
            .addOnFailureListener(new GeelabCaptchaClient.OnFailureListener() {
                @Override
                public void onFailure(String error) {
                    // TODO 处理验证失败
                }
            })
            .verifyWithCaptcha();
}

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

配置选项

配置参数说明

通过 GeelabCaptchaConfig.Builder 类配置参数：

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

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

初始化方法

初始化 API

public static GeelabCaptchaClient getClient(Context context);
public GeelabCaptchaClient init(String captchaId);
public GeelabCaptchaClient init(String captchaId, GeelabCaptchaConfig config);

参数说明：

参数	类型	说明
`context`	`Context`	上下文对象，必须为 `Activity` 实例
`captchaId`	`String`	验证 ID，必须参数
`config`	`GeelabCaptchaConfig`	参数配置对象，非必须

处理验证结果

回调监听器

回调接口

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

完整示例

处理验证结果

geelabCaptchaClient
    .addOnSuccessListener(new GeelabCaptchaClient.OnSuccessListener() {
        @Override
        public void onSuccess(boolean status, String response) {
            if (status) {
                // 验证成功，提交到后端进行二次验证
                submitToBackend(response);
            } else {
                // 用户答案验证错误
                Toast.makeText(context, "验证失败，请重试", Toast.LENGTH_SHORT).show();
            }
        }
    })
    .addOnFailureListener(new GeelabCaptchaClient.OnFailureListener() {
        @Override
        public void onFailure(String error) {
            // 验证过程出错
            Log.e("Captcha", "验证错误: " + error);
        }
    })
    .addOnWebViewShowListener(new GeelabCaptchaClient.OnWebViewShowListener() {
        @Override
        public void onWebViewShow() {
            // WebView 显示时的回调
            Log.d("Captcha", "验证窗口已显示");
        }
    });

重要： 必须在服务端进行二次验证，不要仅依赖客户端结果。

API 方法

启动验证

开始验证流程：

public void verifyWithCaptcha();

取消验证

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

public void cancel();

生命周期管理

销毁资源

在 onDestroy 生命周期销毁资源：

资源释放

@Override
public void onDestroy() {
    super.onDestroy();
    if (geelabCaptchaClient != null) {
        geelabCaptchaClient.destroy();
    }
}

务必在 Activity 销毁时调用 destroy() 方法释放资源。

横竖屏切换

处理配置变更：

横竖屏适配

@Override
public void onConfigurationChanged(Configuration newConfig) {
    super.onConfigurationChanged(newConfig);
    if (geelabCaptchaClient != null) {
        geelabCaptchaClient.configurationChanged(newConfig);
    }
}

日志控制

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

日志开关

public void setLogEnable(boolean enable);

错误处理

验证过程中可能发生一些预料之外的错误，您可以通过实现 addOnFailureListener 接口进行处理：

错误处理示例

geelabCaptchaClient.addOnFailureListener(new GeelabCaptchaClient.OnFailureListener() {
    @Override
    public void onFailure(String error) {
        // 返回 error 内容示例
        // {"code":"-14460","msg":"验证会话已取消","desc":{"description":"User cancelled 'Captcha'"}}

        try {
            JSONObject errorObj = new JSONObject(error);
            String code = errorObj.getString("code");
            String msg = errorObj.getString("msg");

            // 向用户展示错误信息和错误码
            String message = String.format("验证错误 [%s]: %s", code, msg);
            Toast.makeText(context, message, Toast.LENGTH_SHORT).show();

            // 记录错误日志
            Log.e("Captcha", "验证错误详情: " + error);
        } catch (JSONException e) {
            e.printStackTrace();
        }
    }
});

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

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

常见问题

下一步

查看服务端集成了解后端验证
阅读 API 参考了解完整 API
查看常见问题解决集成问题

Android 集成

如何指定语言但不生效？

如何移除或自定义 loading？

On this page