互动工具开发文档
I. 名词解释
客户编码(customerCode):string类型, 用于区分不同的客户,每个客户分别对应不同的编码。
会议ID(conferenceId):string类型, 逻辑会id,预约一场会议(直播)会生成唯一的id。
临时会议ID(tempConfId):string类型, 每个逻辑会议对应1个或多个临时会议,开启一次逻辑会议会产生一个临时会议id。
全时用户ID(userId):string类型,标识注册到全时的用户。
会议临时用户ID(tempUserId):string类型, 用户入会一次会生成针对这场临时会议的临时用户id。
观众ID(accId):string类型,未入会的观众id,通常是观看直播的观众。
姓名(name):string类型。
手机号(phone):string类型。
邮箱(email):string类型。
用户角色(role):number类型, 主持人,联席主持人,嘉宾,观众,评委,选手等等。
终端系统类型(system):string类型,windows, mac, android, ios, ipad,h5, miniprogram。
互动ID(interactionId):string类型,每发起一次互动产生一个唯一的id,通常是uuid。
II. 开发流程
1.项目的html文件中引入qs-js-sdk接口文件
<!-- 在html文档中 -->
<script type="text/javascript"src="https://xxx/qs-js-sdk.js">
</script>
引入此文件会在引入一个全局变量qssdk
2.通过config接口注入权限验证配置(待定,如果没有则跳过)
由于中台提供的接口能力和中台业务功能密切相关,所以调用jsApi之前需要进行鉴权操作
qssdk.config({
interactiveToolId: '', // 互动工具id
timestamp: 0, // 时间戳,毫秒级
nonceStr: '', // 随机字符串
signature: '', // 签名
jsApiList : [], // 需要调用的API列表
success: function(result) {
// 成功回调,可以在成功之后使用 qssdk.xx jsapi
},
fail: function() {
// 失败回调
}
})
3.调用JSAPI
所有接口都为异步,且必须在收到ready后调用.
- 所有接口如果在页面刚加载时调用,必须在 window.qssdk.ready(function(){}) 回调函数里调用
- 接受一个 object 类型的参数
- 成功回调 success
- 失败回调 fail。
以获取互动模板数据举例
window.qssdk.ready(function(){
qssdk.interaction.getInteractiveToolInfo({
templateId: '',
success: function(res){},
fail: function(res){}
})
})
4.JSAPI列表
详情见另一份文档 --- 第三方互动工具交互接口文档
5.会中参会人响应互动
所有端(包括h5和微信小程序端)嘉宾,观众等非主持人角色响应互动,此页面由开发者提供responseUrl对应页面,
开发者需要调用,qssdk.interaction.getSelf() 来获取当前用户是否为主持人,参会人端和主持人端由开发者控制对应跳转不同页面
响应此页面时,会在响应url后面拼接一个参数?uuid=xx,开发者可以通过此id在自己端拿到此次互动相关数据
H5以iframe的方式响应互动url,小程序以webview+视频小窗的方式,开发者可通过调用jssdk接口监听互动消息,发送互动消息,最小化并互动窗口并以悬浮图标显示,关闭互动窗口等。响应互动后,开发者后台服务需要存储响应互动信息,包括互动id,互动类型,互动数据,发起者信息(客户编码等名词解释的数据),
6.会中主持人人响应互动
在嘉宾,观众等响应互动时,发起互动者或会中其他主持人和联席主持人会调转到正在互动的数据概览页面,对应responseUrl页面
开发者需要调用,qssdk.interaction.getSelf() 来获取当前用户是否为主持人,参会人端和主持人端由开发者控制对应跳转不同页面
此页面由开发者提供,同样会在响应url后面拼接一个参数?uuid=xx,点击结束互动,调用 qssdk.interaction.endInteraction(uuid), 成功后会出现互动结果页面,对应结果统计页面,开发者根据互动交互进行实现(根据不同的互动类型可能交互会不同)。
7. 注意事项
-
只有pc端主持人和联席主持人能发起互动,并且主持人和联席主持人不参与互动(如会中有多个主持人和联席主持人,某个人发起互动后所有主持人和联席主持人看到的是相同的页面)
-
主持人发起投票,跳转到发起互动页面,该页面由开发者提供(提前配置好互动类型,icon,发起互动url),以投票为例,部分互动会有会前提前编辑好的互动模板,开发者通过调用jssdk可获取模板列表,用户选中某个模板或可新建模板,点击发布后调用jssdk发起互动(发起互动接口支持开发者传入互动id,响应互动url,以悬浮图标提醒方式打开或直接打开开关等参数,注:若响应者打开url后有http请求,需要使用悬浮图标提醒方式进行响应,避免大方人数下参与互动者同时收到发起互动消息同时请求开发者互动服务)。
-
发起互动后,开发者后台服务需要存储发起互动信息,包括互动id,互动类型,互动数据,发起者信息(客户编码等名词解释的数据)
(注:广播互动消息大小不能超过1k,并限制单个用户广播频率)
三. 技术要求
- 后台服务要求
-
前端静态资源和后台应用接口动静分离,部署在全时域名下(支持全时微信小程序配置全时域名白名单后能正常访问)
-
互动数据存储使用mysql关系型数据库或mongodb文档型数据库,方便全时大数据系统同步相关的互动业务数据进行数据分析和统计
-
使用redis缓存提升互动业务接口访问性能,后台应用服务可横向扩展,单台服务器3000tps以上并发访问(推荐使用java或go语言开发互动服务接口,直播场景大并发访问要求)
-
使用全时的消息通道同步互动业务数据,单条消息大小不超过1K (直播场景大并发限制)
四. 本地调试说明
- 下载并安装云会议客户端
- 如果是新开发的一个互动应用,调试时需要在本地进行配置,打开云会议安装目录下面的config/interaction.config文件,填入开发者对应的互动应用相关信息
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<interaction>
<interactiveToolName>demo</interactiveToolName>
<typeId>xxx</typeId>
<iconUrl>xxx</iconUrl>
<floatWindowIconUrl>xxx</floatWindowIconUrl>
<templateEditUrl>xxx</templateEditUrl>
<templatePreviewUrl>xxx</templatePreviewUrl>
<maxTemplateNumber>10</maxTemplateNumber>
<startUrl>xxx</startUrl>
<responseUrl>xxx</responseUrl>
</interaction>
</configuration>
参数说明:
参数 |
说明 |
interactiveToolName
|
互动工具名称 |
typeId
|
互动工具类型id, 配置数字 |
iconUrl
|
互动工具图标 |
floatWindowIconUrl
|
互动工具浮动小球图标 |
templateEditUrl
|
互动工具模板创建和模板编辑页面地址 |
templatePreviewUrl
|
互动工具模板预览页面地址 |
maxTemplateNumber
|
互动工具最大模板数量,0表示不需要模板 |
responseUrl
|
互动工具响应页面地址,会中 |
startUrl
|
互动工具发起地址,会中 |
3. 登录云会议,邀请参会人创建一场会议,点击互动卡按钮,在弹窗中的创建里面可查看到刚刚配置的互动类型
会前可针对会议提前针对某类型互动编辑好模板,便于会中快速进行互动, 模板数据通常是针对某一次互动的做一些详细的配置。
对此类型的互动工具,要求开发者提供编辑,预览页面,通过编辑完成之后可以通过jssdk接口通知app进行存储。配置数据要求为json格式,大小低于100KB。
4. 点击新建,在弹出窗口内可以看到templateEditUrl对应的页面,此页面由开发者提供
此页面要嵌入qs-js-sdk.js文件,在用户编辑完成后,点击保存的时候,需要调用qssdk.interaction.setInteractiveToolInfo创建一个互动模板
window.qssdk.ready(function(){
qssdk.interaction.setInteractiveToolInfo({
templateId: ‘’,
data: {},
success: function(res){},
fail: function(res){}
})
})(PS: qssdk中的jsApi调用方式均为此)
5. 如果是选中了某一条进行预览或者编辑,则同样打开templatePreviewUrl和templateEditUrl对应的页面,由开发者提供
与创建模板不同的是,打开这2个窗口时,客户端会在打开的地址后面拼一个参数url?templateId=xxx,开发者可以通过该参数调用 qssdk.interaction.getInteractiveToolInfo 获知具体的模板数据,编辑接口同创建接口,qssdk.interaction.setInteractiveToolInfo
6. 点击‘加入会议’,并点击底部工具栏的 ‘互动工具’,此时可在弹出的互动工具中看到新增的一个互动应用
7. 点击对应的互动应用,在弹出的窗口内即可查看startUrl对应的页面,此页面由开发者提供
此页面要嵌入qs-js-sdk-1.0.0.js文件,然后调用
qssdk.interaction.getInteractiveToolInfoList接口获取此类型的互动模板列表数据
8. 此时如果需要发起互动,则需要调用qssdk.interaction. startInteraction
9. 参会人端在主持人发起互动后,会打开responseUrl对应的页面,此页面由开发者提供
下载开发接口说明文档: