logo文档
CAPTCHA
文档首页
客户端SDK服务端数据安全
搜索
简体中文
English
繁體中文
简体中文
日本語
ภาษาไทย
Español
登录
客户端SDK / Android / API 指南

Android SDK API

最新更新：2025-11-07

对外支持工具类

Method

getClient(Context)

获取 GTCaptcha4Client 工具类对象

Declaration

public static GTCaptcha4Client getClient(Context context)
              
              public static GTCaptcha4Client getClient(Context context)
此代码块在浮窗中显示

Parameters

Param Type Description
context context 上下文

Discussion

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

init(String)

使用默认配置初始化

Declaration

public GTCaptcha4Client init(String captchaId)
              
              public GTCaptcha4Client init(String captchaId)
此代码块在浮窗中显示

Parameters

Param Type Description
captchaId String 在后台申请的 captchaId

Discussion

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

init(String, GTCaptcha4Config)

使用自定义配置初始化

Declaration

public GTCaptcha4Client init(String captchaId, GTCaptcha4Config config)
              
              public GTCaptcha4Client init(String captchaId, GTCaptcha4Config config)
此代码块在浮窗中显示

Parameters

Param Type Description
captchaId String 在后台申请的 captchaId
config GTCaptcha4Config 参数配置对象

addOnSuccessListener(GTCaptcha4Client.OnSuccessListener)

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

Declaration

public GTCaptcha4Client addOnSuccessListener(GTCaptcha4Client.OnSuccessListener response)
              
              public GTCaptcha4Client addOnSuccessListener(GTCaptcha4Client.OnSuccessListener response)
此代码块在浮窗中显示

Parameters

Param Type Description
response GTCaptcha4Client.OnSuccessListener 验证结果监听对象

addOnFailureListener(GTCaptcha4Client.OnFailureListener)

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

Declaration

public GTCaptcha4Client addOnFailureListener(GTCaptcha4Client.OnFailureListener listener)
              
              public GTCaptcha4Client addOnFailureListener(GTCaptcha4Client.OnFailureListener listener)
此代码块在浮窗中显示

Parameters

Param Type Description
listener GTCaptcha4Client.OnFailureListener 加载验证码失败监听对象

addOnWebViewShowListener(GTCaptcha4Client.OnWebViewShowListener)

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

Declaration

public GTCaptcha4Client addOnWebViewShowListener(GTCaptcha4Client.OnWebViewShowListener listener)
              
              public GTCaptcha4Client addOnWebViewShowListener(GTCaptcha4Client.OnWebViewShowListener listener)
此代码块在浮窗中显示

Parameters

Param Type Description
listener GTCaptcha4Client.OnWebViewShowListener 验证前端加载成功监听对象

verifyWithCaptcha()

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

Declaration

public GTCaptcha4Client verifyWithCaptcha()
              
              public GTCaptcha4Client verifyWithCaptcha()
此代码块在浮窗中显示

Discussion

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

cancel()

取消验证，关闭验证窗口

Declaration

public void cancel()
              
              public void cancel()
此代码块在浮窗中显示

Discussion

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

setLogEnable(boolean enable)

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

Declaration

public void setLogEnable(boolean enable)
              
              public void setLogEnable(boolean enable)
此代码块在浮窗中显示

Discussion

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

destroy()

销毁生命周期长的资源

Declaration

public void destroy()
              
              public void destroy()
此代码块在浮窗中显示

Discussion

销毁验证资源，务必调用

Discussion

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

configurationChanged(Configuration)

横竖屏切换

Declaration

public void configurationChanged(Configuration newConfig)
              
              public void configurationChanged(Configuration newConfig)
此代码块在浮窗中显示

Discussion

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

getVersion()

获取版本号

Declaration

public static String getVersion()
              
              public static String getVersion()
此代码块在浮窗中显示

Return Value

返回版本号，类型为 String

isSupportWebView(Context)

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

Declaration

