Web和H5用戶端V2架構接入 -

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

前提條件

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

V2驗證架構時序圖

滑块验证、拼图验证、一点即过和图像复原

時序圖說明：

客戶在業務用戶端初始化驗證碼，業務用戶端會請求驗證碼服務端，擷取驗證碼資源（例如圖片、題目等）。
如果請求失敗，客戶可以通過業務用戶端擷取的請求報錯資訊來排查失敗具體原因並進行相應調整或修複。
使用者在網頁完成驗證碼互動（例如滑塊、拼圖、一點即過和映像複原）和應用業務互動（例如登入、註冊等）。
完成後，業務用戶端會發送驗證碼參數和業務參數到商務服務端。
商務服務端調用VerifyIntelligentCaptcha介面後，會向驗證碼服務端發起驗證請求，進行風險諮詢。
驗證碼服務端判斷驗證風險，並將驗證結果返回給商務服務端。
商務服務端結合商務邏輯處理業務。完成後，向業務用戶端返回驗證結果和業務處理結果。
用戶端頁面顯示提示資訊，進行業務處理。
如果驗證不通過，驗證碼會重新整理，流程返回步驟1。

无痕验证

時序圖說明：

客戶在業務用戶端初始化驗證碼，業務用戶端會請求驗證碼服務端，擷取驗證碼資源（例如圖片、題目等）。
如果請求失敗，客戶可以通過業務用戶端擷取的請求報錯資訊來排查失敗具體原因並進行相應調整或修複。
使用者在業務用戶端完成應用業務互動（例如登入、註冊等）。
完成後，業務用戶端會發送無痕驗證參數和業務參數到商務服務端。
商務服務端調用VerifyIntelligentCaptcha介面後，會向阿里雲服務端發起驗證請求，進行風險諮詢。
阿里雲服務端判斷驗證風險，並將驗證結果返回給商務服務端。
商務服務端結合商務邏輯處理業務。
- 如果使用者無風險，驗證流程結束。
- 如果使用者存在風險，觸發二次驗證。
  1. 使用者在網頁完成驗證碼互動（例如滑塊、拼圖、一點即過和映像複原）和應用業務互動（例如登入、註冊等）。
    完成後，業務用戶端會發送驗證碼參數和業務參數到商務服務端。
  2. 商務服務端調用VerifyIntelligentCaptcha介面後，會向阿里雲服務端發起驗證請求，進行風險諮詢。
  3. 阿里雲服務端判斷驗證風險，並將驗證結果返回給商務服務端。
  4. 商務服務端結合商務邏輯處理業務。完成後，向業務用戶端返回驗證結果和業務處理結果。
  5. 用戶端頁面顯示提示資訊，進行業務處理。
    如果驗證不通過，用戶端頁面會重新喚起驗證碼，流程返回步驟i。

整合驗證碼初始化代碼

Web或H5頁面支援彈出式、嵌入式兩種形態。下文以登入情境為例，介紹如何在用戶端原始碼中整合驗證碼。

在用戶端的原始碼中預留驗證碼頁面元素，即element、button參數所指向的DOM元素，如下例中的<div id="captcha-element"></div>。建議將業務模組容器的高度設定為自適應，以免後續切換驗證碼類型時因為驗證碼高度變化而造成元素超出容器高度。這裡以登入情境為例。

重要

整合後，如果您在控制台修改情境配置（例如驗證碼形態），無需再次調整初始化參數和頁面結構，程式會根據配置按需載入。

// 用戶端原代碼舉例
 const button = document.getElementById('button');
 button.onclick = function () {
   // 請求後端介面...
   const result = await getWithParams('xx', { 
       yourBizParam... // 業務參數
   });                
   const { bizResult } = result;
   if (bizResult) {
     // 跳轉到對應頁面。此處以跳轉到https://www.aliyun.com/頁面為例
     window.location.href = 'https://www.aliyun.com/';
   }
 }

// 用戶端body中的代碼
<div id="space-semantic">
    <div id="embed-wrapper">
        <h2>彈出式</h2>
        <div class="embed-wrapper">
            <div>
                <label>使用者名稱：</label>
                <input id="username-embed" class="biz-input">
            </div>
            <div>
                <label>密碼：</label>
                <input id="password-embed" type="password" class="biz-input">
            </div>
            <div id="captcha-element"></div>  //預留的驗證碼頁面元素，用於配置初始化函數中的element參數
            <button id="button" class="login-btn">登入</button>
        </div>
    </div>
</div>

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

重要

必須動態引入驗證碼JS，若通過其他方式規避動態載入（例如拉取JS代碼本地部署），會導致驗證碼無法正常更新，無法保證安全能力，甚至引起誤攔截或者產生相容性問題。
驗證碼JS載入盡量前置，目的是採集更完整的環境和裝置資訊，驗證碼JS載入和驗證請求之間間隔需要大於2s。
為保障圖片資源載入更快，初始化載入的時機盡量前置，初始化和驗證請求間隔大於2s，目的是載入驗證碼相關資源，使圖片資源載入更快。
初始化方法initAliyunCaptcha除了在必要情境下（如初始化參數發生變化）外，不支援重複調用。

