全时云会议SDK文档

版本号:6.12.1

发布时间:2023年5月29日

产品介绍

全时云会议SDK(Electron版本)提供包含界面的音视频会议功能,可帮助用户快速将音视频会议功能集成到自己的Electron app中。

快速开始

1.前提条件

  • Electron 12.0.0 以上版本
  • node 14.19.1

2.编译并运行demo

  • 下载云会议SDK 附带Electron demo
  • 安装依赖
windows 32位: npm run lib:pcmac: npm install
  • 启动/运行demo
npm run start

rundemo

  • 打包 demo
npm run package

3.集成SDK

入口文件

以Demo项目为例,入口文件位于: tangsdk/jsLib/index.js

  • 该文件是一个引用SDK的入口示例集成,开发者可以在这看到SDK提供的方法和事件定义
  • 开发者需要修改该文件中
    let sdkPath =  appPath + (isMac ? '/tangsdk/sdk/mac/Frameworks' : (isDev ? '/tangsdk/sdk/windows' : '/../tangsdk/sdk/windows'))

这一句的路径,该路径指的是在windows和Mac下对应SDK资源包的指向路径,具体路径见接下来的SDK资源包替换

  • 开发者将该文件拷贝至自己项目中,然后在主进程里引入即可

资源包替换

SDK资源包分为window SDK资源包和Mac SDK资源包,开发者需要先在自己项目中为这2个资源包新建好对应的存放目录,在本项目中,SDK资源包分别存放于

  • tangsdk/sdk/windows/win32
  • tangsdk/sdk/mac

接下来的SDK资源包替换以本项目中路径举例

Windows 32位 SDK资源包替换

SDK资源包目录结构:

  • MeetingSDK
    • Meeting
    • win32_bin
  1. 将tangsdk/sdk/windows/win32目录清空
  2. 将SDK资源包MeetingSDK目录下的Meeting文件夹复制到tangsdk/sdk/windows/win32
  3. 将SDK资源包MeetingSDK/win32_bin目录下的内容复制到tangsdk/sdk/windows/win32

替换之后tangsdk/sdk/windows/win32目录结构:

  • Meeting
  • glog.dll
  • MeetingSDK.dll
  • RPCTerminal.dll
  • tangmeeting_ui.node

Mac SDK资源包替换

SDK资源包目录结构:

  • MeetingSDK
    • Frameworks
  1. 将tangsdk/sdk/mac目录清空
  2. 将SDK资源包MeetingSDK目录下的Frameworks目录复制到tangsdk/sdk/mac,(注意:不是复制Frameworks目录里面的内容,而是复制Frameworks目录本身,并且不能更改Frameworks这个目录名称,复制完后tangsdk/sdk/mac下面应该有一个Frameworks目录)

打包

打包win32和x64版本的包时,需要修改package.json对应的配置

Windows 64位

"extraFiles": [
    {
        "from": "./tangsdk/sdk/windows/x64",
        "to": "./resources/tangsdk/sdk/windows/x64"
    }
],

Windows 32位

"extraFiles": [
    {
        "from": "./tangsdk/sdk/windows/win32",
        "to": "./resources/tangsdk/sdk/windows/win32"
    }
],

实现功能

初始化

在使用SDK的功能前,需要调用初始化方法, 参考Demo中 tangsdk/jsLib/index.js 文件

var TangMeeting = requireFunc(path.join(sdkPath, 'tangmeeting_ui.node'))
var tangMeeting = new TangMeeting.TangMeetingWrapper()  //或 new TangMeeting.TangMeetingWrapper('d:\\Logs\\') 自定义日志目录
tangMeeting.initialize()

入会 (参考tangsdk/jsLib/index.js)

/**
*@brief 进入会议
*@param pUserName 进入会议的用户的名字
*@param pMeetingCode 会议的参会密码(注意不含‘-’)
*@param videoEnable 是否默认开启视频
*@param audioEnable 是否默认打开音频
*@param showPreview 是否显示视频预览窗口
*@param extraData 用来在会议信息中显示的扩展数据
*/
tangMeeting.join(userName, meetingCode, videoEnable, audioEnable, showPreview, extraInfo)

主要功能

1.会议管理

a. 注册回调

tangMeeting.onEvent('meetingStatusChanged', onMeetingStatusChanged)
tangMeeting.onEvent('inviteContact', onInviteContact)
tangMeeting.onEvent('callUsers', onCallUsers)
tangMeeting.onEvent('meetingCreated', onMeetingCreated)
tangMeeting.onEvent('getMeetingInfo', onGetMeetingInfo)
tangMeeting.onEvent('loginResult', onLoginResult)
tangMeeting.onEvent('onActionResult', onActionResult)

