Web JS SDK API 文档

---

1 请求接口

1.1 初始化配置

ZegoClient.config(option)，配置参数如下：

1.2 登录房间

ZegoClient.login(roomid, role, token, success, error) ，登录参数如下：

若配置了CDN则streamList也包含了stream的CDN播放地址（flv，m3u8，rtmp） streamList数组中stream的对象结构如下

1.3 鉴权登录房间

ZegoClient.loginWithAuthor(roomid, role, token,thirdToken， success, error) ，登录参数如下：

若配置了CDN则streamList也包含了stream的CDN播放地址（flv，m3u8，rtmp） streamList数组中stream的对象结构

1.4 登出房间

ZegoClient.logout，无参数；
调用之后会向Zego服务器发送登出信令，之后重置当前房间中用户与Zego服务器进行交互所需的关键数据，并置空websocket对象

1.5 发送自定义命令

ZegoClient.sendCustomCommand(dstMembers, customContent, success, error) ，参数如下：

回调参数说明：

• seq: 消息发送序号
• customContent: 发送内容
• err: 错误对象

1.6 获取媒体设备信息

ZegoClient.enumDevices(deviceInfoCallback, errorCallback),参数如下：

deviceInfo对象结构如下：

设备列表中的每一个元素类型相同，结构如下：

• 某些平台浏览器（如: Safari iOS）可能获取到的设备名称为空，建议再次调用此接口，即可获取到正确的设备名称
• 该方法调用可以不初始化ZegoClient对象
• 不同浏览器获取的设备ID可能会有所不同

1.7 启动预览

ZegoClient.startPreview(localVideo, mediaStreamConstraints, success, error) ，参数如下：

mediaStreamConstraints的对象结构

• audioInput和videoInput可以不用指定，即不传或填undefined。不指定时使用默认设备
  
• externalCapture = true 时，从<video>指定的视频源作为预览。目前只支持 Chrome 53 和 Firefox 47版本以上
• 使用externalMediaStream时，mediaStreamConstraints增加 width / height / frameRate / bitRate 属性，需要把这四个属性也传递给 SDK
• 降噪、自动增益控制、回声消除三者默认为开启，若无特殊情况，建议客户保持这三项为true

externalCapture 和 externalMediaStream 只在推第三方流（如屏幕共享，用户其他来源媒体流）情况下使用

facingMode参数取值

• 如果设置了facingMode参数，会忽略videoInput参数

videoQuality参数取值

videoQuality == 4时：

• mediaStreamConstraints增加 width / height / frameRate / bitRate(kbps) 属性
• 分辨率，帧率和码率分别取值自以上四个属性
• 自定义的分辨率和码率有可能浏览器不支持，会有error的错误回调

horizontal属性说明：

• 设置为true时，width和height互换

创建“媒体流播放组件”对象的预览接口

async startPreviewByStreamView(mediaStreamConstraints: ZegoMediaStreamConstraints ): Promise

其中，ZegoStreamView 是媒体流播放器组件对象。

示例代码：

// 创建预览并获取 StreamView 对象
zc.startPreviewByStreamView(previewConfig)
    .then(view => {
        // 挂载界面,localView 为 div 容器 id
        view.play("localView");
    })
    .catch(error => {
        alert("预览失败！" + JSON.stringify(error));
        throw error;
    });

1.8 停止预览

ZegoClient.stopPreview(localVideo)，参数如下：

• 推流过程中，停止预览可能会导致推流中断

销毁媒体流渲染组件上的媒体流对象

stopPreview(localVideo: HTMLMediaElement | ZegoStreamView): boolean

其中，ZegoStreamView 是媒体流播放器组件对象。

1.9 启用/关闭 摄像头

ZegoClient.enableCamera(localVideo, enable)，在开始预览之后才能调用。参数如下：

1.10 启用/关闭 麦克风

ZegoClient.enableMicrophone(localVideo, enable)，在开始预览之后才能调用。参数如下：

1.11 设置本地预览video的音频输出设备

ZegoClient.setLocalAudioOutput(localVideo, audioOutput)，参数如下：

• 某些浏览器指定音频输出设备可能无效
• 如果推流设置了音频输出设备，或者<video>没有设置静音属性，会听到自己的回声

1.12 开始推流

ZegoClient.startPublishingStream(streamid, localVideo, extraInfo,publishOption)，参数如下：