彈出式

<!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>
        <!--3.建立一個<script>標籤，用於調用驗證碼初始化函數initAliyunCaptcha-->
        <script type="text/javascript">
            var captcha;
            // 彈出式，除region和prefix以外的參數
            window.initAliyunCaptcha({
                // 情境ID。根據步驟二建立驗證情境後，您可以在驗證碼情境列表，擷取該情境的情境ID
                SceneId: 'c9h3****',
                // 驗證碼模式。popup表示要整合的驗證碼模式為彈出式。無需修改
                mode: 'popup',
                //頁面上預留的渲染驗證碼的元素，與原代碼中預留的頁面元素保持一致。
                element: '#captcha-element',
                // 觸發驗證碼彈窗的元素。button表示單擊登入按鈕後，觸發captchaVerifyCallback函數。您可以根據實際使用的元素修改element的值
                button: '#button',
                // 業務請求(帶驗證碼校正)回呼函數，無需修改
                captchaVerifyCallback: captchaVerifyCallback,
                // 業務請求結果回呼函數，無需修改
                onBizResultCallback: onBizResultCallback,
                // 綁定驗證碼執行個體函數，無需修改
                getInstance: getInstance,
                // 滑塊驗證碼樣式，支援自訂寬度和高度，單位為px。其中，width最小值為320 px
                slideStyle: {
                    width: 360,
                    height: 40,
                },
                // 驗證碼語言類型，支援簡體中文（cn）、繁體中文（tw）、英文（en）
                language: 'cn',
            });
            function getInstance(instance) {
                captcha = instance
            }
            async
            function captchaVerifyCallback(captchaVerifyParam) {
                // 1.向後端發起業務請求，擷取驗證碼驗證結果和業務結果
                const result = await xxxx('http://您的業務請求地址', {
                    // 驗證碼參數
                    captchaVerifyParam: captchaVerifyParam,
                   // 業務參數
                    yourBizParam... 
                });

                // 2.構造標準返回參數
                const verifyResult = {
                    // 驗證碼驗證是否通過，boolean類型，必選。
                    captchaResult: result.captchaVerifyResult,
                    // 業務驗證是否通過，boolean類型，可選；若為無業務驗證結果的情境，bizResult可以為空白。
                    bizResult: 從result擷取您的業務驗證結果,

                };
                return verifyResult;
            }

            // 業務請求驗證結果回呼函數
            function onBizResultCallback(bizResult) {
                if (bizResult === true) {
                    // 如果業務驗證通過，跳轉到對應頁面。此處以跳轉到https://www.aliyun.com/頁面為例
                    window.location.href = 'https://www.aliyun.com/';
                } else {
                    // 如果業務驗證不通過，給出不通過提示。此處不通過提示為業務驗證不通過！
                    alert('業務驗證不通過！');
                }
            }
        </script>
    </body>
</html>

嵌入式

<!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>
        <!-- 3.建立一個<script>標籤，用於調用驗證碼初始化函數initAliyunCaptcha -->
        <script type="text/javascript">
            var captcha;
            // 嵌入式，除region和prefix以外的參數
            window.initAliyunCaptcha({
                // 情境ID。通過步驟一添加驗證情境後，您可以在驗證碼情境列表，擷取該情境的情境ID
                SceneId: 'c9h3****',
                // 驗證碼模式。embed表示要整合的驗證碼模式為嵌入式。無需修改
                mode: 'embed',
                // 頁面上預留的渲染驗證碼的元素，與原代碼中預留的頁面元素保持一致。
                element: '#captcha-element',
                // 觸發業務請求的元素。button表示單擊登入按鈕後，觸發captchaVerifyCallback函數。您可以根據實際使用的元素修改element的值
                button: '#button',
                // 業務請求(帶驗證碼校正)回呼函數，無需修改
                captchaVerifyCallback: captchaVerifyCallback,
                // 業務請求結果回呼函數，無需修改
                onBizResultCallback: onBizResultCallback,
                // 綁定驗證碼執行個體函數，無需修改
                getInstance: getInstance,
                // 滑塊驗證碼樣式，支援自訂寬度和高度，單位為px。其中，width最小值為320 px
                slideStyle: {
                    width: 360,
                    height: 40,
                },
                // 驗證碼語言類型，支援簡體中文（cn）、繁體中文（tw）、英文（en）
                language: 'cn',
                // 完成驗證後，是否立即發送驗證請求（調用captchaVerifyCallback函數）
                immediate: false,
            });

            // 綁定驗證碼執行個體函數。該函數為固定寫法，無需修改
            function getInstance(instance) {
                captcha = instance;
            }

            // 業務請求(帶驗證碼校正)回呼函數
            /**
              * @name captchaVerifyCallback
              * @function
              * 請求參數：由驗證碼指令碼回調的驗證參數，不需要做任何處理，直接傳給服務端即可
              * @params {string} captchaVerifyParam
              * 返回參數：欄位名固定，captchaResult為必選；如無業務驗證情境時，bizResult為可選
              * @returns {{captchaResult: boolean, bizResult?: boolean|undefined}}
              */
            async
            function captchaVerifyCallback(captchaVerifyParam) {
                // 1.向後端發起業務請求，擷取驗證碼驗證結果和業務結果
                const result = await xxxx('http://您的業務請求地址', {
                    // 驗證碼參數
                    captchaVerifyParam: captchaVerifyParam,
                    // 業務參數
                    yourBizParam... 
                });

                // 2.構造標準返回參數
                const verifyResult = {
                    // 驗證碼驗證是否通過，boolean類型，必選。
                    captchaResult: result.captchaVerifyResult,
                    // 業務驗證是否通過，boolean類型，可選；若為無業務驗證結果的情境，bizResult可以為空白。
                    bizResult: 從result擷取您的業務驗證結果,

                };
                return verifyResult;
            }

            // 業務請求驗證結果回呼函數
            function onBizResultCallback(bizResult) {
                if (bizResult === true) {
                    // 如果業務驗證通過，跳轉到對應頁面。此處以跳轉到https://www.aliyun.com/頁面為例
                    window.location.href = 'https://www.aliyun.com/';
                } else {
                    // 如果業務驗證不通過，給出不通過提示。此處不通過提示為業務驗證不通過！
                    alert('業務驗證不通過！');
                }
            }
        </script>
    </body>