public static Pair<Boolean, String> isSupportWebView(Context context)
              
              public static Pair<Boolean, String> isSupportWebView(Context context)
此代码块在浮窗中显示

Return Value

Pair 对象说明

Param Type Description
first Boolean 是否支持 WebView，若不支持则可以走兜底逻辑
second String 加载 WebView 对象报错说明

GTCaptcha4Config#Builder

参数配置类

setTimeOut(int)

设置请求超时时间

Declaration

public Builder setTimeOut(int timeOut)
              
              public Builder setTimeOut(int timeOut)
此代码块在浮窗中显示

Parameters

Param Type Description
timeOut int 单位 ms，默认 10000

setResourcePath(String)

设置 WebView 加载资源地址

Declaration

public Builder setResourcePath(String html)
              
              public Builder setResourcePath(String html)
此代码块在浮窗中显示

Parameters

Param Type Description
html String WebView 加载地址

Discussion

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

setLanguage(String)

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

Declaration

public Builder setLanguage(String language)
              
              public Builder setLanguage(String language)
此代码块在浮窗中显示

Parameters

Param Type Description
language String 前端支持语言短码，详见前端文档

Discussion

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

setCanceledOnTouchOutside(boolean)

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

Declaration

public Builder setCanceledOnTouchOutside(boolean canceledOnTouchOutside)
              
              public Builder setCanceledOnTouchOutside(boolean canceledOnTouchOutside)
此代码块在浮窗中显示

Parameters

Param Type Description
canceledOnTouchOutside boolean true 为消失

setDebug(boolean)

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

Declaration

public Builder setDebug(boolean debug)
              
              public Builder setDebug(boolean debug)
此代码块在浮窗中显示

Parameters

Param Type Description
debug boolean true 为 debug，默认为 false

setBackgroundColor(int)

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

Declaration

public Builder setBackgroundColor(int backgroundColor)
              
              public Builder setBackgroundColor(int backgroundColor)
此代码块在浮窗中显示

Parameters

Param Type Description
backgroundColor int 颜色资源地址或者 Color.parseColor() 返回值

setDialogStyle(String)

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

Declaration

public Builder setDialogStyle(String dialogStyle)
              
              public Builder setDialogStyle(String dialogStyle)
此代码块在浮窗中显示

Parameters

Param Type Description
dialogStyle String 对话框的主题样式名称

Declaration

以下为默认主题样式

<style name="gt4_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>
              
              <style name="gt4_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(GTCaptcha4Client.OnDialogShowListener)

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

Declaration

public void setDialogShowListener(GTCaptcha4Client.OnDialogShowListener dialogShowListener)
              
              public void setDialogShowListener(GTCaptcha4Client.OnDialogShowListener dialogShowListener)
此代码块在浮窗中显示

Parameters

Param Type Description
dialogShowListener GTCaptcha4Client.OnDialogShowListener 验证窗口显示的监听对象

setParams(Map<String, Object>)

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

Declaration

public Builder setParams(Map<String, Object> params)
              
              public Builder setParams(Map<String, Object> params)
此代码块在浮窗中显示

Parameters

Param Type Description
params JSONObject Additional configuration parameter

Discussion

支持的键值如下表:

Key ValueType Description Default Value
displayMode int 主题样式, 0: 跟随系统 1: 普通 2: 暗黑 0
protocol String 协议头，支持 "https:// or http:// https://
bgColor String 验证背景蒙版颜色，遵循 css 规则，注意最后两位为透明度 #00000000
loading String 自定义 loading，WebView 加载 html 的loading 资源相对路径，空字符串表示取消loading效果 "/gt4-loading.gif"
rem float 设置验证码整体的缩放比例 1
hideBar JSONArray 隐藏后续验证界面的关闭按钮、刷新按钮 N/A
nextWidth String 验证码弹窗的宽度，需要携带单位，如"300px" N/A
riskType String 结合风控融合，指定验证形式 N/A
hideSuccess boolean 隐藏验证成功弹窗 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); GTCaptcha4Config.Builder builder = new GTCaptcha4Config.Builder() .setParams(params);
              
              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);