b. 入会

/**
*@brief 进入会议
*@param pUserName 进入会议的用户的名字
*@param pMeetingCode 会议的参会密码(注意不含‘-’)
*@param videoEnable 是否默认视频
*@param audioEnable 是否默认打开音频
*@param showPreview 是否显示视频预览窗口
*@param extraData 用来在会议信息中显示的扩展数据 -- 注意这里接收的是一个string而不是Json对象,传入之前请先调用JSON.stringify
*/
tangMeeting.join(userName, meetingCode, videoEnable, audioEnable, showPreview, extraInfo)

调用时机:初始化之后

c. 使用UserID 入会

/**
*@brief 进入会议
*@param pUserId   进入会议的用户id
*@param pMeetingCode 会议的参会密码(注意不含‘-’)
*@param videoEnable 是否默认视频
*@param audioEnable 是否默认打开音频
*@param showPreview 是否显示视频预览窗口
*@param extraData 用来在会议信息中显示的扩展数据 -- 注意这里接收的是一个string而不是Json对象,传入之前请先调用JSON.stringify
*/
tangMeeting.joinByUserId(userId, meetingCode, videoEnable, audioEnable, showPreview, extraInfo)

调用时机:初始化以后 注意:使用此接口入会,会中的display name将自动识别为开通的账号的display name, 另外,如果使用约会人的userId, 会议密码即使用参会人密码,会中仍然是主持人

d. extraData说明

// extraData 是用来控制会中信息以及复制的邀请信息的显示隐藏和替换的 Json格式字符串
// 参考:hidden用来控制隐藏的字段,meetingInviteInfo用来控制额外显示或者替换原有的字段
var extraInfo = {
	hidden: ['H323', 'WebRTCUrl'], // 可传ExtraDataHiddenEnum枚举中的字符串
	meetingInviteInfo: [
    {
		key: 'url',   // 键名
		value: 'https://www.baidu.com', // 显示在会中信息以及邀请信息中的值
		type: 'show, copy',  // 可显示,可复制
		replace: 'joinUrl',  // 替换原有的joinUrl信息
	},
	{
		key: '测试1',
		value: 'test1',
		type: 'show',       // 只显示,不复制
		replace: '',
	},
	{
		key: '测试2',
		value: 'test2',     
		type: 'copy',       // 不显示,只复制
		replace: '',
	},
	{
		key: '测试3',
		value: 'test3',
		type: 'show, copy',
		replace: '',
	},
	]
}

export enum ExtraDataHiddenEnum {
	InviteInfoTitle = 'InviteInfoTitle', // 邀请信息标题
	CopyJoinUrlBtn = 'CopyJoinUrlBtn', // 复制会议链接按钮
	ConfHostName = 'ConfHostName', // 会议主持人姓名
	WebRTCUrl = 'WebRTCUrl', // webRtc入会链接
	LivePullUrl = 'LivePullUrl', // 直播链接
	AccessNumList = 'AccessNumList', // 电话入会
	AttendeePassCode = 'AttendeePassCode', // 参会人密码
	EventWatchword = 'EventWatchword', // 活动口令
	H323 = 'H323', // H323
	MeetingTitle = 'MeetingTitle', // 会议标题
	MeetingTime = 'MeetingTime', // 会议时间
	MeetingRoom = 'MeetingRoom', // 会议室
	ConferenceJoinUrl = 'ConferenceJoinUrl', // 会议链接
	MeetingSummary = 'MeetingSummary', // 备注
}

e. 退会

/**
*@brief 退出会议
*@terminate true时,表示主持人离开会议时是否自动结束会议,对参会人此参数无效
*@return void
*/
tangMeeting.stop(false)

调用时机:用户希望通过app控制退会

f. 反初始化

/**
*@brief 销毁TangMeetingSDK.该接口可将meetingSDK的实例杀掉,第三方APP退出之前应调用该接口,否则可能不能完全退出程序
*@return
*- == true 销毁成功
*- == false 销毁失败
*/
tangMeeting.uninitialize()

调用时机:用户app结束时,卸载sdk

g. 上传日志

/**
*@brief 上传日志
*@phoneNum 电话号码
*@description 对问题的简单描述
*@return void
*/
tangMeeting.uploadLog( phoneNum, description)

调用时机:初始化后任意时间

2. 配置界面属性

