1. 概述
本文为您描述如何接入E证通小程序,请您确保在阅读本文前已阅读 接入流程说明 并按照步骤执行。阅读完本文您可以轻松接入小程序SDK,调用E证通微信小程序服务。本文将使用微信小程序开发语言作为示例演示如何接入E证通微信小程序SDK。
2. 接入准备
2.1 下载小程序SDK
2.2 前置条件
step 1. 添加服务器域名白名单
小程序前端接口请求有域名白名单限制,未添加白名单的域名只能在调试模式下运行。接入方需要在小程序上线前将以下域名添加至服务器域名白名单:
// request 合法域名eid.faceid.qq.com
step 2. 添加业务域名白名单
说明:
SDK V1.0.7及以上版本不需要添加业务域名白名单。
在小程序配置业务域名中,将下载后的校验文件在控制台随商户 ID 提交审核时上传,待腾讯侧审核通过后,将域名
eid.faceid.qq.com
添加至业务域名白名单。3. 内嵌小程序 SDK
3.1 安装 SDK
下载完成小程序 SDK 后将E证通小程序 SDK 文件夹放在小程序根目录下。
3.2 SDK 调用步骤
step 1. 初始化 SDK
在 app.js 文件中引入初始化 SDK 的方法 initEid。 在 App.js 的 onLaunch() 中加入相应代码,在 App.json 文件里添加E证通 SDK 页面。 在 onLaunch 方法中调用 initEid。
//app.jsimport { initEid } from './mp_ecard_sdk/main';App({onLaunch() {initEid();},});// app.json{"pages":["mp_ecard_sdk/index/index",// sdk v1.0.4及以下版本还需添加以下路径配置"mp_ecard_sdk/protocol/service/index","mp_ecard_sdk/protocol/privacy/index","mp_ecard_sdk/protocol/userAccredit/index","mp_ecard_sdk/protocol/eid/index",]}
step 2. 调用 SDK
说明:
接入v1.0.5及以上版本,调用 startEid 需注意:调用 startEid 需通过按钮的点击形式发起调用(因v1.0.5及以上版本 sdk 更新,取消了授权页和其他按钮,使用了 wx.navigateToMiniProgram 主动拉起授权小程序)。
import { startEid } from './mp_ecard_sdk/main';// 示例方法goSDK(token) {startEid({data: {token,},verifyDoneCallback(res) {const { token, verifyDone } = res;console.log('收到核身完成的res:', res);console.log('核身的token是:', token);console.log('是否完成核身:', verifyDone);},});},
startEid() 参数说明:
startEid(options)
:进入实名认证页面。options
:Object required 接入方传入的参数。options.data.token
:String required 接入方小程序从接入方服务端获取 EidToken。options.data.needJumpPage
:是否需要中转页,默认为 false(sdk v1.0.7 及以上支持)options.data.enableEmbedded
:是否支持半屏打开,默认为 false(sdk v1.0.9 及以上支持)options.data.allowFullScreen
:半屏打开后是否支持全屏,默认为 true(sdk v1.0.9 及以上支持)options.verifyDoneCallback
:Function(res) required 核身完成的回调。res 包含验证成功的 token,是否完成的布尔值标志 verifyDone。请根据 res 返回的结果进行业务处理判断。3.3 半屏接入指引(可选)
接入准备
申请半屏调用 eID 数字身份小程序
打开小程序微信管理平台后台,选择设置,第三方设置,打开半屏小程序管理,单击添加。
注意:
每个小程序最多可添加10个半屏打开的小程序。
SDK 接入
1. 请先完成上述步骤3.1 - 3.3的接入,并下载最新版本的 SDK(SDK 1.0.9及以上版本支持半屏接入)。
2. app.json 中添加如下代码,其中 AppID 为
eID 数字身份
的 AppID。{ "embeddedAppIdList": ["AppID"]}
3. SDK 接入时传入允许半屏打开参数。
import { startEid } from './mp_ecard_sdk/main';// 示例方法goSDK(token) {startEid({data: {token,enableEmbedded: true,allowFullScreen: false},verifyDoneCallback(res) {const { token, verifyDone } = res;console.log('收到核身完成的res:', res);console.log('核身的token是:', token);console.log('是否完成核身:', verifyDone);},});},
注意事项
1. 每个小程序最多可添加10个半屏打开的小程序。
2. 半屏接入需向E证通
eID数字身份
发送半屏申请,审核通过后才会生效。3. 半屏接入不支持时会自动降级为全屏打开。
4. 因半屏接入是微信新上的能力,少部分机型还存在兼容性问题,请确保进行过完善的测试后再上线。
4. 调试 SDK
请在微信开发者工具中使用手机“预览”模式进行调试,请勿使用“真机调试”。
5. 注意事项
1. 从 eID 数字身份小程序返回接入方小程序。 当接入方小程序在初始化E证通 SDK 的时候,E证通 SDK 会通过 wx.onAppShow 注册一个监听从 eID 数字身份小程序跳转回接入方小程序的事件,从而根据情况触发接入方传入的核身完成的回调函数。
2. 由于微信的机制,用户在 eID 数字身份小程序跳转回接入方小程序的时候,同时也会触发接入方小程序 app.js 中的 onShow 方法。为了避免冲突,如果接入方小程序在 onShow 中有执行逻辑的话,需要排除掉从 eID 数字身份小程序跳转回接入方小程序这个场景。可通过以下方法实现:
// app.jsonShow(options) {const { referrerInfo, scene } = options;/* 判断是否从eID数字身份小程序返回 */const { appId } = referrerInfo;if (scene === 1038 && appId === 'wx0e2cb0b052a91c92') {return;} else {// 执行接入方小程序原本的逻辑}},