GTCaptcha4Config.Builder builder = new GTCaptcha4Config.Builder()
        .setParams(params);
此代码块在浮窗中显示

build()

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

Declaration

public GTCaptcha4Config build()
              
              public GTCaptcha4Config build()
此代码块在浮窗中显示

GTCaptcha4Client#OnSuccessListener

验证结果回调监听类

onSuccess(Boolean, String)

验证接口回调

Declaration

void onSuccess(Boolean status, String response)
              
              void onSuccess(Boolean status, String response)
此代码块在浮窗中显示

Parameters

Param Type Description
status Boolean 用户操作验证结果，true 为成功，false 为失败，失败会刷新验证样式
response String 用户操作验证成功，需要拿 response 数据到服务端验证

Discussion

验证成功描述如：

{"lot_number":"b150e61198924eff9eaae121e9b67aa8","pass_token":"6fcfba4c35cb57b873c99c5b3b02089c58a26244c18f7706aaa1e87aed3aa8f4","gen_time":"1622020720","captcha_output":"Tu6rW0dRNO0NLxMKftwdH00G5whF5HHddthoXSEA1G4="}
              
              {"lot_number":"b150e61198924eff9eaae121e9b67aa8","pass_token":"6fcfba4c35cb57b873c99c5b3b02089c58a26244c18f7706aaa1e87aed3aa8f4","gen_time":"1622020720","captcha_output":"Tu6rW0dRNO0NLxMKftwdH00G5whF5HHddthoXSEA1G4="}
此代码块在浮窗中显示

验证失败描述如：

{"captchaId":"647f5ed2ed8acb4be36784e01556bb71","captchaType":"slide","challenge":"95ed53b4-95c6-4c6b-9aac-769b29ef74a0"}
              
              {"captchaId":"647f5ed2ed8acb4be36784e01556bb71","captchaType":"slide","challenge":"95ed53b4-95c6-4c6b-9aac-769b29ef74a0"}
此代码块在浮窗中显示

GTCaptcha4Client#OnFailureListener

加载失败回调监听类

onFailure(String)

加载失败回调

Declaration

void onFailure(String error)
              
              void onFailure(String error)
此代码块在浮窗中显示

Parameters

Param Type Description
error String 验证加载失败描述，注意：包括用户主动取消

Discussion

加载失败描述如：

{"code":"-14460","msg":"验证会话已取消","desc":{"description":"User cancelled 'Captcha'"}}
              
               {"code":"-14460","msg":"验证会话已取消","desc":{"description":"User cancelled 'Captcha'"}}
此代码块在浮窗中显示

GTCaptcha4Client#OnWebViewShowListener

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

onWebViewShow()

验证前端加载成功

Declaration

void onWebViewShow()
              
              void onWebViewShow()
此代码块在浮窗中显示

Discussion

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

GTCaptcha4Client#OnDialogShowListener

验证窗口显示的监听回调

actionBeforeDialogShow(Dialog)

验证窗口在显示前回调

Declaration

void actionBeforeDialogShow(Dialog dialog)
              
              void actionBeforeDialogShow(Dialog dialog)
此代码块在浮窗中显示

Parameters

Param Type Description
dialog Dialog 验证窗口实例

actionAfterDialogShow()

验证窗口在显示后回调

Declaration

void actionAfterDialogShow(Dialog dialog)
              
              void actionAfterDialogShow(Dialog dialog)
此代码块在浮窗中显示

Parameters

Param Type Description
dialog Dialog 验证窗口实例

Discussion

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

onDialogFocusChanged()

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

Declaration

void onDialogFocusChanged(Dialog dialog, boolean hasFocus)
              
              void onDialogFocusChanged(Dialog dialog, boolean hasFocus)
此代码块在浮窗中显示

Parameters

Param Type Description
dialog Dialog 验证窗口实例
hasFocus boolean 是否有焦点
icon
联系销售