> >

配置参数

这里说的配置参数，是指初始化验证时传入的 config 对象（key-value 结构），也就是调用初始化函数 initGeetest4 时所传入的第一个参数的可选参数配置，必需参数请参考部署文档,demo参考4.0适应性验证码demo

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

参数	必填	类型	说明	默认值	可选值
captchaId	Y	string	验证 id，极验后台申请得到
product	N	string	设置下一步验证的展现形式	float	float、popup、bind
nativeButton	N	object	极验按钮样式设置	{ width:’260px’, height:’50px’ }	单位可以是 px，%，em，rem，pt
rem	N	number	设置验证码整体的缩放比例	1	可以根据不同设备传入不同比例值
language	N	string	设置验证界面文字的语言, 如不传默认取浏览器设置的语言，不在支持的列表内，默认使用中文	zho	zho、eng、zho-tw、zho-hk、udm、jpn、ind、kor、rus、ara、spa、pon、por、fra、deu
protocol	N	string	协议头	默认去当前页面的协议头（本地或者混合开发一定要手动设置，否则一般会自动取到file协议)	http://、https://
timeout	N	number	设置验证过程中单个请求超时时间	30000（ms）	大于0的整数
hideBar	N	array	隐藏后续验证界面的关闭按钮、刷新按钮	[]	[‘close’,’refresh’]
mask	N	object	弹窗相关配置项，目前包括弹窗背景色、点击验证码区域外是否关闭验证	{ outside:true, bgColor:’#0000004d’ }	outside:false, bgColor:任意合法的css颜色单位都可以
apiServers	N	array	控制api请求的地址	[‘gcaptcha4.geetest.com’]
nextWidth	N	string	验证码弹窗的宽度（此参数设置后，验证码弹窗将不会自动根据网页内容宽度调整）
riskType	N	string	结合风控融合，指定验证形式
hideSuccess	N	boolean	隐藏bind展现形式下的验证成功弹窗 (注：仅product参数值为bind情况下生效)	false	true
offlineCb	N	function	宕机模式处理函数,默认为极验的宕机，设置了此函数代表想自定义宕机逻辑（不会再执行默认的宕机模式）
onError	N	function	初始化验证码之前的错误捕获
userInfo	N	string	客户端信息，例如用户账号、用户手机号、用户名等

`product`

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

目前提供三种展现形式

popup（弹出式）
float（浮动式）
bind（隐藏按钮类型）

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

参数	类型	作用	说明
`bgColor`	string	设置弹出背景的颜色	默认为黑色，可设置任何一种合法的颜色值

各展现形式效果如下。

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`

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

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

注意： 验证图片上的文字是不会根据语言设置来切换的，因为他本身是一张图片，如需要设置图片，可在后台上传自定义图集。

设置为简体中文和英文时的效果图如下：

简体中文：

lang-zh-cn-demo

英文：

lang-en-demo

设置界面语言为英文

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

    language: 'eng'
});

其他更多语言配置效果可参考：https://gt4.geetest.com/

`protocol`

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

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

    protocol: "https://"
});

`timeout`

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

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

    timeout: 10000
});

`userInfo`

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

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

    userInfo: "user@geetest.com"
});

初始化

使用初始化函数 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;
            }
        });
    });
});