Captcha v4
API 参考

Android

GeelabCaptchaClient

验证 4.0 主要对外支持工具类

Method

getClient(Context)

获取 GeelabCaptchaClient 工具类对象

Declaration

public static GeelabCaptchaClient getClient(Context context)

Parameters

ParamTypeDescription
contextContext上下文

Discussion

注意：非单例实现，通过 getClient() 获取的 GeelabCaptchaClient 对象需要保存，以方便在 onDestory 或者其他生命周期使用

init(String)

使用默认配置初始化

Declaration

public GeelabCaptchaClient init(String captchaId)

Parameters

ParamTypeDescription
captchaIdString在后台申请的 captchaId

Discussion

注意：调用 init() 方法后就执行了加载验证码操作，若在 onResume() 生命周期之前调用，就预加载了验证码，当执行 verifyWithCaptcha() 展示验证码时候，则验证码很快加载展示出来。下同。

init(String, GeelabCaptchaConfig)

使用自定义配置初始化

Declaration

public GeelabCaptchaClient init(String captchaId, GeelabCaptchaConfig config)

Parameters

ParamTypeDescription
captchaIdString在后台申请的 captchaId
configGeelabCaptchaConfig参数配置对象

addOnSuccessListener(GeelabCaptchaClient.OnSuccessListener)

添加验证结果监听对象，当验证码加载成功，用户解答验证码结果回调

Declaration

public GeelabCaptchaClient addOnSuccessListener(GeelabCaptchaClient.OnSuccessListener response)

Parameters

ParamTypeDescription
responseGeelabCaptchaClient.OnSuccessListener验证结果监听对象

addOnFailureListener(GeelabCaptchaClient.OnFailureListener)

添加加载验证码失败监听对象，加载验证码的过程中报错

Declaration

public GeelabCaptchaClient addOnFailureListener(GeelabCaptchaClient.OnFailureListener listener)

Parameters

ParamTypeDescription
listenerGeelabCaptchaClient.OnFailureListener加载验证码失败监听对象

addOnWebViewShowListener(GeelabCaptchaClient.OnWebViewShowListener)

添加加载验证前端成功的监听对象，验证前端加载成功后回调。预加载已完成的情况下，调用verifyWithCaptcha后立即回调。

Declaration

public GeelabCaptchaClient addOnWebViewShowListener(GeelabCaptchaClient.OnWebViewShowListener listener)

Parameters

ParamTypeDescription
listenerGeelabCaptchaClient.OnWebViewShowListener验证前端加载成功监听对象

verifyWithCaptcha()

开启验证流程，加载验证码

Declaration

public GeelabCaptchaClient verifyWithCaptcha()

Discussion

注意：调用 verifyWithCaptcha() 之前需要先调用 init()、addOnSuccessListener()、addOnFailureListener 否则可能报错

cancel()

取消验证，关闭验证窗口

Declaration

public void cancel()

Discussion

注意：调用 cancel() 之前需要先调用 init()、addOnSuccessListener()、addOnFailureListener 否则可能报错

setLogEnable(boolean enable)

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

Declaration

public void setLogEnable(boolean enable)

Discussion

调用 setLogEnable 会控制日志打印功能

destroy()

销毁生命周期长的资源

Declaration

public void destroy()

Discussion

销毁验证资源，务必调用

Discussion

该方法在客户使用的验证码界面的 onDestroy 生命周期中调用

configurationChanged(Configuration)

横竖屏切换

Declaration

public void configurationChanged(Configuration newConfig)

Discussion

该方法在横竖屏切换生命周期 onConfigurationChanged 方法中调用

getVersion()

获取版本号

Declaration

public static String getVersion()

Return Value

返回版本号，类型为 String

isSupportWebView(Context)

检测是否支持系统 WebView，若不支持，则建议走兜底逻辑

Declaration

public static Pair<Boolean, String> isSupportWebView(Context context)

Return Value

Pair 对象说明

ParamTypeDescription
firstBoolean是否支持 WebView，若不支持则可以走兜底逻辑
secondString加载 WebView 对象报错说明

GeelabCaptchaConfig#Builder

参数配置类

setTimeOut(int)

设置请求超时时间

Declaration

public Builder setTimeOut(int timeOut)

Parameters

ParamTypeDescription
timeOutint单位 ms，默认 10000

setResourcePath(String)

设置 WebView 加载资源地址

Declaration

public Builder setResourcePath(String html)

Parameters

ParamTypeDescription
htmlStringWebView 加载地址

Discussion

默认加载 assets 目录的 gl4-index*.html 文件，无特殊需求无需设置此接口

setLanguage(String)

传输 JS 的设置语言，此接口只能控制加载 WebView 的语言，SDK 的多语言跟随当前应用

Declaration

public Builder setLanguage(String language)

Parameters

ParamTypeDescription
languageString前端支持语言短码，详见前端文档

Discussion

如果设置为 null 或者未设置，则使用应用默认语言短码传输给前端

setCanceledOnTouchOutside(boolean)

设置点击灰色区域是否消失，默认消失

Declaration

public Builder setCanceledOnTouchOutside(boolean canceledOnTouchOutside)

