iframe_內嵌接入 - ID Verification

ID Verification 提供 Web SDK，支援在瀏覽器或內嵌 WebView 中實現 eKYC 遠程身分識別驗證。本文介紹 PC 或移動端 H5 網頁通過 iframe 接入 ID Verification 的流程。

前提條件

支援的最低作業系統版本：Android 5+、iOS 11+。
支援的瀏覽器：
- iOS：Safari。從iOS 14.3開始支援Chrome、Firefox、Microsoft Edge和WKWebView。
- 安卓：推薦Chrome60+、Firefox58+。對於Android中的其他瀏覽器，行為可能因裝置而異。
要求的權限：網路和網路攝影機，媒體採集需要HTTPS部署。
採用豎屏模式：手機橫屏狀態可能會引發頁面互動的不適配，建議引導使用者參考頁面提示調整豎屏模式認證。
相容性：受制於瀏覽器安全色性片段化問題，建議在流程設計上引導使用者使用推薦的瀏覽器完成認證。
- 若您在手機應用App內整合該方案，可能會因為內嵌瀏覽器原因無法相容，可以參考App內整合H5移動端SDK相容性配置減少相容性問題或整合Native SDK。
- 若您通過微信公眾號或者小程式整合，由於微信營運審核規則的限制，可能出現無法避免的相容性問題，建議使用純服務端（API）接入方式。

重要

整合過程中，嚴禁對 TransactionUrl 進行任何操作或修改，否則將導致系統報錯。
為保障認證的安全與有效性，認證URL僅限單次使用。重複調用同一URL將觸發報錯。

啟動認證

在代碼中引入如下JS檔案，並調用getMetaInfo函數擷取MetaInfo。
```

<script type="text/javascript" src="https://hkwebcdn.yuncloudauth.com/cdn/verify.js" ></script>
```
說明
- 傳遞 MetaInfo：調用 ID Verification 服務端介面發起認證請求時，必須傳入擷取到的 MetaInfo 值。
- 擷取並載入認證連結：調用商務服務端初始化介面擷取 TransactionUrl，並在瀏覽器中載入該連結以啟動認證流程。

執行 startVerify 啟動認證邏輯。

// TransactionUrl 和 Protocol 通過初始化介面擷取
window.startVerify({ CertifyUrl: TransactionUrl, Protocol: Protocol });

完整程式碼範例

<!DOCTYPE HTML>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <title>Title</title>
        <!-- 引入該JS，全域注入startVerify和getMetaInfo方法 -->
        <script type="text/javascript" src="https://hkwebcdn.yuncloudauth.com/cdn/verify.js"></script>
    </head>
    <body>
        <div></div>
        <script>
    // 在調用ID Verification服務端發起認證請求時需要傳入該MetaInfo值
    let MetaInfo = window.getMetaInfo();

    // 請求認證業務介面擷取TransactionUrl
    fetch('http://<認證初始化介面地址>', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(MetaInfo)
    })
      .then(response => response.json())
      .then(data => {
        console.log('data:', data)
        // 擷取TransactionUrl發起認證
        window.startVerify({CertifyUrl: data.TransactionUrl, Protocol: data.Protocol}).then((res)=>{
        /* startVerify是個 Promise 函數，可以通過 await  或者 then 擷取認證結果。
            認證結束，根據res判斷認證結果
            res的資料結構
            { 
                resultCode, // 結果碼 
                extInfo, // 擴充資訊
            }
        */
          console.log('認證結果', res);
        })
      });
    </script>
    </body>
</html>

使用者自訂 iframe 接入

若希望自行控制 iframe 容器的樣式與布局，或不希望引入官方 verify.js，可將 TransactionUrl 直接嵌入 iframe，認證結束後通過 postMessage 接收結果。

適用情境

需要將認證地區嵌入到頁面指定位置，而非全屏覆蓋。
需要自訂 iframe 尺寸、邊框、層級等樣式。
已有統一的 iframe 容器管理邏輯，不希望額外引入 verify.js。

接入流程

調用商務服務端初始化介面擷取 TransactionUrl。初始化時請勿配置 ReturnUrl，認證結果將通過 postMessage 機制回傳。
在頁面中建立 iframe 元素，並將擷取到的 TransactionUrl 直接賦值給 src 屬性。
```

<iframe
  id="idv-iframe"
  src="{TransactionUrl}"
  allow="camera"
  style="width: 100%; height: 600px; border: 0;"
></iframe>
```
說明
- iframe 必須設定 allow="camera" 屬性，否則無法調用網路攝影機。
- 頁面須通過 HTTPS 部署。
- 認證頁面載入後會自動啟動認證流程，無需父頁面額外下髮指令。
監聽 message 事件，接收認證結果。

認證結果資料結構

認證流程結束後，子頁面將通過 postMessage 機制向父頁面發送認證結果。返回的資料結構如下：

{
  resultCode,  // 結果碼，參見「用戶端結果碼說明」
  extInfo: {
    certifyId  // 認證 ID
  }
}

完整程式碼範例

<!DOCTYPE HTML>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Custom iframe integration</title>
  </head>
  <body>
    <div id="idv-container"></div>
    <script>
      // 1. 請求商務服務端初始化介面，擷取 TransactionUrl（不配置 ReturnUrl）
      fetch('https://<認證初始化介面地址>', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ /* MetaInfo */ })
      })
        .then(response => response.json())
        .then(data => {
          const { TransactionUrl } = data;

          // 2. 建立 iframe，直接載入 TransactionUrl
          const iframe = document.createElement('iframe');
          iframe.src = TransactionUrl;
          iframe.setAttribute('allow', 'camera');
          iframe.style.cssText = 'width:100%;height:600px;border:0;';
          document.getElementById('idv-container').appendChild(iframe);

          // 3. 監聽 postMessage，接收認證結果
          window.addEventListener('message', function (event) {
            const data = event.data;
            if (Object.prototype.toString.call(data) !== '[object Object]') {
              return;
            }
            if (data.resultCode) {
              console.log('認證結果', data.resultCode, data.extInfo);
              // 根據 resultCode 進行業務處理
            }
          });
        });
    </script>
  </body>
</html>

與 verify.js 接入方式的對比

對比項	verify.js 接入	使用者自訂 iframe 接入
引入依賴	需引入 `verify.js`	無需引入額外 JS
iframe 建立	SDK 自動建立全屏 iframe	開發人員自行建立並控制樣式
啟動方式	需調用 `startVerify()` 並傳入 Protocol	iframe 載入後自動啟動
認證結果擷取	`startVerify().then(res => ...)`	監聽 `message` 事件，讀取 `resultCode`
前置條件	無特殊要求	初始化時不配置 ReturnUrl
適用情境	快速整合，全屏認證	嵌入式整合，自訂布局

注意事項

禁用 ReturnUrl 配置：初始化介面請勿配置 ReturnUrl。若配置該參數，認證結果將通過 URL 跳轉方式回傳，而非預期的 postMessage 機制。
禁止追加 renderMode 參數：請勿在 TransactionUrl 後追加 renderMode=iframe 參數，該參數僅適用於 verify.js 接入方式。
禁止修改 URL：整合過程中，嚴禁對 TransactionUrl 進行任何操作或修改，否則將導致系統報錯。
URL 僅限單次使用：為保障認證安全，認證 URL 僅限單次使用。重複調用同一 URL 將觸發報錯。

用戶端自訂配置

ID Verification Web SDK 支援通過向 TransactionUrl 傳入參數來實現端側自訂功能。

您可以使用 & 符號將所需參數拼接至 TransactionUrl 之後，以使配置生效。樣本如下：

TransactionUrl：

https://xxxx.com?clientcfg=xxx&callbackurl=xxx&paramSign=xxx&guideFlow=ekyc

拼接 initTimeout：

https://xxxx.com?clientcfg=xxx&callbackurl=xxx&paramSign=xxx&guideFlow=ekyc&initTimeout=30

支援的功能如下表：

參數名稱	類型	是否必選	描述	樣本值
initTimeout	String	否	用戶端驗證初始化逾時時間（從頁面 loading 到進入人臉/OCR頁面的時間），單位為秒。	30
clientLivenessTimeout	String	否	人臉活體檢測單次逾時時間，單位為秒。	30
clientLivenessRetryCount	String	否	人臉活體檢測重試次數，單位次。	5
ocrTimeout	String	否	OCR單次檢測逾時時間，單位秒。	20
ocrRetryCount	String	否	OCR重試次數，單位次。	10
isPcOcrCameraCaptureSupported	String	否	是否開啟OCR網路攝影機採集，取值範圍： 0：不開啟（預設）。 1：開啟。說明該參數適用於PC整合情境。	0
region	String	否	移動端阿里雲介面請求地區上車點，其中 region 值和地區對應關係如下： `{ "HK": "香港", "US": "美東", "US-CA": "美西", "SG": "新加坡", "MY": "馬來西亞", "ID": "印尼", "PH": "菲律賓", "DE": "德國", "SA": "沙特" }` 說明傳入此參數可指定調用阿里雲介面的服務地區。如不指定，預設就近訪問。	HK

用戶端結果碼說明

結果碼	是否計費	結果碼描述
1000	是	使用者完成了刷臉過程，認證建議結果為通過。該結果僅供參考，可通過調用服務端CheckResult介面擷取最終認證結果，進行下一步處理。
1001	是	使用者完成了刷臉過程，認證建議結果為未通過。該結果僅供參考，可通過調用服務端CheckResult介面擷取最終認證結果，進行下一步處理。
1002	否	系統錯誤。
1003	否	SDK初始化失敗，請確認用戶端時間是否正確。
1004	否	相機許可權錯誤。請參考以下步驟嘗試解決：在認證前請先確保App已擷取到相機許可權。如已授權仍提示無許可權，請嘗試清除App緩衝後重試。
1005	否	網路錯誤。
1006	否	使用者退出。
1007	否	TransactionId無效.
1009	否	用戶端時間戳記錯誤。
1011	否	提交證件類型錯誤。
1012	否	識別出的證件關鍵資訊缺失或格式校正失敗。
1013	否	圖片品質不佳。
1014	否	錯誤次數超出上限。