Web SDK 集成指南

兼容性

项目	说明
兼容性	IE9+、Chrome、Firefox、Safari、Opera、主流手机浏览器、iOS 及 Android上的内嵌Webview

验证形式

["slide","icon","nine","match"]

              
              ["slide","icon","nine","match"]

此代码块在浮窗中显示

当前支持形式：

名称	描述
slide	滑动拼图
icon	依次点击图标
nine	九宫格
match	消消乐

快速开始

引入

gt4.js文件

由 EngageLab 提供

引入gt4.js会在全局挂载初始化函数initGeetest。

              
              <script src="https://captcha-stat.engagelab.com/www/gt4.js"></script>

此代码块在浮窗中显示

初始化验证码

💡 提示

初始化之前的需要从服务端获取获取验证ID，详见配置参数

通过initGeetest函数得到验证码实例。该函数第一个参数为验证码配置参数，第二个参数为初始化完成后的回调函数 。

var config = { captchaId:'xxxx',// 验证ID apiServers:['https://captcha-api.engagelab.com'],// 验证服务器地址列表，必须按要求配置 staticServers:['https://captcha-stat.engagelab.com/www/js']// 静态资源服务器地址列表，必须按要求配置 } /** * @desc 初始化完成的回调 * @param { Object } gt 验证码实例 */ var callback=function(gt){ // 根据验证码实例处理相关业务，如唤醒验证码窗，监听验证成功事件... } initGeetest(config, callback)

              
              var config = {
    captchaId:'xxxx',// 验证ID
    apiServers:['https://captcha-api.engagelab.com'],// 验证服务器地址列表，必须按要求配置
    staticServers:['https://captcha-stat.engagelab.com/www/js']// 静态资源服务器地址列表，必须按要求配置
    }
/**
 * @desc 初始化完成的回调
 * @param { Object } gt 验证码实例
 */
var callback=function(gt){
  // 根据验证码实例处理相关业务，如唤醒验证码窗， 监听验证成功事件...
  }
  initGeetest(config, callback)

此代码块在浮窗中显示

唤醒验证窗

💡 提示

搭配配置参数product，唤醒验证窗的方式有两种：

点击提供的内置按钮唤醒。（product值不为bind）
调用验证码实例的showCaptcha方法。（product值为bind）

<div id="captch_wrap" class="captch-wrap"></div> var config = { captchaId:'xxxx',// 验证ID apiServers:['https://captcha-api.engagelab.com'],// 验证服务器地址列表，必须按要求配置 staticServers:['https://captcha-stat.engagelab.com/www/js'],// 静态资源服务器地址列表，必须按要求配置 product:'bind'// 场景二 } /** * @desc 初始化完成的回调 * @param { Object } gt 验证码实例 */var callback=function(gt){ gt.onReady(function(){ // 场景一，使用engagelab提供的内置按钮唤醒验证窗 // 将内置按钮添加到指定区域 gt.appendTo("#captch_wrap") // 场景二，自定义唤醒验证窗 // 在指定事件中调用实例的showCaptcha方法 // 例如验证码准备就绪后立即唤醒 gt.showCaptcha() }) } initGeetest(config, callback)

              
               <div id="captch_wrap" class="captch-wrap"></div>
 var config = {
    captchaId:'xxxx',// 验证ID
    apiServers:['https://captcha-api.engagelab.com'],// 验证服务器地址列表，必须按要求配置
    staticServers:['https://captcha-stat.engagelab.com/www/js'],// 静态资源服务器地址列表，必须按要求配置
    product:'bind'// 场景二
}
/**
 * @desc 初始化完成的回调
 * @param { Object } gt 验证码实例
 */var callback=function(gt){
    gt.onReady(function(){
      // 场景一，使用engagelab提供的内置按钮唤醒验证窗
      // 将内置按钮添加到指定区域
         gt.appendTo("#captch_wrap")
      // 场景二，自定义唤醒验证窗
      // 在指定事件中调用实例的showCaptcha方法
      // 例如验证码准备就绪后立即唤醒
        gt.showCaptcha()
        })
        }
      initGeetest(config, callback)

此代码块在浮窗中显示

获取验证结果

/** * @desc 初始化完成的回调 * @param { Object } gt 验证码实例 */ var callback = function(gt){ // 唤醒验证窗... // 监听验证结果 gt.onSuccess(function(res){ console.log(res) }) } initGeetest({...}, callback)

              
              /**
 * @desc 初始化完成的回调
 * @param { Object } gt 验证码实例
 */
var callback = function(gt){
// 唤醒验证窗...
// 监听验证结果
    gt.onSuccess(function(res){
        console.log(res)
    })
}
initGeetest({...}, callback)

此代码块在浮窗中显示

配置参数

参数	类型	描述	默认值
captchaId	string	验证 id，engagelab后台申请得到	必传项｜
product	string	验证窗展示方式，可选值：float popup bind	float
language	string	优先采用传入值，其次跟随当前浏览器语言，无法正确匹配前两项值会使用默认值	zh
protocol	string	网络协议	//
apiServers	array	验证请求服务地址(不含协议)，必须配置为['https://captcha-api.engagelab.com']	-
staticServers	array	验证所需的静态资源服务地址(不含协议)，必须配置为['https://captcha-stat.engagelab.com/www/js']	-
post	boolean	设置为true时，请求方式为ajax, 否则为jsonp	false
showSuccessTip	boolean	product为bind时，控制验证成功的通知窗	true
riskType	string	指定滑动，点击等验证形式（仅当后台系统的验证模式配置设为风控融合模式时生效）	-
timeout	number	验证请求的超时时间	30000
offlineCb	function	自定义宕机处理函数	-
onError	function	初始化验证码之前的错误捕获	-
mask	Object	验证窗遮罩的配置
nativeButton	Object	内置按钮相关配置
toolbar	Array	工具栏配置
clientType	string	客户端类型，可选值：web
width	string	设置验证窗宽度。最大宽为340px （验证窗高度自适应，宽高比约为	340px
zoom	number	适用于特殊场景的缩放值,不受最大值限制（火狐浏览器固定值为1）	1

mask对象配置

参数	类型	描述	默认值
backgroundColor	string	合法色值	-
outside	boolean	点击验证码区域外关闭验证	-

nativeButton对象配置

参数	类型	描述	默认值
width	string	内置唤醒按钮宽度	-
height	string	内置唤醒按钮高度	-

toolbar数组配置

initGeetest({...,toolbar:['close','refresh']},function(){...})

              
              initGeetest({...,toolbar:['close','refresh']},function(){...})

此代码块在浮窗中显示

language配置

initGeetest({...,language:'zh'},function(){...})

              
              initGeetest({...,language:'zh'},function(){...})

此代码块在浮窗中显示

有效值	类型	描述
close	string	关闭验证窗按钮
refresh	string	刷新验证窗按钮

language(18种)

可选值	语言
ara	阿拉伯语
deu	德语
eng	英文
fra	法语
ind	印尼语
jpn	日语
kor	韩语
msa	马来语
pon	巴西葡语
por	欧洲葡语
rus	俄语
spa	西班牙语
tha	泰语
udm	维吾尔语
vie	越南语
zh	中文简体
zho-hk	中文繁体（中国香港）
zho-tw	中文繁体（中国台湾）

行为验证宕机模式

宕机模式，是为了处理极端情况下，保障验证码验证流程异常不影响正常业务流程而设置的一种应急处理模式

宕机模式主要是网站主服务器连接不上验证服务器，出现连接超时等状况。

宕机模式下所有的验证流程均不经过验证服务器，需接入方添加校验逻辑或有产品降级方案。

验证服务器进入宕机模式时，

客户端流程不变，触发验证码会立即通过，进入onSuccess。

业务系统向验证码系统发二次校验，超时则确认为宕机。

initGeetest({...},function(gt){... gt.onSuccess(function(res){ console.log(res)// 验证成功的结果示例值如下 { captcha_id: "59bbe0f128f0624fdd185a6a2207aa54", captcha_output: "X000Q5p.....i-SFRyH1", client_type: "web", gen_time: "1648204854", lot_number: "200e2e58e1d3a6906e08cc9ff5c6e0b5", offline: true, pass_token: "e000b4dc372c1397976f7b8f12d66ea8d5c993ab2db5810258e835429f6fa4ae" }// 提交至业务系统... })})

              
              initGeetest({...},function(gt){...
    gt.onSuccess(function(res){
        console.log(res)// 验证成功的结果示例值如下
        {  captcha_id: "59bbe0f128f0624fdd185a6a2207aa54",
             captcha_output: "X000Q5p.....i-SFRyH1",
          client_type: "web",
              gen_time: "1648204854",
                lot_number: "200e2e58e1d3a6906e08cc9ff5c6e0b5",	
              offline: true,
                  pass_token: "e000b4dc372c1397976f7b8f12d66ea8d5c993ab2db5810258e835429f6fa4ae"
                 }// 提交至业务系统...
                 })})

此代码块在浮窗中显示