Captcha v4
API 参考

Web

Web 端接口参数与配置说明。

配置参数

这里说的配置参数，是指初始化验证时传入的 config 对象（key-value 结构），也就是调用初始化函数 initGeetest4 时所传入的第一个参数的可选参数配置，必需参数请参考部署文档，demo下载请前往Geelab后台下载

除了captchaId，其它均为可选配置参数（以下配置参数除非您知道如何去使用，否则不要去设置（可能在不同的场景下带来副作用））：

参数必填类型说明默认值可选值
captchaIdYstring验证 id，Geelab 后台申请得到
productNstring设置下一步验证的展现形式floatfloat、popup、bind
nativeButtonNobjectGeelab 按钮样式设置{ width:'260px', height:'50px' }单位可以是 px，%，em，rem，pt
remNnumber设置验证码整体的缩放比例1可以根据不同设备传入不同比例值
languageNstring设置验证界面文字的语言, 如不传默认取浏览器设置的语言，不在支持的列表内，默认使用中文zhozho、eng、zho-tw、zho-hk、udm、jpn、ind、kor、rus、ara、spa、pon、por、fra、deu
protocolNstring协议头默认去当前页面的协议头（本地或者混合开发一定要手动设置，否则一般会自动取到file协议)http://、https://
timeoutNnumber设置验证过程中单个请求超时时间30000（ms）大于0的整数
hideBarNarray隐藏后续验证界面的关闭按钮、刷新按钮[]['close','refresh']
maskNobject弹窗相关配置项，目前包括弹窗背景色、点击验证码区域外是否关闭验证{ outside:true, bgColor:'#0000004d' }outside:false, bgColor:任意合法的css颜色单位都可以
apiServersNarray控制api请求的地址，请根据您注册 ID 时选择的地域配置对应的动态域名：全球 cap-global.geelabapi.com、欧洲 cap-eu.geelabapi.com、北美 cap-na.geelabapi.com['cap-global.geelabapi.com']
nextWidthNstring验证码弹窗的宽度（此参数设置后，验证码弹窗将不会自动根据网页内容宽度调整）
riskTypeNstring结合风控融合，指定验证形式
hideSuccessNboolean隐藏bind展现形式下的验证成功弹窗 (注：仅product参数值为bind情况下生效)falsetrue
offlineCbNfunction宕机模式处理函数,默认为 Geelab 的宕机，设置了此函数代表想自定义宕机逻辑（不会再执行默认的宕机模式）
onErrorNfunction初始化验证码之前的错误捕获
userInfoNstring客户端信息，例如用户账号、用户手机号、用户名等

product

在行为验证中，配置了ai模式的绝大多数真实用户仅需点击一下即可通过验证。但是考虑到实际风险情况，被行为验证判定为有风险的请求，会进入下个阶段的验证。此时，行为验证提供了弹出二级验证的交互样式，方便用户兼容自己本身的界面。

目前提供三种展现形式

  • popup（弹出式）

  • float（浮动式）

  • bind（隐藏按钮类型）

对于popup和bind类型，可设置mask中以下参数：

参数类型作用说明
bgColorstring设置弹出背景的颜色默认为黑色，可设置任何一种合法的颜色值
各展现形式效果如下。

popup，弹出式：

initGeetest4({
    // 省略必须的配置参数

    product: 'popup'
}, function (captchaObj) {
    captchaObj.appendTo("#captchaBox"); //将验证按钮插入到宿主页面中captchaBox元素内
    captchaObj.onReady(function(){
      //your code
    }).onSuccess(function(){
      //your code
    }).onError(function(){
      //your code
    })
})

float，浮动式：

initGeetest4({
    // 省略必须的配置参数

    product: 'float'
}, function (captchaObj) {
    captchaObj.appendTo("#captchaBox"); //将验证按钮插入到宿主页面中captchaBox元素内
    captchaObj.onReady(function(){
      //your code
    }).onSuccess(function(){
      //your code
    }).onError(function(){
      //your code
    })
});