Parameters

ParamTypeDescription
canceledOnTouchOutsidebooleantrue 为消失

setDebug(boolean)

设置是否是 debug 模式，上线务必置为 false，或者不配置

Declaration

public Builder setDebug(boolean debug)

Parameters

ParamTypeDescription
debugbooleantrue 为 debug，默认为 false

setBackgroundColor(int)

设置 WebView 背景色，控制的是 Android WebView 控件的背景色，和前端 JS 的背景色不同

Declaration

public Builder setBackgroundColor(int backgroundColor)

Parameters

ParamTypeDescription
backgroundColorint颜色资源地址或者 Color.parseColor() 返回值

setDialogStyle(String)

设置验证码对话框的主题样式

Declaration

public Builder setDialogStyle(String dialogStyle)

Parameters

ParamTypeDescription
dialogStyleString对话框的主题样式名称

Declaration

以下为默认主题样式

<style name="geelab_captcha_dialog_style" parent="android:Theme.Dialog">
    <!--Dialog的windowFrame框为无-->
    <item name="android:windowFrame">@null</item>
    <!--是否浮现在activity之上-->
    <item name="android:windowIsFloating">true</item>
    <!--是否半透明-->
    <item name="android:windowIsTranslucent">true</item>
    <!--除去title-->
    <item name="android:windowNoTitle">true</item>
    <item name="android:windowContentOverlay">@null</item>
    <!--显示区域以外是否使用黑色半透明背景-->
    <item name="android:backgroundDimEnabled">true</item>
    <!--设置dialog的背景-->
    <item name="android:windowBackground">@android:color/transparent</item>
    <item name="android:padding">0dp</item>
</style>

setDialogShowListener(GeelabCaptchaClient.OnDialogShowListener)

设置验证窗口显示的监听回调

Declaration

public void setDialogShowListener(GeelabCaptchaClient.OnDialogShowListener dialogShowListener)

Parameters

ParamTypeDescription
dialogShowListenerGeelabCaptchaClient.OnDialogShowListener验证窗口显示的监听对象

setParams(Map<String, Object>)

额外参数配置，当前参数完全传输给 JS

Declaration

public Builder setParams(Map<String, Object> params)

Parameters

ParamTypeDescription
paramsJSONObjectAdditional configuration parameter

Discussion

支持的键值如下表:

KeyValueTypeDescriptionDefault Value
displayModeint主题样式, 0: 跟随系统 1: 普通 2: 暗黑0
protocolString协议头，支持 "https://" 或 "http://"https://
bgColorString验证背景蒙版颜色，遵循 css 规则，注意最后两位为透明度#00000000
loadingString自定义 loading，WebView 加载 html 的loading 资源相对路径，空字符串表示取消loading效果"/geelab-loading.gif"
remfloat设置验证码整体的缩放比例1
hideBarJSONArray隐藏后续验证界面的关闭按钮、刷新按钮N/A
nextWidthString验证码弹窗的宽度，需要携带单位，如"300px"N/A
riskTypeString结合风控融合，指定验证形式N/A
hideSuccessboolean隐藏验证成功弹窗FALSE

Sample Code

Map<String, Object> params = new HashMap<>();
params.put("displayMode", 0);
params.put("protocol", "https://");
params.put("bgColor", "#CC0000FF");
params.put("loading", "./loading_test.gif");
params.put("rem", 0.6);
JSONArray hideBar = new JSONArray()
        .put("close")
        .put("refresh");
params.put("hideBar", hideBar);
params.put("nextWidth", "300px");
params.put("hideSuccess", true);

GeelabCaptchaConfig.Builder builder = new GeelabCaptchaConfig.Builder()
        .setParams(params);

build()

构造 GeelabCaptchaConfig 对象，传输给 init() 接口使用

Declaration

public GeelabCaptchaConfig build()

GeelabCaptchaClient#OnSuccessListener

验证结果回调监听类

onSuccess(Boolean, String)

验证接口回调

Declaration

void onSuccess(Boolean status, String response)

Parameters

ParamTypeDescription
statusBoolean用户操作验证结果，true 为成功，false 为失败，失败会刷新验证样式
responseString用户操作验证成功，需要拿 response 数据到服务端验证

Discussion

验证成功描述如：

{"lot_number":"b150e61198924eff9eaae121e9b67aa8","pass_token":"6fcfba4c35cb57b873c99c5b3b02089c58a26244c18f7706aaa1e87aed3aa8f4","gen_time":"1622020720","captcha_output":"Tu6rW0dRNO0NLxMKftwdH00G5whF5HHddthoXSEA1G4="}

验证失败描述如：

{"captchaId":"647f5ed2ed8acb4be36784e01556bb71","captchaType":"slide","challenge":"95ed53b4-95c6-4c6b-9aac-769b29ef74a0"}

GeelabCaptchaClient#OnFailureListener

加载失败回调监听类

onFailure(String)

加载失败回调

Declaration

void onFailure(String error)

Parameters

ParamTypeDescription
errorString验证加载失败描述，注意：包括用户主动取消

Discussion

