帮你快速理解、总结文档立即下载
文档中心>人脸核身>含 UI 集成方案>Plus 版人脸核身>微信小程序>微信小程序 uni-app 接入流程

微信小程序 uni-app 接入流程

最近更新时间：2026-07-29 16:53:25

我的收藏

本页目录：

开发准备

注意：
小程序授权指引及接入准备参见 微信小程序接入指引。

1. 下载 SDK

登录 人脸核身控制台 下载小程序 SDK，并在小程序代码中引入，调用 init 方法进行初始化。

2. 安装 SDK

将小程序 SDK 文件夹放在小程序根目录下，使用 require 函数引入。
const Verify = require('/verify_mpsdk/main');

3. 调试 SDK

请在微信开发者工具中使用手机“预览”模式进行调试，请勿使用“真机调试”。

4. 卸载 SDK

卸载时删除verify_mpsdk文件夹，移除相应 require 代码即可。

5. 域名白名单限制

小程序前端接口请求有域名白名单限制，如果不添加只能在调试模式下运行，上线前需要将如下两个域名在小程序后台添加服务器域名。
https://faceid.qq.com;
https://faceid.qcloud.com;

uni-app 主包接入

步骤一：注册并创建 uni-app 开发环境

uni-app 开发接入具体参照 uni 官网。

步骤二：下载 SDK

控制台下载最新版本的 SDK。

步骤三：配置 verify_mpsdk

本 SDK 仅支持 uni 微信小程序端。
1. 将 verify-mpsdk 文件夹拷贝到项目根目录的 wxcomponents 文件夹下。
2. 创建一个空页面调用组件。
pages.json 注册组件地址，例如 pages/verify/index 。
{
  "pages": [ 
    ...
    {
      "path": "/pages/verify/index",
      "style": {
        "navigationBarTitleText": "uni-app",
        "usingComponents": {
              "verify-mp": "/wxcomponents/verify_mpsdk/indexCom"
          }
      }
    }
  ]
}
在注册的地址生成小程序 SDK 页，调用 verify-mp 组件。
注意：
该页面为空内容组件调用页，不需要其他逻辑代码。
<template>
    <verify-mp></verify-mp>
</template>

<script>
export default {
  data() {
    return {   }
  },
  onLoad() {},
  methods: {},
}
</script>
3. 初始化。
方法一：可以在 App.vue 中全局初始化。
export default {
  onLaunch: function() {
    const verify = require('/wxcomponents/verify_mpsdk/main');
  	verify.init();
  },
};
方法二：在需要调用到的页面方法之前初始化即可。
4. 调用 startVerify。
注意：
startVerify 调用需要在 init 初始化之后。
 // 业务发起调用页面
   wx.startVerify({
    data: {
      token: '', // 必要参数，BizToken
      startPath: '/pages/verify/index' // 必要参数，配置了verify核身组件的页面地址
    },
    success: (res) => { // 验证成功后触发
      // res 包含验证成功的token, 这里需要加500ms延时，防止iOS下不执行后面的逻辑
      // 验证成功后，拿到token后的逻辑处理，具体以客户自身逻辑为准
    },
    fail: (err) => {  // 验证失败时触发
      // err 包含错误码，错误信息，弹窗提示错误
    }
  });
5. 添加域名服务器白名单
您需要在小程序上线前进入：微信公众号管理平台 > 管理 > 开发管理 > 开发设置 > 服务器域名，将以下域名添加至白名单，小程序前端接口请求有域名白名单限制，未添加白名单的域名只能在调试模式下运行。
// request 合法域名、uploadFile 合法域名、downloadFile 合法域名这三种都要添加
faceid.qq.com、faceid.qcloud.com
// socket合法域名 （v1.0.20及以上版本需要添加以下socket域名）
wss://faceid.qq.com
// v1.0.17及以上版本身份校验环节如需NFC方式读取证件，需要添加以下socket域名
wss://idcloudread.eidlink.com

主包示例 Demo



uni-app 分包接入

步骤一：注册并创建 uni-app 开发环境

uni-app 开发接入具体参照 uni 官网。

步骤二：下载 SDK

控制台下载最新版本的 SDK。

步骤三：配置 verify_mpsdk

说明：
本 SDK 仅支持 uni‑app 微信小程序端。
以下示例中的文件夹及路径命名均为示意，请根据实际业务场景灵活调整。

1. 将 verify-mpsdk 文件夹拷贝到需要调用的分包路径下


构建配置需将组件目录完整拷贝至打包输出目录（如 dist），且拷贝后的存放路径必须与代码中引用该组件的调用路径保持一致，以确保资源加载正确。


实现方案：

