Web和H5用戶端V3架構接入 - Captcha

在控制台添加驗證情境後，需要在使用驗證功能的Web或H5頁面中，整合驗證碼初始化代碼，實現用戶端接入。本文介紹如何整合驗證碼初始化代碼。

前提條件

已開通阿里雲驗證碼2.0服務。
已建立接入方式為Web/H5的驗證情境。

方法概述

業務用戶端接入驗證碼2.0只需要3步：

添加全域變數AliyunCaptchaConfig。
動態引入驗證碼JS。
調用初始化方法進行驗證碼初始化。

說明

如果您的業務架構是V2版本，請參見Web和H5用戶端V2架構接入。
微信小程式目前僅支援接入V2架構，暫不支援接入V3架構。

操作步驟

步驟一：添加全域變數AliyunCaptchaConfig

在引入阿里雲驗證碼JS指令碼的位置之前，或在HTML的head標籤最前的位置添加一個script指令碼，儲存一個含有region和prefix參數的全域變數AliyunCaptchaConfig即可。

<script>
  window.AliyunCaptchaConfig = {
    // 必填，驗證碼樣本所屬地區，支援中國內地（cn）、新加坡（sgp）
    region: "cn",
    // 必填，身份標。開通阿里雲驗證碼2.0後，您可以在控制台概覽頁面的執行個體基本資料卡片地區，擷取身份標
    prefix: "******",
  };
</script>

重要

身份標位於概览 > 累计开通时间 > 身份标（prefix）地區，如下圖所示：

步驟二：動態引入驗證碼JS

Web頁面需動態引入驗證碼JS，在業務需要驗證時，喚起驗證碼進行驗證。

說明

必須動態引入驗證碼JS，若通過其他方式規避動態載入（例如拉取JS代碼本地部署），會導致驗證碼無法正常更新，無法保證安全能力，甚至引起誤攔截或者產生相容性問題。

<script
  type="text/javascript"
  src="https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js"
></script>

步驟三：調用初始化方法進行驗證碼初始化。

初始化方法initAliyunCaptcha除了在必要情境下（如初始化參數發生變化）外，不支援重複調用。初始化過程中如果返回失敗，請參見用戶端初始化報錯說明進行排查。

<script type="text/javascript">
  var captcha;
  // 除region和prefix以外的參數
  window.initAliyunCaptcha({...});
</script>

程式碼範例

說明

驗證碼JS載入盡量前置，目的是採集更完整的環境和裝置資訊，驗證碼JS載入和驗證請求之間間隔需要大於2s。
為保障圖片資源載入更快，初始化載入的時機盡量前置，初始化和驗證請求間隔大於2s，目的是載入驗證碼相關資源，使圖片資源載入更快。
在用戶端的原始碼中預留驗證碼頁面元素，即element、button參數所指向的DOM元素，如下例中的<div id="captcha-element"></div>。

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="data-spm" />
    <!--1.在引入阿里雲驗證碼JS指令碼的位置之前，或者在html的head標籤最前的位置添加一個script指令碼，裡面儲存一個含有region和prefix參數的全域變數AliyunCaptchaConfig即可-->
    <script>
      window.AliyunCaptchaConfig = {
        // 必填，驗證碼樣本所屬地區，支援中國內地（cn）、新加坡（sgp）
        region: "cn",
        // 必填，身份標。開通阿里雲驗證碼2.0後，您可以在控制台概覽頁面的執行個體基本資料卡片地區，擷取身份標
        prefix: "xxxxxx",
      };
    </script>
    <!--2.整合主JS-->
    <script
      type="text/javascript"
      src="https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js"
    ></script>
  </head>

  <body>
    <div id="captcha-element"></div>
    <!--預留的驗證碼元素，用於配置初始化函數中的element參數-->
    <button id="button" class="btn">登入</button>
    <!--彈出式下，用於觸發驗證碼彈窗的元素-->
    <!--3.建立一個<script>標籤，用於調用驗證碼初始化函數initAliyunCaptcha-->
    <script type="text/javascript">
      var captcha;
      // 彈出式，除region和prefix以外的參數
      window.initAliyunCaptcha({
        // 情境ID。根據步驟二建立驗證情境後，您可以在驗證碼情境列表，擷取該情境的情境ID
        SceneId: "******",
        // 驗證碼模式，popup表示彈出式，embed表示嵌入式。無需修改
        mode: "popup",
        // 頁面上預留的渲染驗證碼的元素，與原代碼中預留的頁面元素保持一致。
        element: "#captcha-element",
        // 觸發驗證碼彈窗或無痕驗證的元素
        button: "#button",
        // 驗證碼驗證通過回呼函數
        success: function (captchaVerifyParam) {
          // 入參為驗簽captchaVerifyParam
          // 1.向後端發起業務請求進行驗證碼驗簽captchaVerifyParam校正
          // 2.根據校正結果來進行業務處理
          // 3.如業務需要重新進行驗證碼驗證，調用驗證碼初始化方法initAliyunCaptcha重新初始化驗證碼
        },
        // 驗證碼驗證不通過回呼函數
        fail: function (result) {
          // 入參為不通過資訊
          // 正常驗證有效期間內不需要做任何操作，驗證碼自動重新整理，重新進行驗證
          console.error(result);
        },
        // 綁定驗證碼執行個體回呼函數，該回調會在驗證碼初始化成功後調用
        getInstance: function (instance) {
          captcha = instance;
        },
        // 滑塊驗證和一點即過的驗證形態觸發框體樣式，支援自訂寬度和高度，單位為px。
        slideStyle: {
          width: 360,
          height: 40,
        },
        // ...其他參數，參考initAliyunCaptcha參數說明
      });
    </script>
  </body>
