意愿核身 E证通接入流程

最近更新时间:2024-04-11 15:24:41

我的收藏
本文为您描述如何接入意愿核身 E证通小程序,详细接入操作如下:
详细接入操作如下:

1. 申请商户 ID

1. 登录腾讯云慧眼 人脸核身控制台,单击自助接入>E证通服务>申请商户 ID
2. 完整填写相关信息,然后单击提交。审核时间从您提交当天开始计算,需要3个工作日,请您预留好时间并耐心等待。
注意:
如果审核后需要您修改资料,审核预估时间会从下次提交时重新计算。

3. 审核通过后,可以看到商户 ID 和 E证通小程序 SDK,后续需要使用商户 ID 获取 E证通服务流程唯一标识 EidToken。



2. 获取 EidToken

接入方服务端调用获取E证通 Token GetEidToken 接口,传入 E证通服务所需参数及意愿核身所需参数 Config 信息,获取到 EidToken。



3. 内嵌小程序 SDK

3.1 前置条件

step 1. 添加服务器域名白名单

小程序前端接口请求有域名白名单限制,未添加白名单的域名只能在调试模式下运行。接入方需要在小程序上线前将以下域名添加至服务器域名白名单:
// request 合法域名
eid.faceid.qq.com

step 2. 添加业务域名白名单

说明:
SDK V1.0.7及以上版本不需要添加业务域名白名单。
在小程序配置业务域名中,将下载后的校验文件在控制台随商户 ID 提交审核时上传,待腾讯侧审核通过后,将域名 eid.faceid.qq.com 添加至业务域名白名单。

3.2 安装 SDK

商户 ID 申请通过后,在 控制台商户 ID 列表页 可以下载 E证通小程序 SDK。下载完成后将 E证通小程序 SDK 文件夹放在小程序根目录下。

3.3 SDK 调用步骤

step 1. 初始化 SDK

1. 在 app.js 文件中引入初始化 SDK 的方法 initEid。
2. 在 App.js 的 onLaunch() 中加入相应代码,在 App.json 文件里添加E证通 SDK 页面。
3. 在 onLaunch 方法中调用 initEid。
//app.js
import { 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.verifyDoneCallback:Function(res) required 核身完成的回调。res 包含验证成功的 token,是否完成的布尔值标志 verifyDone。请根据 res 返回的结果进行业务处理判断。

3.4 半屏接入指引(可选)

如您需要实现小程序半屏模式,可参考3.4步骤进行配置,如不需要实现半屏模式,则可直接跳到 获取 E证通的核验结果信息
小程序的半屏模式可以省去小程序跳转的弹窗步骤,实现如图所示的半屏页面展示,流程体验可以联系慧眼小助手获取:




接入准备

申请半屏调用 eID 数字身份小程序
打开小程序微信管理平台后台,选择设置,第三方设置,打开半屏小程序管理,单击添加
add.jpg


输入 eID 数字身份的 AppID(联系慧眼小助手获取 AppID 并通过半屏申请)。
注意:
每个小程序最多可添加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);
},
});
},

startEid() 参数说明:
半屏接入不支持时会自动降级为全屏打开。
因半屏接入是微信新上的能力,少部分机型还存在兼容性问题,请谨慎开启。
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 返回的结果进行业务处理判断。

注意事项

1. 每个小程序最多可添加10个半屏打开的小程序。
2. 半屏接入需向E证通eID数字身份发送半屏申请,审核通过后才会生效。
3. 半屏接入不支持时会自动降级为全屏打开。
4. 因半屏接入是微信新上的能力,少部分机型还存在兼容性问题,请确保进行过完善的测试后再上线。

4. 获取意愿核身(E证通)核验结果信息

1. 用户完成人脸核身后,会以回调形式返回 EidToken 以及其他信息,接入方小程序将 EidToken 传给接入方的服务端,接入方服务端即可凭借 EidToken 参数调用获取小程序核身结果信息 GetEidResult 接口去获取本次核身的详细信息,最后将核身结果返回给接入方小程序。
说明
EidToken 作为一次核身流程的标识,有效时间为600秒;完成核身后,可用该标识获取3天内验证结果信息。

5. 调试 SDK

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

6. 卸载 SDK

删除 mp_ecard_sdk 文件夹。

接入时序图





注意事项

1. 从 eID 数字身份小程序返回接入方小程序。 当接入方小程序在初始化E证通 SDK 的时候,E证通 SDK 会通过 wx.onAppShow 注册一个监听从 eID 数字身份小程序跳转回接入方小程序的事件,从而根据情况触发接入方传入的核身完成的回调函数。
2. 由于微信的机制,用户在 eID 数字身份小程序跳转回接入方小程序的时候,同时也会触发接入方小程序 app.js 中的 onShow 方法。为了避免冲突,如果接入方小程序在 onShow 中有执行逻辑的话,需要排除掉从 eID 数字身份小程序跳转回接入方小程序这个场景。可通过以下方法实现:
// app.js

onShow(options) {
const { referrerInfo, scene } = options;
/* 判断是否从eID数字身份小程序返回 */
const { appId } = referrerInfo;
if (scene === 1038 && appId === 'wx0e2cb0b052a91c92') {
return;
} else {
// 执行接入方小程序原本的逻辑
}
},
3. 基于对个人隐私信息的保护,按照最小必要返回身份信息的要求,E证通服务不再返回姓名和身份证号的明文信息。如因业务需要返回,请查看E证通获取实名信息指引