加载失败描述如：

 {"code":"-14460","msg":"验证会话已取消","desc":{"description":"User cancelled 'Captcha'"}}

GeelabCaptchaClient#OnWebViewShowListener

验证前端加载成功回调监听类

onWebViewShow()

验证前端加载成功

Declaration

void onWebViewShow()

Discussion

在验证前端加载成功后回调。预加载已完成的情况下，调用verifyWithCaptcha后立即回调。

GeelabCaptchaClient#OnDialogShowListener

验证窗口显示的监听回调

actionBeforeDialogShow(Dialog)

验证窗口在显示前回调

Declaration

void actionBeforeDialogShow(Dialog dialog)

Parameters

ParamTypeDescription
dialogDialog验证窗口实例

actionAfterDialogShow()

验证窗口在显示后回调

Declaration

void actionAfterDialogShow(Dialog dialog)

Parameters

ParamTypeDescription
dialogDialog验证窗口实例

Discussion

可在此处对系统样式进行改变，例如隐藏导航栏、隐藏状态栏等

onDialogFocusChanged()

验证窗口在改变焦点时回调

Declaration

void onDialogFocusChanged(Dialog dialog, boolean hasFocus)

Parameters

ParamTypeDescription
dialogDialog验证窗口实例
hasFocusboolean是否有焦点

错误码

错误码错误描述错误详情
-10170参数不合法Response 成功回调为 null
-10171参数不合法Context 对象为 null
-10172参数不合法Context 实例必须为 Activty 类型
-10174参数不合法appId 未配置
-13099不支持的 WebView 组件当前设备 new WebView 对象报错
-13175参数不合法H5 静态地址配置错误
-13201网络错误ERROR_UNKNOWN 一般错误
-13202网络错误ERR_ADDRESS_UNREACHABLE 地址无法访问
-13203网络错误ERROR_UNSUPPORTED_AUTH_SCHEME 不支持身份验证方案
-13204网络错误ERROR_AUTHENTICATION 用户身份验证失败
-13205网络错误ERROR_PROXY_AUTHENTICATION 代理用户身份验证失败
-13206网络错误ERROR_CONNECT 未链接到服务器
-13207网络错误ERROR_IO 无法读写服务器
-13208网络错误ERR_CONNECTION_TIMED_OUT 链接超时
-13209网络错误ERROR_REDIRECT_LOOP 重定向太多
-13210网络错误ERROR_UNSUPPORTED_SCHEME 不支持 URI 方案
-13211网络错误ERROR_FAILED_SSL_HANDSHAKE SSL 握手失败
-13212网络错误ERROR_BAD_URL URL 格式错误
-13213网络错误ERROR_FILE 通用文件错误
-13214网络错误ERROR_FILE_NOT_FOUND 文件未找到
-13215网络错误ERROR_TOO_MANY_REQUESTS 加载请求过多
-13216网络错误ERROR_UNSAFE_RESOURCE 资源加载取消
-13220网络错误WebView 加载报错，当前系统版本小于 4.4w 无详细错误码
-13221网络错误WebView 加载报错，当前系统版本为 5.0 或 5.1 无详细错误码
-13300证书错误SSL_NOTYETVALID 证书未生效
-13301证书错误SSL_EXPIRED 证书已过期
-13302证书错误SSL_IDMISMATCH 证书与 HOST 不匹配
-13303证书错误SSL_UNTRUSTED 不信任证书颁发机构
-13304证书错误SSL_DATE_INVALID 证书日期无效
-13305证书错误SSL_INVALID 一般证书异常
-13580加载遇到一点麻烦H5 回调数据为空
-13581加载遇到一点麻烦H5 回调数据解析报错
-13582加载遇到一点麻烦H5 回调数据缺省关键值
-14460验证会话已取消用户主动取消验证流程

iOS

iOS SDK 接口参数与配置说明。

Server

服务端二次验证接口文档

On this page

GeelabCaptchaClientMethodgetClient(Context)init(String)init(String, GeelabCaptchaConfig)addOnSuccessListener(GeelabCaptchaClient.OnSuccessListener)addOnFailureListener(GeelabCaptchaClient.OnFailureListener)addOnWebViewShowListener(GeelabCaptchaClient.OnWebViewShowListener)verifyWithCaptcha()cancel()setLogEnable(boolean enable)destroy()configurationChanged(Configuration)getVersion()isSupportWebView(Context)GeelabCaptchaConfig#BuildersetTimeOut(int)setResourcePath(String)setLanguage(String)setCanceledOnTouchOutside(boolean)setDebug(boolean)setBackgroundColor(int)setDialogStyle(String)setDialogShowListener(GeelabCaptchaClient.OnDialogShowListener)setParams(Map<String, Object>)build()GeelabCaptchaClient#OnSuccessListeneronSuccess(Boolean, String)GeelabCaptchaClient#OnFailureListeneronFailure(String)GeelabCaptchaClient#OnWebViewShowListeneronWebViewShow()GeelabCaptchaClient#OnDialogShowListeneractionBeforeDialogShow(Dialog)actionAfterDialogShow()onDialogFocusChanged()错误码