• 鉴权参数streamParams格式如下：'zg_expired=XX&zg_nonce=XX&zg_token=XX'，只有需要配置鉴权才传入（可选功能）
• 转推客户自己cdn地址cdnUrl：先向即构申请开通，且填入完整的rtmp地址（可选功能）
• 如需要传publishOption 则extraInfo必须传 类型是字符串 没有附加信息传入null占位
• 视频编码参数videDecodeType目前支持VP8与H.264，填写格式如 '{videoDecodeType: 'VP8'}'，'{videoDecodeType: 'H264'}'，不传默认为H.264视频编码

1.13 切换推流采集设备

ZegoClient.switchDevice(type, localVideo, deviceId, success, error)，参数如下：

• deviceId 可通过接口enumDevices 获得
• 部分浏览器会出现无法更换麦克风设备的情况

1.14 结束推流

ZegoClient.stopPublishingStream(streamid)，参数如下：

• 停止推流时会停止预览

1.15 更新流信息

ZegoClient.updateStreamExtraInfo(streamd, extraInfo) ，参数如下：

1.16 筛选符合当前浏览器视频格式的url

ZegoClient.filterStreamList(streamId) 一般用于CDN拉流

streamList为login成功回调， 该方法一般用于CDN拉流情况，该方法可通过浏览器及协议筛选出能够在当前页面播放的url地址
参数streamId为可选，不填流id默认选择拉到的第一条流

1.17 开始播放流

ZegoClient.startPlayingStream(streamid, remoteVideo, audioOutput, playOption) 开始播放流，参数如下：

• playType可以不设置，不设置 SDK 默认会根据拉到的实际设备状态选择是否拉音视频，或者是'audio','video','all'中任意一个，表示拉纯音/视频和音视频
• 鉴权参数streamParams格式如下：'zg_expired=XX&zg_nonce=XX&zg_token=XX'，只有需要配置鉴权才传入，否则请忽略
• streamType 参数为大小流模式选择，0为小流，1为大流，2为根据网络情况自动切换大小流模式
• 视频编码参数videDecodeType目前支持VP8与H.264，填写格式如 '{videoDecodeType: 'VP8'}'，'{videoDecodeType: 'H264'}'，不传默认为H.264视频编码
• audioOutput可以不设置，不设置时为默认音频输出设备
• 某些浏览器指定音频输出设备可能无效
• 若推流端为单主播模式需通过CDN拉流

远端用户渲染媒体流组件对象的拉流接口

async startPlayingByStreamView(streamID: string, playOption?: PlayOption): Promise

其中，ZegoStreamView 是媒体流播放器组件对象。

示例代码：

zc.startPlayingByStreamView(streamId, playOptions).then(view => {
    // 挂载界面, remoteView 为 div 容器 id
    view.play("remoteView");
}).catch(error => {
    alert("拉流失败！" + JSON.stringify(error));
    throw error;
});

1.18 停止播放流

ZegoClient.stopPlayingStream(streamid)，参数如下：

1.19 设置拉流音频输出设备

ZegoClient.setPlayAudioOutput(streamid, audioOutput)，设置拉流时streamid对应的音频输出设备，参数如下：

• 某些浏览器指定音频输出设备可能无效

1.20 设置推拉流质量回调间隔

ZegoClient.setQualityMonitorCycle(timeInMS) ，参数如下：

• timeInMS的最小取值为1000

1.21 请求连麦

ZegoClient.requestJoinLive(destIdName, success, error, resultCallback)，参数如下：

• resultCallback 必须设置，否则调用失败
  
• 发送此信令成功后，目标用户会收到onRecvJoinLiveRequest回调
  

1.22 邀请连麦

ZegoClient.inviteJoinLive(destIdName, success, error, resultCallback)，参数如下：

• resultCallback 必须设置，否则调用失败
  
• 发送此信令成功后，目标用户会收到onRecvInviteJoinLiveRequest回调
  

1.23 响应连麦结果

ZegoClient.respondJoinLive(requestId, respondResult, success, error) ，参数如下:

• 在收到onRecvJoinLiveRequest / onRecvInviteJoinLiveRequest后调用此函数响应连麦结果
  
• requestId 参数来自onRecvJoinLiveRequest / onRecvInviteJoinLiveRequest回调参数
  

1.24 结束连麦

ZegoClient.endJoinLive(destIdName, success, error) ，参数如下：

1.25 发送房间消息

ZegoClient.sendRoomMsg(msg_category, msg_type, msg_content, success, error)，参数如下：

1.26 设置是否关注房间成员变化

ZegoClient.setUserStateUpdate(update)，默认为false，参数如下：

• update参数设置为true后，SDK登录成功后会自动拉取当前房间所有成员列表通过onGetTotalUserList回调
  
• 之后进出房间的用户变化通过onUserStateUpdate回调
  
• 该设置为房间配置，只能是创建房间的人设置
  
