接入流程
1. 下载 NFC 小程序 SDK,并在小程序代码中引入,调用 init 方法进行初始化。
2. 接入方服务端调用 GetNFCToken 接口,获取到 NFC 核验流程标识(BizToken)。
3. 客户后端将 BizToken 返回给客户小程序端,然后小程序调用
wx.startNfcVerify() 进入 NFC 身份证件核验流程。4. 用户完成 NFC 读卡核验后,会以回调函数形式返回 BizToken,接入方小程序将 BizToken 传给接入方服务端,接入方服务端即可凭借 BizToken 参数调用 GetWxNFCResult 接口获取本次核验的详细信息。
SDK 接入
开发准备
环境要求
项目 | 说明 |
终端 | 仅 Android(iOS 小程序不支持 NFC,SDK 会返回 ErrorCode: -201) |
微信版本 | 建议 8.0.0 及以上 |
硬件 | 设备需支持 NFC 且处于开启状态 |
下载 SDK
安装 SDK
将
nfc_sdk 文件夹放在小程序根目录下,使用 require 函数引入。const Verify = require('/nfc_sdk/main');
调试 SDK
请在微信开发者工具中使用手机"预览"模式进行调试,请勿使用"真机调试"。NFC 读卡功能需在 Android 真机上测试。
卸载 SDK
卸载时删除
nfc_sdk 文件夹,移除相应 require 代码即可。快速入门
1. 将
nfc_sdk 文件夹放到小程序项目根目录。2. 初始化 NFC SDK。
在
app.js 的 onLaunch() 中加入相应代码,在 app.json 文件里添加 NFC 验证页面 nfc_sdk/index/index。// app.jsApp({onLaunch: function () {// 初始化 NFC SDKconst Verify = require('/nfc_sdk/main');Verify.init();}})
// app.json{"pages": ["nfc_sdk/index/index"]}
3. 调用 SDK 功能函数
wx.startNfcVerify()。在需要 NFC 身份核验的地方调用
wx.startNfcVerify() 进入核验流程,核验完成会触发对应的回调函数。身份证类(默认):
gotoVerify: function () {let BizToken = getBizToken(); // 客户自定义函数,从后端获取 Tokenwx.startNfcVerify({data: {token: BizToken, // 必填,来自 GetNFCTokencardType: '01', // 可选,证件类型 code,默认 '01' 身份证},success: (res) => { // 验证成功后触发// res.BizToken 为本次验证对应的 TokensetTimeout(() => {// 验证成功后的逻辑处理}, 500);},fail: (err) => { // 验证失败时触发// err.ErrorCode 错误码,err.ErrorMsg 错误信息setTimeout(() => {wx.showModal({title: "提示",content: err.ErrorMsg,showCancel: false})}, 500);}});}
旅行证类(需额外传入三要素):
gotoVerify: function () {let BizToken = getBizToken();wx.startNfcVerify({data: {token: BizToken,cardType: '06', // 证件类型,如港澳通行证cardNumber: 'C12345678', // 证件号码birthday: '910323', // 出生日期,6 位 YYMMDDexpriyDay: '270320', // 有效期,6 位 YYMMDD},success: (res) => {setTimeout(() => {// 验证成功后的逻辑处理}, 500);},fail: (err) => {setTimeout(() => {wx.showModal({title: "提示",content: err.ErrorMsg,showCancel: false})}, 500);}});}
4. 添加域名服务器白名单。
您需要在小程序上线前进入:微信公众号管理平台 > 管理 > 开发管理 > 开发设置 > 服务器域名中将以下域名添加至白名单,小程序前端接口请求有域名白名单限制,未添加白名单的域名只能在调试模式下运行。
// request 合法域名nfc.faceid.qq.com,faceid.qq.com
基本 API 描述
Verify.init()
初始化 NFC SDK,需在
app.js 的 onLaunch() 中调用。wx.startNfcVerify(options)
进入 NFC 身份证件核验页面。
options 参数说明:
参数 | 类型 | 必填 | 说明 |
options.data.token | String | 是 | |
options.data.cardType | String | 否 | 证件类型 code,默认为 '01'(身份证),详见下方证件类型表 |
options.data.cardNumber | String | 旅行证类必填 | 证件号码 |
options.data.birthday | String | 旅行证类必填 | 出生日期,6 位数字 YYMMDD 格式 |
options.data.expriyDay | String | 旅行证类必填 | 有效期,6 位数字 YYMMDD 格式 |
options.success | Function(res) | 是 | 验证成功的回调, res.BizToken 为本次验证的 Token |
options.fail | Function(err) | 是 | 验证失败的回调, err.ErrorCode 为错误码,err.ErrorMsg 为错误信息 |
cardType 证件类型取值:
身份证类(只需传 token):
cardType | 证件名称 |
01(默认) | 身份证 |
13 | 外国人永久居留证 |
14 | 港澳台居民居住证 |
旅行证类(需额外传入 cardNumber / birthday / expriyDay):
cardType | 证件名称 |
06 | 港澳通行证 |
07 | 台胞证 |
08 | 外国护照 |
15 | 回乡证 |
16 | 大陆居民来往台湾通行证 |
注意:
传入不支持的 cardType 会自动兜底为身份证(01)。
错误码
ErrorCode | 含义 |
0 | 成功 |
-1 | 用户退出 NFC 验证 |
-100 | token 为空 |
-101 | 旅行证类三要素(cardNumber / birthday / expriyDay)缺失 |
-104 | 网络请求失败 |
-201 | 设备不支持 NFC / NFC 未开启 / iOS 机型 |
-202 | 跳转 NFC 验证页面失败 |
-203 | 获取 NFC 配置失败 |
说明:
业务层错误码(TriggerDecode 返回)透传自服务端,具体含义以慧眼服务端文档为准。
操作步骤
步骤1:获取 Token
注意:
BizToken 仅对应一次核验流程,有效时间为 600 秒;用户完成核验后,开发者可用该标识获取验证结果信息,结果信息仅保留 7 天。
步骤2:调用 SDK 发起核验
客户后端将 BizToken 下发给小程序端后,调用
wx.startNfcVerify() 发起 NFC 核验流程,用户进入核验页面完成 NFC 读卡操作。步骤3:查询核验结果
注意: