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	否	错误次数超出上限。