• 在网络异常或其他情况下，SDK会再次拉取房间所有成员，再次回调onGetTotalUserList
  

1.27 发送可靠消息

ZegoClient.sendReliableMessage(type, data, success, error)，只用于大房间低频场景（如，直播答题中的题目推送），参数如下：

参数 type 表示可靠业务消息类型，不能超过 128 字节，不允许为空字符串，一个房间内只允许不超过 1 个不同的消息类型

1.28 向业务服务器转发消息

ZegoClient.sendRelayMessage(type, data, success, error),向业务服务器转发消息（如，直播答题中的观众答题），参数如下：

1.29 发送大房间的实时消息

ZegoClient.sendBigRoomMessage(msg_category ,msg_type , msg_content, success, error) 发送大房间的实时消息（如，直播答题中的观众评论），参数如下

1.30 更新混流信息

ZegoClient.updateMixStream(mixStreamConfig, success, error),发起（更新）混流信息

mixStramConfig对象结构

• outputStreamId 和 outputUrl 必须二选一。如果两个都存在，默认为 outputStreamId
• outputBgColor 为十六进制的RGB， 输入格式必须为 0xRRGGBBxx
• outputBgImage 需要提前在即构后台预设imageId, 输入格式为 preset-id://xxx
• outputAudioConfig 默认是0（可选3）。使用混流转码时，目标编码格式为VP8时该参数值为3；目标编码格式为H.264时该参数为0。与此同时，需要传入extraParams的对象，key为'video_encode'，value 为转换后的编码格式（'h264' 或 'vp8'）

streamList里的一个元素，即每一条输入流的对象结构如下：

• top, left, bottom, right必须为整型

mixStreamInfo对象结构如下：

extraParams里的一个元素，即每一个对象是K-V 结构：

1.31 结束混流

ZegoClient.stopMixStream(mixStreamConfig, success, error)

mixStreamConfig对象结构

• outputStreamId 和 outputUrl 必须二选一。如果两个都存在，会结束 outputStreamId 指定的混流

1.32 预加载音效资源

ZegoClient.preloadEffect(id, effectUrl, callBack)

• 预加载音效接口用于缓存音效文件，使之能够快速播放，优化性能
• id 用于区分不同的音效资源，为数字类型，需保证唯一性
• effectUrl 指音效文件的路径，支持在线地址，为保证通信的流畅，音效资源不应过大

1.33 播放音效

ZegoClient.playEffect(audioMixConfig, start, end)

audioMixConfig对象结构

• audioMixConfig中streamId指的是需要播放音效的流id，每条流一次只能播放一个音效
• audioMixConfig对象中loop、replace默认为false，playTime默认为0，即从头开始播放

1.34 暂停音效

ZegoClient.pauseEffect(streamid)

1.35 恢复音效

ZegoClient.resumeEffect(streamid)

1.36 释放音效资源

ZegoClient.unloadEffect(effectid)

• 该接口用于释放内存中的某个预先加载音效资源，减少内存占用

1.37 开始混音

ZegoClient.startMixingAudio(streamid, localaudio, replace)

• localaudio 混单路请直接传入<audio>对象 需要混多路的 请传入<audio>数组集合 1.8.0版本及以上支持
• 该接口需与1.34 播放音效 区分。SDK提供了两种混音方式，一种是通过1.33预加载的方式，混音后通过1.35暂停音效 与 1.36恢复音效的接口对音效进行暂停恢复的操作。另一种则是当前通过传入本地<audio>对象的方式，这种方式对音效的暂停恢复则是通过操作<audio>对象完成。
• replace 参数表示是否要替换麦克风音轨
• 此种方式safari暂不支持

1.38 停止混音

ZegoClient.stopMixingAudio(streamid)

1.39 设置混音音量

ZegoClient.setMixingAudioVolume(streamid, volume)

• volume表示音效音量，范围为 0～100，100表示原始音量
• 设置混音音量接口适用于 1.34 与 1.38 两种混音方式

1.40 动态转推CDN

ZegoClient.publishTarget(cdnPublishConfig, success, error)

cdnPublishConfig对象结构

• type 仅可填 "addpush"、"delpush"、"clearpush" 三种类型，分别表示增加，删除，清空
• 若需推多路CDN则type填 "addpush" 并多次调用该接口

1.41 修改推流参数

ZegoClient.setPublishStreamConstraints(streamID, constraints, success,error)

constraints对象结构

error对象结构如下：

• constraints所有属性均为选填，开发者仅需将要修改的属性值传递给SDK，不能传空对象
• 此接口可在推流途中修改推流相关参数，不建议频繁修改

1.42 设置音浪回调