</html>

其中的captchaVerifyCallback使用ES6文法，如需要使用ES5文法，則參照以下樣本，調用captchaVerifyCallback的第二個參數callback回調，將驗證結果傳入即可：

/**
 * @name captchaVerifyCallback
 * @function
 * @param {String} captchaVerifyParam - 由驗證碼指令碼回調的驗證參數，不需要做任何處理，直接傳給服務端即可
 * @param {Function} callback - 回呼函數，用於處理驗證結果，ES5文法相容
 */
function captchaVerifyCallback(captchaVerifyParam, callback) {
  // 1.向後端發起業務請求，擷取驗證碼驗證結果和業務結果
  requestVerifyResult('http://您的業務請求地址', { 
      captchaVerifyParam: captchaVerifyParam, // 驗證碼參數
      yourBizParam... // 業務參數
  }, function(result) {
      // 2.構造標準返回參數
      var verifyResult = {
          captchaResult: result.captchaVerifyResult,
          bizResult: result.bizResult,
      };    
      // 調用回呼函數，傳入驗證結果
      callback(verifyResult);
  });
}

如果您在接入過程中遇到任何問題，請提交工單聯絡我們。

參數說明

AliyunCaptchaConfig參數說明

參數

類型

是否必填

預設值

描述

region

String

是

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

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

重要

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

prefix

String

是

無

驗證碼身份標識，開通驗證碼2.0後，可擷取該值。

initAliyunCaptcha參數說明

參數	類型	是否必填	預設值	描述
SceneId	String	是	無	驗證碼情境ID，建立驗證情境後可擷取該值。
mode	String	是	無	驗證碼模式。可選項： popup：表示彈出式。 embed：表示嵌入式。重要無痕驗證不支援嵌入式驗證，請使用彈出式驗證接入。
element	String	是	captcha-element	頁面上預留渲染驗證碼的元素，與原始碼中預留的頁面元素保持一致。
button	String	是	無	觸發驗證碼彈窗的元素。具體取值與用戶端body中的button參數值一致。
captchaVerifyCallback	Function	是	captchaVerifyCallback	業務請求（帶驗證碼校正）回呼函數。更多資訊，請參見captchaVerifyCallback。
onBizResultCallback	Function	是	onBizResultCallback	業務請求結果回呼函數，用於設定驗證結果處理邏輯。
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支援的語言類型。
immediate	Boolean	否	false	嵌入式下，完成驗證後，是否立即發送驗證請求（調用captchaVerifyCallback函數）。
timeout	Number	否	5000	驗證碼初始化請求單次請求逾時時間，單位為毫秒（ms）。
rem	Number	否	1	對驗證碼UI進行整體縮放。請傳入正數，如0.5是縮小一倍，2是放大一倍。說明參數rem主要針對移動端瀏覽器使用。
autoRefresh	Boolean	否	true	設定驗證碼驗證通過後是否自動重新整理驗證碼。說明設定為false後，需手動調用執行個體方法重新整理驗證碼，參考常見問題Q4。
onError	Function	否	無	驗證碼初始化介面請求失敗或逾時的錯誤回呼函數。
captchaLogoImg	String	否	無	一點即過形態驗證碼按鈕右側的企業Logo更換參數，為圖片URL連結或者base64格式資料。

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);
}

captchaVerifyCallback參數說明

請求參數

參數	類型	是否必填	預設值	描述
captchaVerifyParam	String	是	captchaVerifyParam	驗證碼參數。由驗證碼指令碼回調的驗證參數，不需要做任何處理，直接傳給服務端即可

返回參數

參數	類型	預設值	描述
captchaResult	Boolean	無	驗證碼驗證是否通過。
bizResult	Boolean	無	業務驗證是否通過。如果為無業務驗證結果的情境，bizResult取值可以為空白。

：Web和H5用戶端V2架構接入