侧边栏模块化-自定义卡片功能说明
侧边栏模块化-自定义卡片
功能概述
侧边栏模块化是基于微伴助手侧边栏推出的满足客户个性化需求的功能。允许公司修改基础卡片的配置，开发自定义卡片或修改自定义卡片样式。
微伴开放平台还为开发者提供了 侧边栏模块化 DEMO，供开发者体验和快速接入。
使用场景
侧边栏个性化展示
展示地图、图表、关系图等微伴助手暂无法提供的页面。
例如：客户的车辆需要报修，开发者需要在员工的侧边栏展显示客户车辆的位置。此时自定义字段无法满足需求，企业可以开发地图页面侧边栏卡片，以便在侧边栏展示客户的车辆位置和地图信息。
如下图所示：
敏感数据保护场景
部分企业业务涉及敏感信息，不能将数据存储在微伴后端数据库，通过使用自定义卡片对接企业自身的后端数据库，向其发送请求~~~~进行数据交互，以保证敏感数据安全。
例如：客户的银行卡信息和身份证号都属敏感信息，银行不能将数据保存到微伴后端中，因此银行定制自定义卡片，将对应url配置为从请求银行后端以获取敏感信息的前端页面，以保证敏感数据安全。
已有功能集成到侧边栏
将企业私有的网页集成到侧边栏中，企业员工在侧边栏可以直接通过企业微信侧边栏与其后端服务器进行交互，以方便员工操作，避免造成员工在多个页面之间进行跳转操作。
例如：企业已有一个提交工单、导入订单的网页，企业可以创建自定义卡片，卡片链接设置为提交工单、导入订单网页的url，将这些卡片集成到侧边栏，员工就可以在侧边栏上对应的卡片上提交工单、导入订单。
接入指南
流程概述
接入步骤
- 实现一个自定义卡片后端服务器。后端需要实现一个接收code的后端接口。后端主要用来接收code，调用 OpenAPI接口获取数据，向前端返回数据。
- 实现一个自定义卡片前端页面并挂载在后端服务器上。前端会以iframe方式引入到「客户画像」侧边栏中。前端页面应该处理来自员工的交互，并根据情况调用【前端sdk接口】控制主体页面（即客户画像页面）的行为。同时因为前端会向后端服务器请求数据，前端需要维护登录态以防止被恶意攻击。
- 创建和配置自定义卡片模块。建议可见范围仅设置为开发者，以方便调试。
- 微伴侧边栏预览和调试。在可见范围内的企微账号中，打开侧边栏即可预览和调试卡片。
交互时序图：
后端服务器
接收code的后端接口
企业开发者需要在卡片后端开发该接口，暴露给微伴侧边栏进行调用。
员工打开侧边栏，此时初始化卡片，侧边栏会向卡片链接发起请求，请求中携带code，企业开发者需要在卡片链接对应的服务中配置接收code的后端接口。
请求方式：GET
请求地址：IFRAME_URL?corp_id=CORP_ID&code=CODE&origin=ORIGIN
query参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| corp_id | str | 是 | 公司id |
| code | str | 是 | 信息兑换凭证 |
| origin | str | 是 | 请求源 |
返回渲染页面
自定义卡片模块创建和配置
创建自定义卡片模块
- 进入「侧边栏管理」页面，点击「客户画像」，可以选择「单聊画像」或是「群聊画像」进行画像的配置管理，选择「单聊画像」，添加自定义画像；
- 选择「添加自定义画像」，输入画像名称，选择客服成员，只有选中的客服成员可见该侧边栏
- 选择「新增画像卡片」
- 编辑「新增画像卡片」页面，卡片链接需要填入公网网页链接。开启「默认隐藏」卡片会在侧边栏不可见，但是卡片前端代码依然会在侧边栏运行，卡片可以持续与后端交互，达到触发条件时，卡片可以调用wb.changeCardProperty使卡片可见。
配置自定义卡片布局
例如企业可以通过修改卡片的间距和高度，使得侧边栏的布局更加紧凑；例如企业可以选择勾选需要的卡片进行展示来精简侧边栏的布局；例如企业可以长按卡片并拖动以改变卡片展示的顺序
修改卡片的间距和高度
- 选择「画像卡片」工单信息进行修改
- 在「修改卡片」页面，将卡片的高度由600改为400，将卡片的上边距由150改为50
- 在「侧边栏展示」页面，侧边栏的卡片高度、上边距修改生效
API列表
OpenAPI接口
侧边栏自定义卡片开发高度依赖于微伴助手OpenAPI
OpenAPI 接口需要由开发者后端调用，不可由前端直接调用。调用时需要走 OpenAPI标准授权。
获取当前员工和客户信息
开放身份校验 -自定义侧边栏身份校验
接口将会返回客户id(staff_id)，客户id(external_user_id)等信息。
根据这些信息通过OpenAPI的其他接口例如 获取员工详情，获取客户详情 等进行进一步的数据开发。
前端sdk接口
功能概述
前端sdk通过数据存取和自定义事件接口，给自定义卡片开发者提供了纯前端的跨卡片/iframe通信和数据传输的能力，让开发者无需通过后端接口就能在多个同页面的卡片间共享数据或进行交互联动
引入JS文件
在需要调用JS接口的页面引入如下JS文件：https://mpa.oss-cn-hangzhou.aliyuncs.com/weiban-prod/weiban-client-js-sdk.0.2.js
示例
<script src="https://mpa.oss-cn-hangzhou.aliyuncs.com/weiban-prod/weiban-client-js-sdk.0.2.js"></script>
Copy
刷新页面
刷新微伴页面
wb.refresh()
Copy
显示对话框
toast 类型
显示一个toast
wb.showDialog("toast", toastType, message)
Copy
参数说明
| 参数 | 类型 | 说明 | ||||
|---|---|---|---|---|---|---|
| toastType | "success" \ | "warning" \ | "error" | 成功 \ | 警告 \ | 失败 |
| message | string | 弹出消息 |
全屏页面类型
显示一个全屏页面，页面会用iframe方式载入，行为和自定义卡片一致
wb.showDialog("page", url)
Copy
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| url | string | 页面链接 |
抽屉类型
在页面底部显示一个抽屉，抽屉会用iframe方式载入，行为和自定义卡片一致
wb.showDialog("drawer", url, height)
Copy
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| url | string | 页面链接 |
| height | number | 弹窗高度，设计稿对应750px |
变更卡片属性
设置卡片可见性
wb.changeCardProperty("visibility", value)
Copy
参数说明
| 参数 | 类型 | 说明 | ||
|---|---|---|---|---|
| value | "visible" \ | "hidden" | 可见 \ | 隐藏 |
设置卡片高度
wb.changeCardProperty("height", value)
Copy
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| value | number | 卡片高度，设计稿对应750px |
设置卡片上边距
wb.changeCardProperty("marginTop", value)
Copy
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| value | number | 卡片上边距，设计稿对应750px |
数据存取
给自定义卡片开发者提供了纯前端的跨卡片/iframe数据传输的能力，让开发者无需通过后端接口就能在多个同页面的卡片间共享数据
获取数据
wb.getStorageData(scope,key,callback)
Copy
参数说明
| 参数 | 类型 | 说明 | ||
|---|---|---|---|---|
| scope | "session" \ | "target" \ | "global" | session:临时会话，页面刷新消失target:针对同一个聊天对象是持久化的，多次打开对应同一聊天对象的侧边栏时数据不会消失global:持久会话，所有聊天对象都可以访问，页面刷新不会消失 |
| key | string | 需要获取值的键 | ||
| callback | function | 回调方法，参数为获取到的值 |
赋值数据
wb.setStorageData(scope,key,value)
Copy
参数说明
| 参数 | 类型 | 说明 | ||
|---|---|---|---|---|
| scope | "session" \ | "target" \ | "global" | session:临时会话，页面刷新消失target:针对同一个聊天对象是持久化的，多次打开对应同一聊天对象的侧边栏时数据不会消失global:持久会话，所有聊天对象都可以访问，页面刷新不会消失 |
| key | string | 需要赋值的键 | ||
| value | string | 需要赋值的值 |
自定义事件
给自定义卡片开发者提供了纯前端的跨卡片/iframe通信能力，让开发者无需通过后端接口就能在多个同页面的卡片间进行交互联动
设置自定义事件监听器
wb.addCustomEventListener(eventName,handler)
Copy
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| eventName | string | 事件名 |
| handler | function | 需要处理的回调函数 |
发送自定义事件
wb.sendCustomEvent(eventName,data)
Copy
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| eventName | string | 事件名 |
| data | any | 传递的数据 |
发送消息到当前会话框
// 发送方式
wb.sendCustomEvent('WB_SEND_CHAT_MESSAGE',{data})
//监听发送消息的调用返回
wb.addCustomEventListener('WB_SEND_CHAT_MESSAGE',(res)=>{
console.log(res)
})
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| eventName | WB_SEND_CHAT_MESSAGE | 指定事件名 |
| data | 如下介绍 | 传递的数据 |
// 传入参数和企业微信接收参数保持一致，即可。
const text = {
msgtype:"text",
text:{
content:"weiban"
}
}
// 举例
wb.sendCustomEvent('WB_SEND_CHAT_MESSAGE',text)
const image = {
msgtype:"image",
image:{
mediaid: "", //图片的素材id
}
}
// 举例
wb.sendCustomEvent('WB_SEND_CHAT_MESSAGE',image)
const video = {
msgtype:"video",
video:{
mediaid: "", //视频的素材id
},
}
// 举例
wb.sendCustomEvent('WB_SEND_CHAT_MESSAGE',video)
const file = {
msgtype: "file",
file:{
mediaid: "", //文件的素材id
}
}
// 举例
wb.sendCustomEvent('WB_SEND_CHAT_MESSAGE',file)
const news = {
msgtype:"news",
news:{
link: "", //H5消息页面url 必填
title: "", //H5消息标题
desc: "", //H5消息摘要
imgUrl: "", //H5消息封面图片URL
}
}
// 举例
wb.sendCustomEvent('WB_SEND_CHAT_MESSAGE',news)
const miniprogram = {
msgtype:"miniprogram",
miniprogram:{
//小程序的appid，企业已关联的任一个小程序
appid: "wx8bd80126147df384",
//小程序消息的title
title: "this is title",
//小程序消息的封面图。必须带http或者https协议头，否则报错 $apiName$:fail invalid imgUrl
imgUrl:"https://search-operate.cdn.bcebos.com/d054b8892a7ab572cb296d62ec7f97b6.png",
//小程序消息打开后的路径，注意要以.html作为后缀，否则在微信端打开会提示找不到页面
page:"/index/page.html",
}
}
// 举例
wb.sendCustomEvent('WB_SEND_CHAT_MESSAGE',miniprogram)