ZegoClient.setSoundLevelDelegate(boolean, interval)参数如下：

• 设置后将通过onSoundLevelUpdate 回调推拉流的音量大小
• 回调间隔越小，音浪数据对应更准确，间隔不建议过小

1.43 音浪更新回调

ZegoClient.onSoundLevelUpdate(soundLevelList) 参数如下：

soundLevelList对象结构：

• 该接口目前暂不兼容safari

1.44 推静态图片

ZegoClient.setDummyCaptureImagePath(filePath, localStream)

1.45 开启小流

ZegoClient.enableDualStream(localVideo)

• 该接口需要在调用 startPreview 成功后执行

1.46 设置小流参数

ZegoClient.setLowStreamParameter(localVideo, constraints)

constraints 对象结构

• 该接口需要在调用 enableDualStream 前调用

2 回调接口

• 以下所有回调接口调用都是通过赋值方式，接收回调；例如：

  ZegoClient.onDisconnect = function(err) {
   //处理回调逻辑.....
  }

2.1 房间连接断开通知

ZegoClient.onDisconnect(err) ，参数如下：

2.2 被踢下线通知

ZegoClient.onKickOut(err) ，参数如下：

2.3 主播信息更新

ZegoClient.onGetAnchorInfo(anchor_userid, anchro_username) ，参数如下：

• 登录成功后会回调主播信息

2.4 自定义命令消息通知

ZegoClient.onRecvCustomCommand(from_idName, from_nickName, custom_content) ，参数如下：

2.5 流更新通知

ZegoClient.onStreamUpdated(type, streamList) ，参数如下：

流信息对象结构：

2.6 流状态变更通知

ZegoClient.onStreamExtraInfoUpdated(streamList) ，（不包含增加，删除），参数如下:

流信息对象结构：

2.7 房间消息通知

ZegoClient.onRecvRoomMsg(chat_data, server_msg_id, ret_msg_id) ，参数如下：

消息对象结构：

2.8 拉流状态变更通知

ZegoClient.onPlayStateUpdate(type, streamId, error) ，参数如下：

拉流失败时会返回error，error对象结构如下：

错误码有以下类型：

2.9 拉流的首帧画面通知

ZegoClient.onVideoSizeChanged(streamId, videoWidth, videoHeight) ，参数如下:

2.10 拉流质量回调

ZegoClient.onPlayQualityUpdate(streamId, streamQuality) ，参数如下：

streamQuality对象结构:

2.11 推流状态变更通知

ZegoClient.onPublishStateUpdate(type, streamId, error) ，参数如下：

推流失败时会返回error，error对象结构如下：

错误码有以下类型：

2.12 推流质量回调

ZegoClient.onPublishQualityUpdate(streamId, streamQuality) ，参数如下：

streamQuality对象结构：

2.13 房间成员变化回调

ZegoClient.onUserStateUpdate(roomId, userList) ，设置setUserStateUpdate为true时回调。参数如下：

成员对象结构：

2.14 房间所有成员回调

ZegoClient.onGetTotalUserList(roomId, userList) ，设置setUserStateUpdate为true时回调。参数如下：

成员对象结构:

2.15 收到请求连麦信令

ZegoClient.onRecvJoinLiveRequest(requestId, from_idName, from_nickName, roomid) ，参数如下：

• 回复连麦请求respondJoinLive时需要使用此requestId
  

2.16 收到邀请连麦信令

ZegoClient.onRecvInviteJoinLiveRequest(requestId, from_idName, from_nickName, roomid) ，参数如下：

• 回复连麦请求respondJoinLive时需要使用此requestId
  

2.17 收到结束连麦信令

ZegoClient.onRecvEndJoinLiveCommand(requestId, from_idName, from_nickName, roomid) ，参数如下：

2.18 收到房间其他用户发送的可靠消息

ZegoClient.onRecvReliableMessage(type, seq, data) ，参数如下：

2.19 收到大房间的实时消息

ZegoClient.onRecvBigRoomMessage(messageList, roomId) ，参数如下：

消息结构如下：

2.20 更新房间当前在线人数

ZegoClient.onUpdateOnlineCount(roomId, userCount)

2.21 远端摄像头状态通知

ZegoClient.onRemoteCameraStatusUpdate(streamID, status)

status状态为0表示开启，其它数值表示为关闭状态

2.22 远端麦克风状态通知

ZegoClient.onRemoteMicStatusUpdate(streamID, status)

status状态为0表示开启，其它数值表示为关闭状态

2.23 屏幕共享中断回调

ZegoClient.onScreenSharingEnded(mediaStream)

• 该回调在用户点击取消分享或其它情况导致屏幕共享中断时触发