/**
*@brief 此接口用来定制界面做一些个性化设置,应在入会之前调用,且只需调用一次,多次调用无效。如没有个性化要求,此接口可以不调用
*@customConfigData Json格式的字符串,具体可配置项如下
*
*return
*-== true 设置成功
*-== false 设置失败(比如没有调用Initialize就调用本函数)
*/
tangMeeting.setCustomConfig(JSON.stringify(customConfig))

customConfigData示例:

{"colorTheme":1,"language":1, "customUI":{"inviteBtn":{"isShow":true}}} // 深色主题,英文,参会人也有邀请按钮

customConfig对象定义:

key value类型 描述
appName string 设置会议窗口显示名称
language number 设置会议界面的显示语言,0:简体中文(默认);1:英文
colorTheme number 设置会议界面的主题色, 1:深色主题; 2: 浅色主题(默认)
customUI object 设置会议界面中元素的自定义项,见customUI对象参考
openVideoWhenJoinMeeting boolean 入会是否开启视频,true: 开启; false: 不开启,如果调用入会接口TangMeetingJoin时,设置了videoEnable,则会覆盖该值
openVOIPWhenJoinMeeting boolean 入会是否连接VOIP,true: 连接; false: 不连接,如果调用入会接口TangMeetingJoin时,设置了audioEnable,则会覆盖该值
isMuteMicrophoneWhenJoin boolean 入会是否连接VOIP是否静音,true: 静音; false: 不静音,只有入会自动连接VOIP时,该值才起作用

customUI对象定义:

key value类型 描述
inviteBtn customBtnObject 邀请按钮
shareBtn customBtnObject 共享按钮
switchLayoutBtn customBtnObject 切换布局按钮
layoutType number 设置布局类型,1:平均(默认);2:全景;3:演讲;4:回型;5:上台; 6: 工字型; 7: 左右
audioBtn customBtnObject 音频设置按钮
videoBtn customBtnObject 视频设置按钮
recordBtn customBtnObject 录制按钮
attendeeBtn customBtnObject 参会人按钮
chatBtn customBtnObject 聊天按钮
lockBtn customBtnObject 锁定会议按钮
interactiveBtn customBtnObject 互动激励按钮
customerServiceBtn customBtnObject 客服按钮
aboutBtn customBtnObject 关于按钮
feedbackBtn customBtnObject 反馈按钮
isShowFootbar boolean 是否显示底部工具栏,true:显示(默认);false:隐藏
isShowMeetingInfo boolean 是否显示会议信息,true:显示(默认);false:隐藏
leaveBtn customBtnObject 离开按钮
isShowBulletOption boolean 是否显示弹幕选项,true:显示(默认);false:隐藏
isShowEmotionToolbar boolean 是否显示聊天表情,true:显示(默认);false:隐藏
isShowAudioGuide boolean 是否显示音频引导弹窗,true:显示(默认);false:隐藏,如果设置了入会自动连接VOIP,则该值不起作用
isShowEndMeeting boolean 是否显示结束会议按钮,true: 显示, false: 隐藏。 如果设置了false,则只能退会,不能结会

customBtnObject对象参考:

key value类型 描述
isShow boolean 是否显示,true:显示(默认);false:隐藏

调用时机:在初始化之后

3. 其他功能

a. 获取会议信息

/**
*@brief    通过会议Id获取会议信息
*@param meetingId 会议ID
*@return
*/
tangMeeting.getMeetingInfo(meetingId);

调用时机:初始化以后,通过会议ID获取会议详情, 详情通过回调 getMeetingInfo 返回

b. 登录

/**
*@brief    通过普通账号密码登录云会议
*@param pUserName 用户名
*@param pPassword 密码

*@return
*/
tangMeeting.login("Account","psw");

调用时机:初始化以后,登录状态通过 loginResult 回调返回

c. 使用authKey登录

/**
*@brief    通过auth key登录云会议
*@param userId 用户id
*@param authKey 通过open api获取的auth key
*@return
*/
tangMeeting.loginWithAuthKey(userId, authKey);

调用时机:初始化以后,登录状态通过 loginResult 回调返回

d. 设置authKey

/**
*@brief    设置auth key信息,存储在本地,以备后续使用(比如打开设置页面)
*@param userId 用户id
*@param authKey 通过open api获取的auth key
*@return
*/
tangMeeting.setAuthKey(userId, authKey);

调用时机:初始化以后

e. 打开设置页面

/**
*@brief    打开设置页面,必须先调用setAuthKey
*@return
*/
tangMeeting.openPersonalSetting();

调用时机:设置完auth key之后调用

f. 开启投屏

