通过webview接入G1互动白板
更新时间: 2024/07/24 13:59:48
本文介绍Android、iOS、Windows、macOS客户端如何通过 webview 使用互动白板的相关能力。
示例项目源码
详细的示例代码请参见互动白板示例项目源码。
实现方法
通过 webview 调用白板的 API 时序图如下图所示。
-
webview 调用
webPageLoaded
接口,通知客户端 webview 脚本加载成功。js
{ action: 'webPageLoaded', param: {} }
-
客户端收到
webPageLoaded
之后,请求加入房间。调用
jsLoginIMAndJoinWB
接口通知 Web 登录IM,并建立白板信令连接。js
{ action: 'jsLoginIMAndJoinWB', param: { account: string, nickname: string //非必须 debug: true | false, token: string, //IM 账号体系 密码, 通过md5算法加密的密码。现在调试阶段使用pwd明文密码也行,但是以后会禁止。 channelName: string, appKey: string, platform: 'android' | 'ios' | 'pc' | 'mac' | 'pad' //会影响工具栏的布局 record: true | false, /** * 指定客户端监听哪些白板状态变化。 * 请参考SDK接口中event:appState:change,查看能接收的状态 * * 比如设置 appStateToListen: ['page'], 则所有page相关的变化都会通知客户端 * * webview会通过webAppStateChange通知客户端该状态的最新数值 */ appStateToListen?: Array<string> /** * 请参考SDK接口中WhiteboardSDK.getInstance中的drawPluginParams */ drawPluginParams: any } }
-
webview 通过
webRoomStateChange
事件,向客户端同步房间连接状态。客户端可以根据该事件判断当前是否可以编辑。js
{ action: 'webRoomStateChange', param: { event: 'onwillreconnect' | 'onconnected' | 'onSyncStart' | 'onSyncFinish', /** * 如果当前处于连接状态,且同步已经完成,则isEditable为true。 * 注意,下面的参数并没有考虑drawPlugin.enableDraw是否设置为true。 * * 客户端用户应该在接到webRoomStateChange, 且isEditable为true,且设置了drawPlugin.enableDraw(true)之后,才可以修改白板的内容 */ isEditable: boolean } }
-
客户端通过
jsDirectCall
编辑白板。通过
jsDirectCall
直接操作白板 SDK 的drawPlugin
、toolCollection
、whiteboardSDK
、WhiteBoardSDKClass
对象。如果
jsDirectCall
的参数中设置了seqId
,webDirectCallReturn
返回结果时,会将seqId
一并返回。请您自行维护seqId,并通过
seqId
判断应该将序列号和哪一次jsDirectCall
匹配。示例代码如下:
js
{ action: 'jsDirectCall', param: { target: 'whiteboardSDK' | 'drawPlugin' | 'toolCollection' | 'WhiteBoardSDKClass' funcName: string //请参考SDK API文档。funcName为函数名 seqId?: number | string arg1?: any arg2?: any arg3?: any arg4?: any arg5?: any } }
例如调用
undo
操作的示例代码如下:js
{ action: 'jsDirectCall', param: { target: 'drawPlugin', funcName: 'undo' } }
开启编辑权限的示例代码如下:
js
{ action: 'jsDirectCall', param: { target: 'drawPlugin', funcName: 'enableDraw', arg1: true } }
调用
zoomTo
的示例代码如下:js
{ action: 'jsDirectCall', param: { target: 'drawPlugin', funcName: 'zoomTo', arg1: 0.3 , //缩放比例30% arg2: true //动画过渡至目标位置 } }
-
webview 通过
webDirectCallReturn
将返回值发送给客户端。如果客户端调用
jsDirectCall
时,设置了seqId
参数,会一并返回seqId
的值。js
{ action: 'webDirectCallReturn', param: { target: 'drawPlugin' | 'whiteboardSDK' | 'toolCollection' funcName: string //请参考API文档,action为接口名称 result: res //接口函数调用后返回的数据 seqId: number | string } }
-
退出登录。
客户端调用
jsLogoutIMAndLeaveWB
接口通知 webview 登出 IM。webview 会销毁白板信令通道,然后登出 NIM 账号。
js
{ action: 'jsLogoutIMAndLeaveWB', param: {} }
-
退出成功后,webview 会给客户端发送
webLeaveWB
事件。
其他事件
事件 | 描述 | 处理建议 |
---|---|---|
webAppStateChange | 在初始参数中设置appStateToListen 数组,当数组中代表的状态改变时, webview 会发送webAppStateChange 给客户端。 |
无 |
webToolCollectionEvent | 工具栏触发事件 | docAdd 和docDelete 事件:客户端可以根据此事件通知应用服务器记录当前用户关联的文档iconClick 事件:客户端界面变更 |
webCreateWBSucceed | 创建白板房间成功。 | 可以不用处理该事件 |
webCreateWBFailed | 创建白板频道失败。 | 请根据错误信息对业务代码进行调整。客户端应退出webview |
webLoginIMSucceed | 登录IM成功。仅在通过G1 登录白板时会触发此消息。 |
开发者应该在等到该事件之后,再调用 jsDirectCall 、 jsGetState 等接口 |
webLoginIMFailed | 登录IM失败。仅在通过G1 登录时会触发此消息。 |
请仔细检查您的用户名和 Token 是否匹配。 |
webLeaveWB | 白板连接中断。 | 客户端此时应该销毁 webview |
webLog | webview 运行时产生的日志。 | 建议客户端将这些日志保存下来,方便日后调试 |
webJsError | webview 内js运行异常。 | 客户端可根据此消息调试 |
webGetAuth | webview请求auth | 上传音视频、文档转码时webview会通知请求auth |
webAppStateChange
在初始参数中设置appStateToListen
数组,当数组中代表的状态改变时, webview 会发送webAppStateChange
给客户端。具体参数为:
js{
action: 'webAppStateChange',
param: {
name: string
data: res //更新后的应用状态, 这个值和drawPlugin.on('event:appState:change', (name, ...res))的res一样
}
}
webToolCollectionEvent
工具栏触发事件时,会给客户端发送webToolCollectionEvent
消息。目前工具栏共有三类事件:docAdd
, docDelete
, 以及iconClick
。
工具栏中docUpload
所代表的文档弹窗中,文档发生变化时,会触发docAdd
与docDelete
事件。客户端可以根据此事件通知应用服务器记录当前用户关联的文档。详情请参见文档与页面。
用户自定义工具栏按钮被点击时,会触发iconClick
事件,详情请参见自定义组件
jsinterface IDocEntity {
docId: string, //文档的唯一id,删除文档时使用
fileType: 'pdf' | 'ppt' | 'doc', //文档类型,会影响弹窗中文档的图标
name: string, //文档名称
showDelete?: boolean, //是否显示删除按钮,默认为不显示删除按钮
params: {
url: string,
width: number,
height: number
}[]
}
{
action: 'webToolCollectionEvent',
param: {
name: 'docAdd' | 'docDelete'
data: Array<IDocEntity>
}
}
{
action: 'webToolCollectionEvent',
param: {
name: 'iconClick',
toolName: 'custom-xxx',
option: undefined
}
}
{
action: 'webToolCollectionEvent',
param: {
name: 'iconClick',
toolName: 'custom-state-xxx',
option: {
state: string,
newState: string
}
}
}
webLog
webview 给客户端发送 webview 运行时产生的日志。建议客户端将这些日志保存下来,方便日后调试。
js{
action: 'webLog',
param: {
type: 'info' | 'error' | 'warn' | 'log' | 'debug',
msg: string
}
}
webCreateWBSucceed
创建白板房间成功。开发者可以不用处理该事件。
js{
action: 'webCreateWBSucceed',
param: {}
}
webCreateWBFailed
创建白板频道失败。请根据错误信息对业务代码进行调整。客户端应退出webview。
js{
action: 'webCreateWBFailed',
param: {
code: number,
msg: string
}
}
webLoginIMSucceed
登录IM成功。收到此消息说明传入的用户名和token正确。注意,仅在通过G1
登录时会触发此消息。
js{
action: 'webLoginIMSucceed',
param: {}
}
webLoginIMFailed
登录IM失败。请仔细检查你的用户名和 Token 是否匹配。如检查后仍遇到此问题,请联系网易云信技术支持。注意,仅在通过G1
登录时会触发此消息。
js{
action: 'webLoginIMFailed',
param: {
code: number,
msg: string
}
}
webLeaveWB
白板连接中断。客户端此时应该销毁 webview ,并查看中断原因。
js{
action: 'webLeaveWB',
param: {}
}
webJsError
webview 内js运行异常。客户端可根据此消息调试。
js{
action: 'webJsError',
param: {
msg: string
}
}
webGetAuth
webview
请求客户端返回auth
。auth
用于登陆白板服务器,请求上传资源,文档转码。客户端收到该消息后,应该向开发者的应用服务器请求auth
,然后通过jsSendAuth
返回auth
给webview
。
下面分别是webGetAuth
和jsSendAuth
的格式:
js{
action: 'webGetAuth',
param: {}
}
{
action: 'jsSendAuth',
param: {
code: 200, //若成功,返回200
nonce: 'xxxx', //长度小于128的随机字符串
curTime: Math.round(Date.now()/1000) //当前UTC时间戳,从1970年1月1日0点0分0秒开始到现在的秒数
checksum: sha1(appsecret + nonce + curTime)
}
}