首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >微信小程序怎么接入人脸核身?保姆级教程来了

微信小程序怎么接入人脸核身?保姆级教程来了

原创
作者头像
克劳德2048
发布于 2026-09-30 18:05:00
发布于 2026-09-30 18:05:00
710
举报

摘要:

微信生态是国内业务绕不开的入口,小程序内的实名核身怎么接?本文讲清楚微信渠道支持的接入方式、接入前的准备工作,并给出完整的代码示例和常见问题的处理。


一、微信渠道支持哪些接入形式

微信生态内的人脸核身主要有三种形态:

微信小程序:用户在小程序内直接唤起刷脸流程,体验最接近原生。

微信公众号 H5:通过公众号文章或菜单跳转到 H5 页面完成核身。

微信浏览器 H5:在微信内置浏览器中打开网页完成核身。

三者调用的都是同一套核身能力,区别在于载体和交互细节。

二、接入前要准备什么

2.1 账号与服务开通

  1. 注册腾讯云账号并完成企业认证
  2. 在人脸核身控制台开通对应服务
  3. 提交接入申请,等待审核(3-5 个工作日)

2.2 资质要求

微信小程序人脸核身仅对以下行业开放,需提前准备对应资质文件:

行业

资质要求

政务

机构或事业单位

金融

银行、保险、信托、基金、证券/期货、持牌消费金融等

医疗

公立医疗机构、互联网医院、三级私立医疗机构

运营商

基础电信运营商、虚拟运营商

教育

学历教育(学校)、公立/私立学校

出行与交通

网约车、航空、公交/地铁、火车/高铁等

社交

直播

2.3 创建业务流程获取 RuleId

登录人脸核身控制台,单击自助接入 > 创建业务流程:

  1. 选择应用场景:微信小程序
  2. 上传对应资质文件
  3. 选择应用类型:增强版人脸核身
  4. 配置人脸比对库源(权威库比对或自传照片比对)
  5. 配置活体检测方式
  6. 提交审核,审核通过后获取 RuleId

2.4 服务端准备工作

审核通过后,需要完成服务端接口对接:

代码语言:python
复制
# Python 示例:调用 DetectAuth 获取 BizToken
from tencentcloud.common import credential
from tencentcloud.faceid.v20180301 import faceid_client, models

cred = credential.Credential("SecretId", "SecretKey")
client = faceid_client.FaceidClient(cred, "ap-guangzhou")

def get_biz_token(rule_id, redirect_url):
    req = models.DetectAuthRequest()
    req.RuleId = rule_id
    req.RedirectUrl = redirect_url
    resp = client.DetectAuth(req)
    return resp.BizToken, resp.Url

# 使用示例
rule_id = "你的RuleId"
biz_token, verify_url = get_biz_token(rule_id, "https://your-domain.com/callback")
print(f"BizToken: {biz_token}")

三、小程序端接入步骤

3.1 下载并引入 SDK

从控制台获取小程序 SDK 下载链接,下载后在小程序项目中引入:

代码语言:javascript
复制
// 引入 SDK
const { init, startVerify } = require('./sdk/huiyan-sdk.min.js')

// 初始化 SDK
init({
  appId: '你的小程序AppId'
})

3.2 调用核身流程

代码语言:javascript
复制
Page({
  data: {
    bizToken: ''
  },

  // 用户点击开始核身
  async handleStartVerify() {
    try {
      // 1. 请求服务端获取 BizToken
      const res = await wx.request({
        url: 'https://your-domain.com/api/getBizToken',
        method: 'POST',
        data: {
          // 业务参数
        }
      })

      const bizToken = res.data.bizToken
      this.setData({ bizToken })

      // 2. 调用 SDK 启动核身
      startVerify({
        token: bizToken,
        success: (res) => {
          console.log('核身成功', res)
          // 3. 通知服务端拉取结果
          this.verifyResult(res.token)
        },
        fail: (err) => {
          console.error('核身失败', err)
          wx.showToast({
            title: '核身失败,请重试',
            icon: 'none'
          })
        }
      })
    } catch (err) {
      console.error('获取Token失败', err)
    }
  },

  // 服务端拉取核身结果
  async verifyResult(token) {
    const res = await wx.request({
      url: 'https://your-domain.com/api/getResult',
      method: 'POST',
      data: { token }
    })

    if (res.data.success) {
      wx.redirectTo({
        url: '/pages/result/result?status=success'
      })
    } else {
      wx.redirectTo({
        url: '/pages/result/result?status=fail'
      })
    }
  }
})

