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"
                 }// 提交至業務系統...
                 })})

此代碼塊在浮窗中顯示