</html>

參數說明

AliyunCaptchaConfig參數說明

參數

類型

是否必填

預設值

描述

region

String

是

驗證碼執行個體所屬地區。取值：

cn：表示中國內地。
sgp：新加坡。

重要

如果用戶端region是cn，服務端請調用中國內地地址；如果是sgp，請調用新加坡地址。
產品在中國內地（華東2（上海））和新加坡分別設定了管控中心平面，根據客戶自行配置的調用參數，用戶端採集的行為資料、裝置資料等將回傳對應中心處理，主要實現安全驗證功能。

prefix

String

是

無

驗證碼身份標識，開通驗證碼2.0後在控制台概覽頁面右上方可擷取該值。

initAliyunCaptcha參數說明

在頁面載入完成後儘早調用驗證碼初始化方法。

參數	類型	是否必填	預設值	描述
SceneId	String	是	無	驗證碼情境ID，建立驗證情境後可擷取該值。
mode	String	是	無	驗證碼模式，可選項： popup：表示彈出式。 embed：表示嵌入式。重要無痕驗證不支援嵌入式驗證，請使用彈出式驗證接入。
element	String	是	無	頁面上預留渲染驗證碼的元素，與原始碼中預留的頁面元素保持一致。
button	String	是	無	觸發驗證碼彈窗或無痕驗證的元素，點擊後彈出驗證碼或觸發無痕驗證。具體取值與用戶端body中的button參數值一致。
success	Function	是	無	驗證碼驗證通過回呼函數，透出驗證參數，客戶可在該回呼函數中擷取`CaptchaVerifyParam`，請求客戶服務端進行驗證`CaptchaVerifyParam`校正。
fail	Function	否	無	驗證碼驗證失敗回呼函數，透出驗證失敗錯誤碼。
getInstance	Function	是	getInstance	綁定驗證碼執行個體回呼函數，該回調會在驗證碼初始化成功後調用，固定寫法如下： `function getInstance(instance) { captcha = instance; }`
slideStyle	Object	否	{ width: 360, height: 40 }	滑塊驗證和一點即過的驗證形態觸發框體樣式，支援自訂寬度和高度，單位為px。相容歷史參數名。重要由於驗證碼需要通過滑動採集足夠多的資訊用於策略模型判斷，所以，建議您將滑塊的寬度（width值）最小設定為320 px。如果width值小於320 px，系統會按照320 px進行配置。該參數並不適用於拼圖驗證和映像複原驗證。如果您使用的是拼圖驗證碼，由於拼圖驗證碼的映像尺寸和驗證答案是預設固定的，請不要複寫 CSS 強行修改樣式，否則會導致驗證異常。
language	String	否	cn	驗證碼2.0支援的語言類型。
timeout	Number	否	5000	驗證碼初始化請求單次請求逾時時間，單位為毫秒（ms）。
rem	Number	否	1	對驗證碼UI進行整體縮放。請傳入正數，如0.5是縮小一倍，2是放大一倍。說明參數rem主要針對移動端瀏覽器使用。
onError	Function	否	無	驗證碼初始化介面請求和驗證碼資源載入失敗、逾時的錯誤回呼函數。固定寫法如下： `function onError(errorInfo) { const {code, msg} = errorInfo; console.log(code, msg); }`
onClose	Function	否	無	驗證碼彈窗關閉時觸發的回呼函數。
captchaLogoImg	String	否	無	一點即過、拼圖驗證或映像複原嵌入式觸發按鈕右側的企業Logo更換參數，為圖片URL連結或者base64格式資料。
dualStack	Boolean	否	false	初始化請求網域名稱、驗證請求網域名稱是否開啟支援雙棧，取值： false：只支援IPv4。 true：同時支援IPv4和IPv6。
UserCertifyId	String	否	無	客戶自訂產生的certifyId。非必傳，用於客戶期望通過驗證碼透傳參數關聯商務程序情境，在服務端驗簽介面返回該參數，支援客戶進行校正。重要參數格式標準：身份標（prefix）_10位隨機字串（包含大小寫字母和數字）。樣本值：`1q5***_7G47iByes3`。程式碼範例詳見UserCertifyId參數程式碼範例。
showErrorTip	Boolean	否	true	是否顯示網路品質不佳時訪問異常的錯誤提醒。
delayBeforeSuccess	Boolean	否	true	驗證成功後，是否延遲1s觸發success回呼函數，預設為true。
EncryptedSceneId	String	否	無	加密後的 SceneId。建立驗證情境後可獲得原始 SceneId。使用控制台頒發的密钥（ekey），按照文檔中的加密流程對該 SceneId 進行加密，最終得到的加密字串即為加密後的 SceneId。
zIndex	Number	否	無	驗證碼元素區塊層級，當前預設1000000，可以通過該參數進行重設。

