本文介绍Android、iOS、Windows、macOS客户端如何通过 webview 使用互动白板的相关能力。

示例项目源码

详细的示例代码请参见互动白板示例项目源码。

实现方法

通过 webview 调用白板的 API 时序图如下图所示。

1. webview 调用 webPageLoaded 接口，通知客户端 webview 脚本加载成功。

   js{
       action: 'webPageLoaded',
       param: {}
   }
   

2. 客户端收到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
       }
   }
   

3. webview 通过 webRoomStateChange 事件，向客户端同步房间连接状态。客户端可以根据该事件判断当前是否可以编辑。

   js{
       action: 'webRoomStateChange',
       param: {
           event: 'onwillreconnect' | 'onconnected' | 'onSyncStart' | 'onSyncFinish',
           /**
           * 如果当前处于连接状态，且同步已经完成，则isEditable为true。
           * 注意，下面的参数并没有考虑drawPlugin.enableDraw是否设置为true。
           *
           * 客户端用户应该在接到webRoomStateChange, 且isEditable为true，且设置了drawPlugin.enableDraw(true)之后，才可以修改白板的内容
           */
           isEditable: boolean
       }
   }
   

4. 客户端通过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         //动画过渡至目标位置
       }
   }
   

5. webview 通过webDirectCallReturn将返回值发送给客户端。

   如果客户端调用jsDirectCall时，设置了 seqId 参数，会一并返回 seqId 的值。

   js{
       action: 'webDirectCallReturn',
       param: {
           target: 'drawPlugin' | 'whiteboardSDK' | 'toolCollection'
           funcName: string  //请参考API文档，action为接口名称
           result: res     //接口函数调用后返回的数据
           seqId: number | string
       }
   }
   

6. 退出登录。

   客户端调用 jsLogoutIMAndLeaveWB 接口通知 webview 登出 IM。

   webview 会销毁白板信令通道，然后登出 NIM 账号。

   js{
       action: 'jsLogoutIMAndLeaveWB',
       param: {}
   }
   

7. 退出成功后，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)     
    }
}