平台简介
新手指南
API协议
API文档
单点登录集成
小程序插件
公告
常见问题
开放平台使用操作手册
帮助中心 / 开放平台帮助文档 / 插件集成说明
插件集成说明
小程序插件集成说明

插件集成说明

申请插件

在开始开发前,需要先申请契约锁小程序插件的使用权限,开发者需要登录自身小程序管理后台,在”设置-第三方服务-插件管理“中添加小程序插件,通过如下appId:wxaf8f505686ddf66a,匹配到插件后添加即可提交申请。

引入插件

使用插件前,使用者要在 app.json 中声明契约锁小程序插件(version见插件更新记录中最新版本号),即:

{
  ...
  "plugins": {
    "qyssdk-plugin": {
      "version": "1.2.2",
      "provider": "wxaf8f505686ddf66a"
    }
  }
  ...
}

插件调用方法

契约锁小程序插件以插件页面的形式为对接方小程序提供服务,可通过如下方式进入插件页面,用户在插件页面完成对应操作后,会自动跳回到跳转前的小程序页面,也支持指定跳转页面。

let eventChannel = null;
wx.navigateTo({
    url: `plugin://qyssdk-plugin/${page}?ticket=${ticket}&env=${env}&hasCb=true`,
    events: {
        signSuccessCb: () => { // 签署成功回调
            console.log('signComplete');
            const url = '/pages/bbb/bbb'; // 需要跳转的小程序页面地址,必须是绝对路径,可不传
            eventChannel.emit('jumpTo', url); // 触发跳转逻辑,回调存在时必需调用,url不传默认返回
        },
        authSuccessCb() { // 认证成功回调
            console.log('authSuccess');
            eventChannel.emit('jumpTo');
        },
        authFailCb() { // 认证失败回调
            console.log('authFail');
            eventChannel.emit('jumpTo');
        },
    },
    success(res) {
        eventChannel = res.eventChannel;
    },
});

1.0.23新增:支持调用方小程序自定义跳转

应用示例:实名认证完成,跳转到填参页面

let eventChannel = null;
wx.navigateTo({
    url: `plugin://qyssdk-plugin/${page1}?ticket=${ticket1}&env=${env1}&hasCb=true`,
    events: {
        signSuccessCb: () => {
            eventChannel.emit('jumpTo', '/tabbar/home/home');
        },
        authSuccessCb: () => {
            eventChannel.emit('jumpTo', `plugin://qyssdk-plugin/${page2}?ticket=${ticket2}&env=${env2}&hasCb=true`, {
                signSuccessCb: (openedEventChannel) => {
                    openedEventChannel.emit('jumpTo', `plugin://qyssdk-plugin/${page3}?ticket=${ticket3}&env=${env3}&hasCb=true`);
                },
                authSuccessCb: (openedEventChannel) => {
                    openedEventChannel.emit('jumpTo', '/tabbar/mine/mine');
                },
                authFailCb: (openedEventChannel) => {
                    openedEventChannel.emit('jumpTo', '/subpackages/mine/settings');
                },
            });
        },
        authFailCb: () => {
            eventChannel.emit('jumpTo', '/subpackages/list/list');
        },
    },
    success(res) {
        eventChannel = res.eventChannel;
    },
});

1.0.30新增:支持直接传入成功或失败的跳转地址 ps: 用于修复eventChanel丢失导致无法触发回调(如在插件中,从签署跳到了认证,此时OpenerEventChannel是上一个插件页面,与宿主小程序无法进行通信了)

wx.navigateTo({
    url: `plugin://qyssdk-plugin/${page1}?ticket=${ticket1}&env=${env1}&hasCb=true`,
    success(res) {
        const eventChannel = res.eventChannel;
        // 不传、undefined、null则沿用旧逻辑,空字符串不做任何处理
        eventChannel.emit('sendNavigatePaths', {
            success: '/pages/success', // 成功时跳转的地址,不区分签署页面或者实名认证页面。可传tab页面
            fail: '/pages/fail',
        });
    },
}

参数说明

参数 类型 是否必须 描述
page String 插件页面入口:doc(合同预览入口),doc(合同签署入口),enterprise-auth(企业认证入口),personal-auth(实名认证入口),signature(个人签名授权-open平台),signature(个人签名授权-sass平台),signature(印章自动签授权-sass平台)
注意:如果当前签署用户进入合同签署入口,且需要认证,插件会自行跳转认证,认证成功后继续签署合同,即对接方若非需要单独进行用户认证,直接调用合同签署入口即可。
ticket String 由开放平台接口获取的插件页面令牌,请注意获取的令牌需与插件页面入口对应使用
env String 环境参数:com(生产环境),cn(测试环境),默认为生产环境
hasCb String 与 events 回调配合使用,events 存在时为必传,不存在时不传
type String 当page为signature时必传:个人签名授权-open平台(personalSignatureOpen),个人签名授权-sass平台(personalSignature),印章自动签授权-sass平台(sealSignature)

插件入口与令牌对应说明

此处仅申明不同的插件页面入口,对应的令牌获取接口地址,具体接口请求内容,参考具体接口文档。

插件页面入口 令牌获取接口名称 令牌获取接口地址
doc 生成合同签署令牌 /v2/contract/miniappexchange
doc 生成合同预览令牌 /v2/contract/miniappexchange/view
enterprise-auth 生成企业认证令牌 /companyauth/miniappexchange
personal-auth 生成个人认证令牌 /v2/personalauth/miniappexchange
signature 生成个人静默签授权令牌-open平台 /v2/personalsign/authurl/miniappexchange
signature 生成个人静默签授权令牌-sass平台 /saas/v2/personalsign/authurl/miniappexchange
signature 生成印章自动签授权令牌-sass平台 /saas/v2/sealsign/authurl/miniappexchange