rem參數程式碼範例

const customWidth = 360;
function initCaptcha(rem) {
  window.initAliyunCaptcha({
    SceneId: "xxxxxx",
    mode: "popup",
    element: "#captcha-element",
    button: "#captcha-button",
    success: success,
    fail: fail,
    getInstance: getInstance,
    slideStyle: {
      width: customWidth,
      height: 40,
    },
    language: "cn",
    rem: rem,
  });
}

const pageWidth = window.innerWidth;
if (pageWidth <= customWidth) {
  const rem = Math.floor(pageWidth / customWidth * 100) / 100;
  initCaptcha(rem);
}

UserCertifyId參數程式碼範例

// 範例程式碼
function generateRandomString(length) {
  const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
  let result = '';
  const charactersLength = characters.length;
  for (let i = 0; i < length; i++) {
    result += characters.charAt(Math.floor(Math.random() * charactersLength));
  }
  return result;
}

const initCaptcha = async () => {
  const prefix = 'xxxxxx';
  const UserCertifyId = prefix + '_' + generateRandomString(10);

  // 阿里雲驗證碼初始化邏輯
  window.initAliyunCaptcha({
    // 按照要求格式產生自訂的certifyId傳入初始化方法
    UserCertifyId: UserCertifyId,
    // ...其他參數，參考initAliyunCaptcha參數說明
  });
};

方法調用說明

調用驗證碼執行個體對應方法。

方法名

說明

樣本

使用情境

show

顯示驗證碼元素、蒙板。

captcha.show()

需要自動彈出（不需要點擊按鈕）驗證碼彈框時可以使用。

說明

無痕驗證模式下不支援。

hide

隱藏或關閉驗證碼元素、蒙板。

captcha.hide()

需要自動關閉（不需要點擊按鈕）驗證碼彈框時可以使用。

說明

無痕驗證模式下不支援。

startTracelessVerification

獨立調用無痕驗證方法

captcha.startTracelessVerification()

無痕驗證模式特有，需要自訂業務按鈕綁定事件，支援無痕驗證之前做商務邏輯判斷。

獨立調用無痕驗證程式碼範例

<!doctype html>
<link rel="shortcut icon" href="//www.aliyun.com/favicon.ico" type="image/x-icon" />
<script>
  window.AliyunCaptchaConfig = {
    region: 'cn',
    prefix: 'prefix',
  };
</script>
<script type="text/javascript" src="AliyunCaptcha.js"></script>

<div>
  <button id="login-button" class="login-btn">登入</button>
</div>

<script type="text/javascript">
  var captcha;

  function initCaptcha() {
      window.initAliyunCaptcha({
        // showErrorTip: false,
        delayBeforeSuccess: false,
        SceneId: 'SceneId',
        mode: 'popup',
        element: '#traceless-element',
        success: function(){
          
        },
        getInstance: function(instance;){
          captcha = instance;
        },
        slideStyle: {
          width: 360,
          height: 40,
        },
        language: 'cn',
      });  
    }
  }

  initCaptcha();

  document.getElementById('login-button').onclick = function() {
    // 使用者商務邏輯
    ...
    
    // 用於二次調整彈窗的展示
    captcha.show();
    // 開始無痕驗證
    captcha.startTracelessVerification();

    // 使用者商務邏輯
    ...
  }


</script>

返回資料

在驗證碼2.0接入用戶端V3架構的行為驗證中，驗證碼服務端會在驗證答案是否正確以及判斷是否為機器請求後，將驗證碼Code和其他參數返回給業務用戶端，您可以通過瀏覽器的Network功能查看返回資料，請參見用戶端V3架構返回資料說明。

lQLPJxFSi2GYDIHNBHTNCpawwjNH3sY_CI4IOehh6YNsAQ_2710_1140

Captcha：Web和H5用戶端V3架構接入