1.1 手动拷贝
编译完成后，请手动将 verify_mpsdk 文件夹复制到对应的调用路径，并务必确保每次编译后均成功完成此拷贝操作。
1.2 自动编译拷贝
推荐使用自动化构建插件（如 rollup-plugin-copy、vite-plugin-copy、copy-webpack-plugin）来完成文件拷贝操作，以下以 rollup-plugin-copy 为例：
// vite.config.js
import copy from 'rollup-plugin-copy'

export default defineConfig({
  plugins: [
    copy({
      targets: [
        {
          src: 'src/subpages/native-components/',
          dest: 'dist/dev/mp-weixin/subpages/'
        },
      ],
    })
  ],
})

2. Pages.json 文件配置分包调用 pages

2.1 在 pages.json 注册分包页面的组件调用空白页面地址，例如 subpages/verify/index 。

// pages.json
  "subPackages": [
    {
      "root": "subpages",
      "pages": [
        {
          "path": "index/index",
          "style": {
            "navigationBarTitleText": "分包调用核身页面"
          }
        },
        {
          "path": "verify/index",
          "style": {
            "navigationBarTitleText": "组件调用空页面",
            "usingComponents": {
                  "verify-mp": "/subpages/native-components/verify_mpsdk/indexCom"
              }
          }
        }
      ]
    }
  ],
2.2 在注册的组件地址调用verify-mp组件。
注意：
该页面为空内容组件调用页，不需要其他逻辑代码。
<template>
    <verify-mp></verify-mp>
</template>

<script>
export default {
  data() {
    return {   }
  },
  onLoad() {},
  methods: {},
}
</script>

3. 初始化

请在发起调用之前进行 SDK 初始化，如涉及跨包调用，需使用 异步调用。
const verify = require('/wxcomponents/verify_mpsdk/main');
verify.init();

4. 调用 startVerify

分包发起核身服务页面调用 wx.startVerify，startPath 为调用组件的配置地址。
 // 业务发起调用页面，如subpags/index/index
   wx.startVerify({
    data: {
      token: '', // 必要参数，BizToken
      startPath: '/subpages/verify/index' // 必要参数，配置了verify核身组件的页面地址
    },
    success: (res) => { // 验证成功后触发
      // res 包含验证成功的token, 这里需要加500ms延时，防止iOS下不执行后面的逻辑
      // 验证成功后，拿到token后的逻辑处理，具体以客户自身逻辑为准
    },
    fail: (err) => {  // 验证失败时触发
      // err 包含错误码，错误信息，弹窗提示错误
    }
  });
发起页面异步调用参考示例：
 require.async('../native-components/verify_mpsdk/main').then(async (Verify) => {
        console.log('gotoVerify', Verify);
        await Verify.init();
        // 调用实名核身功能
        wx.startVerify({
          // 传入的数据
          data: {
            token: this.token,
            startPath: "/subpages/verify/index"
          },
          // 验证成功后触发
          success: function (data) {
            console.log('收到验证成功的回调');
          },
          // 验证失败时触发
          fail: function (err) {
            console.log('收到验证失败的回调', err);
          },
        });
      })

5.添加域名服务器白名单

您需要在小程序上线前进入：微信公众号管理平台 > 管理 > 开发管理 > 开发设置 > 服务器域名，将以下域名添加至白名单，小程序前端接口请求有域名白名单限制，未添加白名单的域名只能在调试模式下运行。
// request 合法域名、uploadFile 合法域名、downloadFile 合法域名这三种都要添加
faceid.qq.com、faceid.qcloud.com
// socket合法域名 （v1.0.20及以上版本需要添加以下socket域名）
wss://faceid.qq.com
// v1.0.17及以上版本身份校验环节如需NFC方式读取证件，需要添加以下socket域名
wss://idcloudread.eidlink.com

分包示例 Demo

示例 Demo 仅供演示参考，请先掌握分包接入逻辑，随后按自身业务需求调整代码。


基本 API 描述

Verify.init(options)：初始化插件。
​ options：Object required 初始化的参数。
wx.startVerify(options)：进入实名认证页面。
​ options：Object required 初始化的参数。
​ options.data.startPath：组件初始化页面，必填。
​ options.data.token：String required 客户后端调用 DetectAuth 接口获取的 BizToken。
​ options.success：Function(res) required 验证成功的回调。res 包含验证成功的 token。
​ options.fail：Function(err) required 验证失败的回调。err 包含错误码、错误信息。


获取实名核身结果信息

用户完成人脸核身后，页面会跳转到 RedirectUrl 上，地址中会带上此次验证流程使用的 BizToken，您在服务端即可凭借 BizToken 参数调用 获取实名核身结果信息 接口去获取本次核身的详细信息。获取到用户验证过程数据，包括文本信息、识别分数、照片和视频。也可以通过访问 腾讯云人脸核身控制台 查看服务
中国站