bind，隐藏按钮式:

对于bind类型，需要注意此时appendTo接口调用将无效，验证时调用showCaptcha实例方法进行验证。

initGeetest4({
    // 省略必须的配置参数

    product: 'bind'
}, function(captchaObj){
    captchaObj.onReady(function(){
        //验证码ready之后才能调用showCaptcha方法显示验证码
    }).onSuccess(function(){
        //your code,结合您的业务逻辑重置验证码
        captchaObj.reset()
    }).onError(function(){
        //your code
    })
    // 按钮提交事件
    button.click = function(){
        // some code
        // 检测验证码是否ready, 验证码的onReady是否执行
        captchaObj.showCaptcha(); //显示验证码
        // some code
    }
});

nativeButton

调节验证按钮的宽度，使按钮适应宿主页面的尺寸。

默认：260px * 50px。

通过设置 width height 使按钮的宽度与输入框一致：

示例： 设置按钮宽度和高度为 100%，使按钮的宽度与其父元素的宽度一致

initGeetest4({
    // 省略必须的配置参数
    nativeButton:{
      height: '100%',
      width: '100%'
    }
}, handler);

language

设置验证界面文字的语言。示例语言如下，更多支持语言配置可联系 Geelab 小助手获取

  • zho（简体中文）
  • eng（英文）
  • zho-tw（台湾）
  • zho-hk（香港）
  • udm（维吾尔语）
  • jpn（日文）
  • ind（印尼）
  • kor（韩语）
  • rus（俄语）
  • ara（阿拉伯语）
  • spa（西班牙语）
  • pon（巴西葡语）
  • por（欧洲葡语）
  • fra（法语）
  • deu（德语）

设置界面语言为英文

initGeetest4({
    // 省略必须的配置参数

    language: 'eng'
});

protocol

设置验证请求头。常见的有 http://，https://。默认值与宿主页面所使用的协议一致。

initGeetest4({
    // 省略必须的配置参数

    protocol: "https://"
});

timeout

设置验证码单个请求加载超时时间，默认为30000毫秒

initGeetest4({
    // 省略必须的配置参数

    timeout: 10000
});

userInfo

传入客户端信息，例如用户账号、用户手机号、用户名等。

initGeetest4({
    // 省略必须的配置参数

    userInfo: "[email protected]"
});

初始化

使用初始化函数 initGeetest4 初始化后，它的第二个参数是一个回调，回调的第一个参数即是验证实例，如下代码所示。

initGeetest4({
    // 省略配置参数
}, function (captchaObj) {
    // 现在可以调用验证实例 captchaObj 的方法了
});

Web API方法

appendTo(position)

appendTo 方法用于将验证按钮插到宿主页面，使其显示在页面上。接受的参数可以是 id 选择器（例如 #captcha-box），或者 DOM 元素对象。

可以通过以下方式传入:

1.传入 id 选择器

    <div id="captcha-box"></div>
    ...
    <script>
        initGeetest4({
            // 省略配置参数
        }, function (captchaObj) {
            captchaObj.appendTo('#captcha-box');

            // 省略其他方法的调用
        });
    </script>

2.传入 DOM 元素

    <div id="captcha-box"></div>
    ...
    <script>
        var captchaBox = document.getElementById('#captcha-box');
        initGeetest4({
            // 省略配置参数
        }, function (captchaObj) {
            captchaObj.appendTo(captchaBox);

            // 省略其他方法的调用
        });
    </script>

getValidate()

获取用户进行成功验证(onSuccess)所得到的结果，该结果用于进行服务端 SDK 进行二次验证。getValidate 方法返回一个对象，该对象包含一些验证需要的字段。

其他情况下返回 false，因此，网站开发者也可以根据该返回值决定是否需要进行下一步的操作（提交表单或者 ajax 进行二次验证）。

通过 ajax 方式进行二次验证