/**
*@brief    开启投屏,必须先调用loginWithAuthKey
*@return
*/
tangMeeting.startScreenCast();

调用时机:设置完loginWithAuthKey之后调用

g. 设置域名信息

/**
*@brief    设置域名信息,必须在初始化之前调用
*@param envConfig 环境信息,格式 {CasDomain: 'xxx', UCCDomain: 'xxx', UMSDomain: 'xxx', NetworkType: 0/1} NetworkType: 0 -- 公网, 1: 内网
*@return
*/
tangMeeting.setEnvConfig(envConfig);

调用时机:初始化之前

4. 回调事件说明

a. 会议状态回调

onMeetingStatusChanged(code)

b. 约会或邀请人后回调,code见 SDK code

/** 返回数据说明
 {"contactsInfo":"
    {
        "attendeePassCode":"参会人密码",
        "meetingId":"会议id",
        "conferenceJoinUrl":"入会链接",
        "confHostName":"会议主持人名称",
        "conHostId":"会议主持人 id",
        "title":"会议标题",
        "trigger":2}"}
 */
/** 返回数据demo
 {"contactsInfo":"
    {
        "attendeePassCode":"1673958948",
        "meetingId":"3436449",
        "conferenceJoinUrl":"https://n.qsh1.cn/k/klppX2dKa0",
        "confHostName":"微V测试06",
        "conHostId":"20384857",
        "title":"微V测试06的会议室",
        "trigger":2}"}
 */
onInviteContact(meetingInfo)

c. 创建会议回调

onMeetingCreated( errorCode, meetingId)

d. 获取会议信息回调


/**
* 获取会议信息的回调, 返回会议信息(meetingInfo)的JSON字符串
{
    id - 会议的id,
    title - 会议的标题,
    startTime - 会议的开始时间,
    attendees - 会议的参会人ID列表数组,
    hostId - 会议的主持人ID,
    hostName - 会议的主持人名字,
    pCode - 会议的参会人密码,
    hCode - 会议的主持人密码,仅在登录账户是该场会议的主持人时候返回,
}
*/

onGetMeetingInfo(errorCode , meetingInfo)

e. 登录回调

onLoginResult(errorCode)

f. 邀请外呼列表回调

/**
* 返回外呼邀请信息
返回的callUsers是一个Json数组
 [ 
    { 
        userName: name, 
        phoneNum: phoneNumber, 
        email: xxx@email.com
    }, 
]
*/

onCallUsers(callUsers)

g. 上传日志进度回调

/**
 * 返回上传日志的进度
 */

onUploadLogProgress(progress)

h. 上传日志结果回调

/**
 * 返回上传日志的结果
 */

onUploadLogResult(errorCode, downloadUrl)

i. 操作回调

/**
 * 返回上传日志的结果
 * param action 操作类型,见action type
 * param code 操作结果, 见 SDK code
 * message 错误描述
 */

onActionResult(action, code, message)

i. 对应的错误码与状态码

操作类型 Action type

含义
1 打开设置窗口
2 关闭设置窗口
3 打开投屏窗口
4 关闭投屏窗口

操作错误码 SDK code

含义
0 成功
100 登录失败
101 预约失败
102 入会失败
103 入会需要登录
104 登录的auth key无效
200 登录成功
201 预约成功
202 入会成功
300 退出会议
301 会议已结束
400 退出会中窗口
401 进入口令输入
410 没有或者authKey无效
411 使用authKey登录失败

常见问题

  1. 初始化路径不对 特别留意通常SDK都应该被放在应用的Frameworks目录,另外dev环境和app运行时,SDK路径在Electron环境下不一样,这里请具体参考demo里tangsdk/jsLib/index.js里的代码
    const sdkPath =  appPath + (isMac ? '/tangsdk/sdk/mac/Frameworks' : (isDev ? '/tangsdk/sdk/win32' : '/../tangsdk/sdk/win32'))
    var TangMeeting = requireFunc(path.join(sdkPath, 'tangmeeting_ui.node'))
    var tangMeeting = new TangMeeting.TangMeetingWrapper();
    
  2. 程序退出时崩溃 请注意在相应app退出事件,调用sdk的Uninit方法, 参考demo里的index.js代码 ``` js tangSDK.cleanUpSdk = function() { tangMeeting.stop(false) tangMeeting.uninitialize() // mac这里必须用before-quit,因为用的[NSAPP run] 获取的消息循环,在will-quit里应该已经没有这个消息循环了 }
    app.on('before-quit', ()=>{
    console.log('before-quit')
    tangSDK.cleanUpSdk()
})

```