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

微信小程序原生开发接入流程

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

我的收藏

本页目录：

开发准备

1. 下载 SDK

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

2. 安装 SDK

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

3. 调试 SDK

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

4. 卸载 SDK

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


SDK 主包接入

主包接入流程

1. 将 verify_mpsdk 文件夹放到小程序项目根目录。
2. 初始化慧眼实名核身 SDK。
3. 在 App.js 的 onLaunch() 中加入相应代码，在 App.json 文件里添加活体验证页面verify_mpsdk/index/index。
//app.js
App({
 onLaunch: function () {
     // 初始化慧眼实名核身组件
     const Verify = require('/verify_mpsdk/main');
     Verify.init();
 }
}) 
// app.json
{
 "pages":[
     "verify_mpsdk/index/index"
 ]
}
4. 调用 SDK 功能函数 wx.startVerify()。
5. 在需要实名认证的地方调用 wx.startVerify() 进入实名认证页面，认证完成会触发对应的回调函数。
// 单击某个按钮时，触发该函数
gotoVerify: function () {
 let BizToken = getBizToken();// 该函数为客户自定义函数，去客户后端调用 DetectAuth 接口获取 BizToken
 // 调用实名核身功能
 wx.startVerify({
     data: {
         token: BizToken // BizToken
     },
     success: (res) => { // 验证成功后触发
         // res 包含验证成功的token, 这里需要加500ms延时，防止iOS下不执行后面的逻辑
         setTimeout(() => {
             // 验证成功后，拿到token后的逻辑处理，具体以客户自身逻辑为准
         }, 500);
     },
     fail: (err) => {  // 验证失败时触发
         // err 包含错误码，错误信息，弹窗提示错误
         setTimeout(() => {
             wx.showModal({
                 title: "提示",
                 content: err.ErrorMsg,
                 showCancel: false
             })
         }, 500);
     }
 });
}
6. 添加域名服务器白名单。
您需要在小程序上线前进入：微信公众号管理平台 > 管理 > 开发管理 > 开发设置 > 服务器域名，将以下域名添加至白名单，小程序前端接口请求有域名白名单限制，未添加白名单的域名只能在调试模式下运行。
// 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


分包接入

分包接入流程

1. 复制verify_mpsdk到src根目录下。

2. 配置app.json分包页面路径。
"subpackages": [
    {
      "root": "verify_mpsdk",
      "pages": [
        "index/index"
      ]
    }
  ],
3. 初始化慧眼实名核身 SDK：初始化及调用参考 微信小程序接入-SDK 主包接入，参数无变化。
4. 调用 SDK 功能函数wx.startVerify() 。
在需要实名认证的地方调用 wx.startVerify() 进入实名认证页面，认证完成会触发对应的回调函数。
// 单击某个按钮时，触发该函数
gotoVerify: function () {
 let BizToken = getBizToken();// 该函数为客户自定义函数，去客户后端调用 DetectAuth 接口获取 BizToken
 // 调用实名核身功能
 wx.startVerify({
     data: {
         token: BizToken // BizToken
     },
     success: (res) => { // 验证成功后触发
         // res 包含验证成功的token, 这里需要加500ms延时，防止iOS下不执行后面的逻辑
         setTimeout(() => {
             // 验证成功后，拿到token后的逻辑处理，具体以客户自身逻辑为准
         }, 500);
     },
     fail: (err) => {  // 验证失败时触发
         // err 包含错误码，错误信息，弹窗提示错误
         setTimeout(() => {
             wx.showModal({
                 title: "提示",
                 content: err.ErrorMsg,
                 showCancel: false
             })
         }, 500);
     }
 });
}
如涉及跨分包调用等情况，请使用异步调用。异步初始化、调用代码示例如下：
// 单击某个按钮时，触发该函数
gotoVerify: function () {
    ...
 // 调用实名核身功能
require.async('../../verify_mpsdk/main').then(async (Verify) => {
      await Verify.init();
      // 调用实名核身功能
      wx.startVerify({
        // 传入的数据
        data: {
          token: BizToken // BizToken
        },
        // 验证成功后触发
        success: function (data) {
          console.log('收到验证成功的回调',data);
        },
        // 验证失败时触发
        fail: function (err) {
          console.log('收到验证失败的回调', err);
        },
      });
    }).catch(({ mod, errMsg }) => {
      console.log(mdoe, errMsg)
    })
}
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.token：String required 客户后端调用 DetectAuth 接口获取的 BizToken。
options.success：Function(res) required 验证成功的回调。res 包含验证成功的 token。
options.fail：Function(err) required 验证失败的回调。err 包含错误码、错误信息。

中国站