3.3 服务端拉取结果

代码语言:python
复制
# Python 示例:调用 GetDetectInfoEnhanced 获取核身结果
def get_detect_result(biz_token):
    req = models.GetDetectInfoEnhancedRequest()
    req.BizToken = biz_token
    resp = client.GetDetectInfoEnhanced(req)

    result = {
        'success': resp.Text and resp.Text.ErrCode == 0,
        'score': resp.Sim if resp.Sim else None,
        'video': resp.VideoData if resp.VideoData else None,
        'best_frame': resp.BestFrame if resp.BestFrame else None
    }
    return result

四、小程序和公众号 H5 的差别

对比项

小程序

公众号 H5

用户入口

小程序内直接唤起

文章、菜单跳转

交互体验

更接近原生

网页交互

摄像头权限

由小程序统一申请

依赖浏览器授权

适用场景

高频、核心业务流程

引导式、活动式场景

接入复杂度

需下载 SDK

直接跳转 URL

如果核身是业务的核心环节,建议放在小程序里;如果只是特定活动的补充验证,公众号 H5 更轻。

五、常见问题

5.1 摄像头权限被拒

现象:用户误点拒绝摄像头授权后无法继续核身。

解决方案:

代码语言:javascript
复制
// 引导用户重新授权
wx.showModal({
  title: '需要摄像头权限',
  content: '请在设置中开启摄像头权限以完成人脸核身',
  confirmText: '去设置',
  success(res) {
    if (res.confirm) {
      wx.openSetting()
    }
  }
})

5.2 中途退出

现象:用户在核身过程中返回或关闭页面。

解决方案:在页面 onShow 生命周期中检测状态,提供重新发起入口。

代码语言:javascript
复制
Page({
  onShow() {
    // 检查是否有未完成的核身
    if (this.data.pendingVerify) {
      wx.showModal({
        title: '继续核身',
        content: '检测到您有未完成的核身,是否继续?',
        success: (res) => {
          if (res.confirm) {
            this.handleStartVerify()
          }
        }
      })
    }
  }
})

5.3 网络不稳定

现象:核身过程中断网导致流程失败。

解决方案:监听网络状态,给用户明确提示和重试入口。

代码语言:javascript
复制
wx.onNetworkStatusChange((res) => {
  if (!res.isConnected) {
    wx.showToast({
      title: '网络已断开,请检查网络',
      icon: 'none',
      duration: 3000
    })
  }
})

5.4 核身成功但业务状态没更新

现象:SDK 回调成功,但业务系统未更新用户状态。

原因:通常是服务端拉取结果的环节没打通。

排查步骤:

  1. 检查 GetDetectInfoEnhanced 接口是否正常调用
  2. 确认 BizToken 是否正确传递
  3. 检查业务系统的状态更新逻辑

六、上线前的检查清单

  • 资质文件已提交并通过审核
  • RuleId 已创建并配置正确
  • 服务端 DetectAuth 接口已联通
  • 服务端 GetDetectInfoEnhanced 接口已联通
  • 小程序 SDK 已正确引入并初始化
  • 摄像头权限的申请时机与提示文案已确认
  • 用户在核身中断后可以重新发起
  • 核身结果与账号状态联动正确
  • 关键操作有日志留存,便于问题定位

腾讯云慧眼人脸核身支持微信小程序与微信 H5 渠道接入,可作为微信生态内实名核身的实现方案。该系列产品正在限时特惠活动中,低至3.3折:https://cloud.tencent.com/act/pro/happynewyears

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 摘要:
  • 一、微信渠道支持哪些接入形式
  • 二、接入前要准备什么
    • 2.1 账号与服务开通
    • 2.2 资质要求
    • 2.3 创建业务流程获取 RuleId
    • 2.4 服务端准备工作
  • 三、小程序端接入步骤
    • 3.1 下载并引入 SDK
    • 3.2 调用核身流程
    • 3.3 服务端拉取结果
  • 四、小程序和公众号 H5 的差别
  • 五、常见问题
    • 5.1 摄像头权限被拒
    • 5.2 中途退出
    • 5.3 网络不稳定
    • 5.4 核身成功但业务状态没更新
  • 六、上线前的检查清单
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档