initGeetest4({
    // 省略配置参数
}, function (captchaObj) {
    // 省略其他方法的调用

    // 这里调用了 onSuccess 方法，该方法介绍见下文
    captchaObj.onSuccess(function () {
        var result = captchaObj.getValidate();

        // ajax 伪代码
        $.ajax({
              url: '服务端',
              data: result,
              dataType: 'json',
              success: function (res) {
                console.log(res.result);
            }
        })
    });
});

reset()

让验证回到初始状态。一般是在用户后台发现验证成功但其他信息不对的情况（比如用户名密码错误），或者验证出现错误的情况。因此，该接口只能在成功或者出错的时候调用才有效。对于bind模式，成功后再次调用showCaptcha会自动reset，无需主动调用

发现用户名或者密码错误后进行重置

initGeetest4({
    // 省略配置参数
}, function (captchaObj) {
    // 省略其他方法的调用

    // 这里调用了 onSuccess 方法，该方法介绍见下文
    captchaObj.onSuccess(function () {
        var result = captchaObj.getValidate();

        // ajax 伪代码
        ajax('/login', {
            lot_number: result.lot_number,
            captcha_output: result.captcha_output,
            pass_token: result.pass_token,
            gen_time: result.gen_time,

            username: 'xxx',
            password: 'xxx'

            // 其他服务端需要的数据，比如登录时的用户名和密码
        }, function (data) {
            // 根据服务端二次验证的结果进行跳转等操作
            if (data.status === 'fail') {
                alert('用户名或密码错误，请重新输入并完成验证');
                captchaObj.reset(); // 调用该接口进行重置
            }
        });
    });
});

showCaptcha()

当product为bind类型时，可以调用该接口进行验证。

这种形式的好处是，允许开发者先对用户所填写的数据进行检查，没有问题之后在调用验证接口。 但是要特别注意调用的时机，在验证码还未进入onReady状态，调用此方法不会有任何反应。

<div id="btn">提交按钮</div>
<script>
initGeetest4({
    // 省略配置参数

    product: 'bind'
}, function (captchaObj) {
    // 省略其他方法的调用

    document.getElementById('btn').addEventListener('click', function () {
        if (check()) { // 检查是否可以进行提交
            captchaObj.showCaptcha();
        }
    });
    captchaObj.onSuccess(function () {
        // 用户验证成功后，进行实际的提交行为
        // todo
    })
});
</script>

onReady(callback)

监听验证按钮的 DOM 生成完毕事件。参数 callback 为函数类型。

根据 onReady 事件隐藏“加载验证提示语”

<div id="captcha-box">
    <div id="loading-tip">加载中，请稍后...</div>
</div>
<script>
    initGeetest4({
        // 省略配置参数
    }, function (captchaObj) {
        captchaObj.appendto('#captcha-box');

        // 省略其他方法的调用

        captchaObj.onReady(function () {
            // DOM 准备好后，隐藏 #loading-tip 元素
            // 仅作示例用，用您适合的方式隐藏即可
            document.getElementById('loading-tip').style.display = 'none';
        });
    });
</script>

onNextReady(callback)

监听验证下一步资源的加载完毕事件。参数 callback 为函数类型。

<div id="captcha-box">
    <div id="loading-tip">加载中，请稍后...</div>
</div>
<script>
    initGeetest4({
        // 省略配置参数
    }, function (captchaObj) {
        captchaObj.appendto('#captcha-box');

        // 省略其他方法的调用

        captchaObj.onNextReady(function () {
            
        });
    });
</script>

onSuccess(callback)

监听验证成功事件。参数 callback 为函数类型。

监听验证成功事件，进行二次验证

initGeetest4({
    // 省略配置参数
}, function (captchaObj) {
    // 省略其他方法的调用

    captchaObj.onSuccess(function () {
        var result = captchaObj.getValidate();

        // ajax 伪代码，进行二次验证
        ajax('/login', {
            lot_number: result.lot_number,
            captcha_output: result.captcha_output,
            pass_token: result.pass_token,
            gen_time: result.gen_time,

            // 其他服务端需要的数据，比如登录时的用户名和密码
        }, function (data) {
            // 根据服务端二次验证的结果进行跳转等操作
        });
    });
});

