人脸核身小程序集成-含 UI 集成方案-文档中心-腾讯云

1. 概述

本文为您描述如何接入E证通小程序，请您确保在阅读本文前已阅读 接入流程说明 并按照步骤执行。阅读完本文您可以轻松接入小程序SDK，调用E证通微信小程序服务。本文将使用微信小程序开发语言作为示例演示如何接入E证通微信小程序SDK。 
2. 接入准备
2.1 下载小程序SDK
﻿人脸核身控制台，单击自助接入>E证通服务>下载小程序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.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.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 半屏接入指引（可选）
如您需要实现小程序半屏模式，可参考3.4步骤进行配置，如不需要实现半屏模式，则可直接跳到 获取 E证通的核验结果信息。
小程序的半屏模式可以省去小程序跳转的弹窗步骤，实现如图所示的半屏页面展示，流程体验可以联系慧眼小助手获取：
﻿
﻿
﻿
接入准备
申请半屏调用 eID 数字身份小程序
打开小程序微信管理平台后台，选择设置，第三方设置，打开半屏小程序管理，单击添加。 
﻿
﻿
﻿
输入 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);          
            },
        });
    },
﻿
注意事项
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.js
﻿
 onShow(options) {
     const { referrerInfo, scene } = options;
     /* 判断是否从eID数字身份小程序返回 */
     const { appId } = referrerInfo;
     if (scene === 1038 && appId === 'wx0e2cb0b052a91c92') {
         return;
     } else {
         // 执行接入方小程序原本的逻辑
     }
 },
﻿
﻿
小程序集成

本页目录：

1. 概述

2. 接入准备

2.1 下载小程序SDK

2.2 前置条件

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

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

3. 内嵌小程序 SDK

3.1 安装 SDK

3.2 SDK 调用步骤

step 1. 初始化 SDK

step 2. 调用 SDK

startEid() 参数说明：

3.3 半屏接入指引（可选）

接入准备

﻿SDK 接入

注意事项

4. 调试 SDK

5. 注意事项

SDK 接入