2.24 音频设备状态变更回调

ZegoClient.OnAudioDeviceStateChanged(msg)

msg对象结构

deviceInfo对象结构

• 该回调在音频设备变化时候触发

2.25 视频设备状态变更回调

ZegoClient.OnVideoDeviceStateChanged(msg)

msg对象结构

deviceInfo对象结构

• 该回调在视频设备变化时候触发

2.26 推流使用设备状态变更回调

ZegoClient.onDeviceError(msg)

msg对象结构

errorCode 0：正常 -6：异常

• 该回调在推流设备状态变化时候触发

2.27 网络中断回调

ZegoClient.onTempBroken()

• 该回调在网络中断时触发

2.28 重连成功回调

ZegoClient.onReconnect()

• 该回调在网络中断重连恢复后触发

2.29 采集、编码、渲染异常或恢复回调

ZegoClient.onExceptionUpdate(streamID, eventData)，参数定义如下：

eventData 的对象结构：

事件码描述（异常相关）：

事件码描述（从异常变正常）：

3 工具方法

3.1 浏览器支持度检测

ZegoClient.supportDetection(success, error)

该方法为静态方法，不需要先初始化ZegoClient对象
result结构如下：

videoDecodeType 目前包含 H264与VP8属性，类型为布尔值，表示当前浏览器是否支持H264与VP8视频编码

3.2 获取当前SDK版本号

ZegoClient.getCurrentVersion()

该方法为静态方法，不需要先初始化ZegoClient对象

3.3 获取流音量

ZegoClient.getAudioInfo(localVideo, error)

方法返回souder对象，该对象包含流当前音量属性:instant

3.4 视频截屏（保存到图片或下载）

ZegoClient.takeSnapShot(videoElement,imgElement) ZegoClient.saveSnapShot(videoElement,name)

这两个方法为静态方法，不需要先初始化ZegoClient对象

3.5 录制视频

ZegoClient.startRecord(videoElement,constraints)

constraints 结构如下：

该方法为静态方法，不需要先初始化ZegoClient对象

3.6 暂停录制视频

ZegoClient.pauseRecord()

该方法为静态方法，不需要先初始化ZegoClient对象

3.7 恢复录制视频

ZegoClient.resumeRecord()

该方法为静态方法，不需要先初始化ZegoClient对象

3.8 停止录制视频

ZegoClient.stopRecord()

该方法为静态方法，不需要先初始化ZegoClient对象

3.9 保存录制视频

ZegoClient.saveRecord(name)

该方法为静态方法，不需要先初始化ZegoClient对象

4 屏幕共享

4.1 使用说明

• web屏幕共享功能，目前只支持桌面端(例如window和mac)的chrome和火狐浏览器以及最新的safari浏览器，chrome 72及72版本以上无需下载插件，72版本以下需要下载即构共享插件

• 分享功能只能获取到系统扬声器声音，外部麦克风需另外推流（例子：电脑播放音乐可以采集到，对着电脑说话声音采集不到）

• 当同时推多路流时，建议音频只推一路，防止回音

4.2 插件安装

4.2.1 方法一

• 点击下载即构共享插件，并解压；

• 打开你的 Chrome 浏览器，点击屏幕右上方的扩展按钮，选择 更多工具 > 扩展程序， 打开开发者模式 > 加载已解压的扩展程序 > 选择 解压的 即构共享插件文件夹，即可完成安装

4.2.2 方法二

• 进入chrome网上应用商店搜索 Screensharing Extension by Zego 即构共享插件；

• 选择添加至chrome即可

4.3 方法调用

火狐获取屏幕区域需要在代码中传入参数，chrome则会以弹窗形式给用户提供选择

4.3.1 startScreenShotFirFox

火狐获取屏幕共享媒体流

screen 代表整个屏幕；application 代表某个应用； window 代表某个应用的某个窗口

4.3.2 startScreenShotChrome

chrome获取屏幕共享媒体流

4.3.3 startScreenSharing

无插件获取屏幕共享媒体流

screenConfig 对象结构

4.3.4 stopScreenShot

stopScreenShot( )

4.4推流示例（chrome）

   zg.startScreenShotChrome(function (suc,mediastream) {

       previewVideo.srcObject = mediastream;//本地预览

       // 与正常推流一样，需要先调用SDK预览接口，成功后再推流 ，
       // 需要注意的是  mediaStreamConstraints.externalCapture = true (必须)
       zg.startPreview(localVideo, mediaStreamConstraints, function() {

         zg.startPublishingStream(streamid, localVideo, extraInfo);

       }, error)

    })

更多github示例

5 信令错误码列表