onFail(callback)

监听验证成功事件。参数 callback 为函数类型。 failObj操作失败对象包含： captcha_id、captcha_type、challenge，后续可能增加。 监听验证码操作失败事件，统计用户操作失败次数

initGeetest4({
    // 省略配置参数
}, function (captchaObj) {
    // 省略其他方法的调用

    captchaObj.onFail(function (failObj) {
        //  对错误信息做一些统计
    });
});

onError(callback)

监听验证出错事件。参数 callback 为函数类型。 静态资源加载失败、网络不给力等验证码能捕获到的错误(参考ErrorCode)，都会触发onError回调。 该错误对象包含三部分： code：错误码、msg：提示信息、desc： 该对象包含detail属性，描述具体的错误信息，后续可能会增加

当出错事件触发时，可以提示用户刷新页面重试。

initGeetest4({
    // 省略配置参数
}, function (captchaObj) {
    // 省略其他方法的调用

    captchaObj.onError(function (error) {
        // 出错啦，可以提醒用户稍后进行重试
        // error 包含error_code、msg
        // {code: '60000',msg:"用户配置错误"，desc:{ detail: "用户id缺少"} }
    });
});

onClose(callback)

当用户关闭弹出来的验证时，会触发该回调。

initGeetest4({
    // 省略配置参数

    product: 'bind'
}, function (captchaObj) {
    // 省略其他方法的调用

    captchaObj.onClose(function () {
        // 用户把验证关闭了，这时你可以提示用户需要把验证通过后才能进行后续流程
    });
});

destroy

销毁验证实例，验证相关UI以及验证注册的事件监听器都会被移除。

initGeetest4({
    // 省略配置参数

    product: 'bind'
}, function (captchaObj) {
    // 省略其他方法的调用

    captchaObj.onSuccess(function () {
        var result = captchaObj.getValidate();

        // ajax 伪代码
        ajax('/login', {
            lot_number: result.lot_number,
            captcha_output: result.captcha_output,
            pass_token: result.pass_token,
            gen_time: result.gen_time,

            username: 'xxx',
            password: 'xxx'

            // 其他服务端需要的数据，比如登录时的用户名和密码
        }, function (data) {
            // 根据服务端二次验证的结果进行跳转等操作
            if (data.status === 'fail') {
                alert('用户名或密码错误，请重新输入并完成验证');
                captchaObj.reset(); // 调用该接口进行重置
            }else if(data.status === 'success'){
                // 结合业务逻辑，判断是否需要移除验证
                captchaObj.destroy();
                captchaObj = null;
            }
        });
    });
});

ErrorCode

Geelab 行为验证 Web 端业务错误代码

ErrorCodeDescription
60001配置参数captcha_id有误：请检查初始化时传入的配置参数captcha_id（对应申请时的ID）
60002传给 appendTo 接口的参数有误，只接受 id 选择器和 DOM 元素
60100/load请求报错：1.请保持网络畅通；2.检查初始化时传入的配置参数captchaId
60101/verify请求报错：1.请保持网络畅通；2.请联系 Geelab 客服
60200皮肤加载失败：1.请保持网络畅通；2.请联系 Geelab 客服
60201语言包加载失败：1.请保持网络畅通；2.请联系 Geelab 客服
60202验证图片加载失败：1.请保持网络畅通；2.请联系 Geelab 客服
60204（gacptcha4）js资源加载超时：1.请保持网络畅通；2.请联系 Geelab 客服
60205(gct4)js资源加载超时：1.请保持网络畅通；2.请联系 Geelab 客服
60500服务端forbidden： 请联系 Geelab 客服

API 指南

完整的 API 接口文档

iOS

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

On this page

配置参数productnativeButtonlanguageprotocoltimeoutuserInfo初始化Web API方法appendTo(position)getValidate()reset()showCaptcha()onReady(callback)onNextReady(callback)onSuccess(callback)onFail(callback)onError(callback)onClose(callback)destroyErrorCode