Web JS SDK API 文档

下载pdf
更新时间:2019-12-20 16:24
本页目录
1 请求接口
1.1 初始化配置
1.2 登录房间
1.3 鉴权登录房间
1.4 登出房间
1.5 发送自定义命令
1.6 获取媒体设备信息
1.7 启动预览
1.8 停止预览
1.9 启用/关闭 摄像头
1.10 启用/关闭 麦克风
1.11 设置本地预览video的音频输出设备
1.12开始推流
1.13 切换推流采集设备
1.14 结束推流
1.15 更新流信息
1.16 筛选符合当前浏览器视频格式的url
1.17 开始播放流
1.18 停止播放流
1.19 设置拉流音频输出设备
1.20 设置推拉流质量回调间隔
1.21 请求连麦
1.22 邀请连麦
1.23 响应连麦结果
1.24 结束连麦
1.25 发送房间消息
1.26 释放流资源
1.27 设置是否关注房间成员变化
1.28 发送可靠消息
1.29 向业务服务器转发消息
1.30 发送大房间的IM消息
1.31 更新混流信息
1.32 结束混流
1.33 预加载音效资源
1.34 播放音效
1.35 暂停音效
1.36 恢复音效
1.37 释放音效资源
1.38 开始混音
1.39 停止混音
1.40 设置混音音量
1.41 动态转推CDN
2 回调接口
2.1 房间连接断开通知
2.2 被踢下线通知
2.3 主播信息更新
2.4 自定义命令消息通知
2.5 流更新通知
2.6 流状态变更通知
2.7 房间消息通知
2.8 拉流状态变更通知
2.9 拉流的首帧画面通知
2.10 拉流质量回调
2.11 推流状态变更通知
2.12 推流质量回调
2.13 房间成员变化回调
2.14 房间所有成员回调
2.15 收到请求连麦信令
2.16 收到邀请连麦信令
2.17 收到结束连麦信令
2.18 收到房间其他用户发送的可靠消息
2.19 收到大房间的IM消息
2.20 更新房间当前在线人数
3 工具方法
3.1 浏览器支持度检测
3.2 浏览器是否支持webrtc
3.3 浏览器是否支持H264编码
3.4 获取当前sdk版本号
3.5 获取流音量
3.6 视频截屏(保存到图片或下载)
3.7 录制视频
3.8 暂停录制视频
3.9 恢复录制视频
3.10 停止录制视频
3.11 保存录制视频
4 屏幕共享
4.1 使用说明
4.2 插件安装
4.3 方法调用
4.4推流示例(chrome)
5 信令错误码列表

1 请求接口

1.1 初始化配置

ZegoClient.config(option),配置参数如下:

参数 含义 类型 是否必填
option.appid appid 数值 必填
option.server 服务器地址 字符串 必填
option.idName 用户id 字符串 必填
option.nickName 用户昵称 字符串 必填
option.logLevel 本地log级别 0:debug 1:info 2:warn 3:error 98:report 100:disable 数值 必填
option.remoteLogLevel 上报log级别 0:debug 1:info 2:warn 3:error 100:disable 数值,默认为0 可选(建议上报)
option.logUrl 远程log服务器地址 websocket地址 字符串 可选
option.audienceCreateRoom 观众是否可以创建房间 布尔值 可选

1.2 登录房间

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

参数 含义 类型 是否必填
roomid 房间id 字符串 必填
role 角色类型,1:主播 2:观众 数值 必填
token 登录验证token 字符串 必填
success 成功回调函数 function(streamList) 必填
error 失败回调函数 function(err) 必填

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

参数 含义 类型
stream_id 流Id 字符串
anchor_id_name 流对应的用户Id 字符串
anchor_nick_name 流对应的用户昵称 字符串
extra_info 流附加信息 字符串

1.3 鉴权登录房间

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

参数 含义 类型 是否必填
roomid 房间id 字符串 必填
role 角色类型,1:主播 2:观众 数值 必填
token 登录验证token 字符串 必填
thirdToken 客户自定义验证token 字符串 必填
success 成功回调函数 function(streamList) 必填
error 失败回调函数 function(err) 必填

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

参数 含义 类型
stream_id 流Id 字符串
anchor_id_name 流对应的用户Id 字符串
anchor_nick_name 流对应的用户昵称 字符串
extra_info 流附加信息 字符串

1.4 登出房间

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

1.5 发送自定义命令

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

参数 含义 类型 是否必填
dstMembers 接收消息者列表 字符串数组 必填
customContent 自定义消息内容 字符串 或 object(支持最大1024字节) 必填
success 成功回调函数 function(seq, customContent) 必填
error 失败回调函数 function(err, seq, customContent) 必填

回调参数说明:

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

调用限制:
1.不能发送房间广播的自定义消息

1.6 获取媒体设备信息

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

参数 含义 类型 是否必填
deviceInfoCallback 媒体设备信息回调 function(deviceInfo) 必填
errorCallback 失败回调 function(error) 必填

deviceInfo对象结构如下:

参数 含义 类型
microphones 音频输入设备列表 对象数组
speakers 音频输出设备列表 对象数组
cameras 视频输输入设备列表 对象数组

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

参数 含义 类型
label 设备名称 字符串
deviceId 设备Id 字符串
  • 某些平台浏览器(如: Safari iOS)可能获取到的设备名称为空,建议再次调用此接口,即可获取到正确的设备名称
  • 该方法调用可以不初始化ZegoClient对象
  • 不同浏览器获取的设备ID可能会有所不同

1.7 启动预览

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

参数 含义 类型 是否必填
localVideo 本地预览的<video>对象 文档对象 必填
mediaStreamConstraints 音视频配置项 对象 必填
success 成功回调函数 function() 必填
error 失败回调函数 function(reason) 必填

mediaStreamConstraints的对象结构

参数 含义 类型
audio 是否需要音频 布尔值
audioInput 麦克风设备Id 字符串
video 是否需要视频 布尔值
facingMode 摄像头朝向,"user"表示前置摄像头,"environment"表示后置摄像头 字符串
videoInput 摄像头设备Id 字符串
videoQuality 视频质量等级 数值
horizontal 是否横屏视频 布尔值
externalCapture 是否使用外部来源 布尔值
externalMediaStream 外部提供MediaStream对象 MediaStream
noiseSuppression 是否开启降噪 布尔值
autoGainControl 是否开启自动增益 布尔值
echoCancellation 是否开启回声消除 布尔值
  • audioInput和videoInput可以不用指定,即不传或填undefined。不指定时使用默认设备
  • externalCapture = true 时,从<video>指定的视频源作为预览。目前只支持 Chrome 53 和 Firefox 47版本以上
  • 使用externalMediaStream时,mediaStreamConstraints增加 width / height / frameRate / bitRate 属性,需要把这四个属性也传递给SDK
  • 降噪、自动增益、回声消除三者默认为开启,若无特殊情况,建议客户保持这三项为true

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

facingMode参数取值

取值 说明
"user" 手机上的前置摄像头
"environment" 手机上的后置摄像头
  • 如果设置了facingMode参数,会忽略videoInput参数

videoQuality参数取值

取值 分辨率 帧率 码率
1 240 * 320 15 300K
2 480 * 640 15 800K
3 720 * 1280 20 1500K
4 width * height frameRate bitRate(k)

videoQuality == 4时:

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

horizontal属性说明:

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

1.8 停止预览

ZegoClient.stopPreview(localVideo),参数如下:

参数 含义 类型 是否必填
localVideo 本地预览的<video>对象 文档对象 必填
  • 推流过程中,停止预览可能会导致推流中断

1.9 启用/关闭 摄像头

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

参数 含义 类型 是否必填
localVideo 本地预览的<video>对象 文档对象 必填
enable 是否启用 布尔值 必填

1.10 启用/关闭 麦克风

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

参数 含义 类型 是否必填
localVideo 本地预览的<video>对象 文档对象 必填
enable 是否启用 布尔值 必填

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

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

参数 含义 类型 是否必填
localVideo 本地预览的<video>对象 文档对象 必填
audioOutput 音频输出设备 字符串或null 必填
  • 某些浏览器指定音频输出设备可能无效
  • 如果推流设置了音频输出设备,或者<video>没有设置静音属性,会听到自己的回声

1.12开始推流

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

参数 含义 类型 是否必填
streamid 推流Id 字符串 必填
localVideo 本地预览的<video>对象 文档对象 必填
extraInfo 流附加信息 字符串 可选
publishOption 推拉附加参数:鉴权、视频编码 {streamParams:'XXX',cdnUrl:'XX',videoDecodeType:'XX'} 可选
  • 鉴权参数streamParams格式如下:'zg_expired=XX&zg_nonce=XX&zg_token=XX',只有需要配置鉴权才传入(可选功能)
  • 转推客户自己cdn地址cdnUrl:先向即构申请开通,且填入完整的rtmp地址(可选功能)
  • 视频编码参数videDecodeType目前支持VP8与H.264,填写格式如 '{videoDecodeType: 'VP8'}','{videoDecodeType: 'H264'}',不传默认为H.264视频编码

1.13 切换推流采集设备

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

参数 含义 类型 是否必填
type 切换设备类型,'audio'或'video' 字符串 必填
localVideo 需要切换设备的<video><audio>对象 文档对象 必填
deviceId 设备id 字符串 必填
success 成功回调函数 function 选填
error 失败回调函数 function 选填
  • deviceId 可通过接口enumDevices 获得
  • 部分浏览器会出现无法更换麦克风设备的情况

1.14 结束推流

ZegoClient.stopPublishingStream(streamid),参数如下:

参数 含义 类型 是否必填
streamid 推流Id 字符串 必填
  • 停止推流时会停止预览

1.15 更新流信息

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

参数 含义 类型 是否必填
streamid 推流Id 字符串 必填
extraInfo 流附加信息 字符串 必填

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

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

参数 含义 类型 是否必填
streamId 流id string 可选

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

1.17 开始播放流

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

参数 含义 类型 是否必填
streamid 拉流id 字符串 必填
remoteVideo 拉流界面的<video>对象 文档对象 必填
audioOutput 音频输出设备 字符串 可选
playOption 播放附加参数(播放模式,鉴权) {playType:'audio',streamParams:'XXX', videoDecodeType:'XXX'} 可选
  • playType可以不设置,或者是'audio','video','all'中任意一个,表示拉纯音/视频和音视频
  • 鉴权参数streamParams格式如下:'zg_expired=XX&zg_nonce=XX&zg_token=XX',只有需要配置鉴权才传入,否则请忽略
  • 视频编码参数videDecodeType目前支持VP8与H.264,填写格式如 '{videoDecodeType: 'VP8'}','{videoDecodeType: 'H264'}',不传默认为H.264视频编码
  • audioOutput可以不设置,不设置时为默认音频输出设备
  • 某些浏览器指定音频输出设备可能无效
  • 若推流端为单主播模式需通过CDN拉流

1.18 停止播放流

ZegoClient.stopPlayingStream(streamid),参数如下:

参数 含义 类型 是否必填
streamid 流id 字符串 必填

1.19 设置拉流音频输出设备

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

参数 含义 类型 是否必填
streamid 拉流id 字符串 必填
audioOutput 音频输出设备 字符串 必填
  • 某些浏览器指定音频输出设备可能无效

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

ZegoClient.setQualityMonitorCycle(timeInMS) ,参数如下:

参数 含义 类型 是否必填
timeInMS 时间间隔,默认3000ms 数值,单位毫秒 必填
  • timeInMS的最小取值为1000

1.21 请求连麦

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

参数 含义 类型 是否必填
dest_id_name 目标用户IdName 字符串 必填
success 成功回调函数 function(seq) 必填
error 失败回调函数 function(err, seq) 必填
resultCallback 目标用户响应结果 function(result, fromUserId, fromUserName) 必填
  • resultCallback 必须设置,否则调用失败
  • 发送此信令成功后,目标用户会收到onRecvJoinLiveRequest回调

1.22 邀请连麦

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

参数 含义 类型 是否必填
dest_id_name 目标用户IdName 字符串 必填
success 成功回调函数 function(seq) 必填
error 失败回调函数 function(err, seq) 必填
resultCallback 目标用户响应结果 function(result, fromUserId, fromUserName) 必填
  • resultCallback 必须设置,否则调用失败
  • 发送此信令成功后,目标用户会收到onRecvInviteJoinLiveRequest回调

1.23 响应连麦结果

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

参数 含义 类型 是否必填
requestId 请求Id 字符串 必填
respondResult 响应结果 布尔值 必填
success 成功回调函数 function(seq) 必填
error 失败回调函数 function(err, seq) 必填
  • 在收到onRecvJoinLiveRequest / onRecvInviteJoinLiveRequest后调用此函数响应连麦结果
  • requestId 参数来自onRecvJoinLiveRequest / onRecvInviteJoinLiveRequest回调参数

1.24 结束连麦

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

参数 含义 类型 是否必填
destIdName 目标用户IdName 字符串 必填
success 成功回调函数 function(seq) 必填
error 失败回调函数 function(err, seq) 必填

1.25 发送房间消息

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

参数 含义 类型 是否必填
msg_category 消息业务类型 数值 1:聊天消息 2:系统消息 必填
msg_type 消息格式类型 数值 1:文本消息 2:图片url 3:文件url 必填
msg_content 消息内容 字符串 必填
success 成功回调函数 function(seq, msgId, msg_category, msg_type, msg_content) 必填
error 失败回调函数 function(err, seq, msg_category, msg_type, msg_content) 必填

1.26 释放流资源

ZegoClient.release(),释放ZegoClient资源,退出房间,并释放流资源, 参数无
调用之后会向Zego服务器发送登出信令,之后重置当前房间中用户与Zego服务器进行交互所需的关键数据,并置空websocket对象和销毁播放器对象

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

ZegoClient.setUserStateUpdate(update),默认为false,参数如下:

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

1.28 发送可靠消息

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

参数 含义 类型 是否必填
type 消息类型 字符串 '1':聊天消息 '2':系统消息 必填
data 消息内容 字符串 必填
success 成功回调函数 function(seq) 必填
error 失败回调函数 function(err, seq) 必填

1.29 向业务服务器转发消息

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

参数 含义 类型 是否必填
type 消息类型 字符串 '1':聊天消息 '2':系统消息 必填
data 消息内容 字符串 必填
success 成功回调函数 function(seq, result) 必填
error 失败回调函数 function(err, seq) 必填

1.30 发送大房间的IM消息

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

参数 含义 类型 是否必填
msg_category 消息业务类型 数值 1:聊天消息 2:系统消息 必填
msg_type 消息格式类型 数值 1:文本消息 2:图片url 3:文件url 必填
msg_content 消息内容 字符串 必填
success 成功回调函数 function(seq, messageId) 必填
error 失败回调函数 function(err, seq) 必填

1.31 更新混流信息

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

参数 含义 类型 是否必填
mixStreamConfig 混流配置信息 对象 必填
success 成功回调函数 function(mixStreamId, mixStreamInfop[]) 必填
error 失败回调函数 function(err, errorInfo) 必填

mixStramConfig对象结构

参数 含义 类型
outputStreamId 混流输出流ID 字符串
outputUrl 混流输出URL 字符串
outputBitrate 混流输出码率 数值 (必须,且大于0)
outputFps 混流输出帧率 数值 (必须,且大于0)
outputWidth 混流输出宽度 数值 (必须,且大于0)
outputHeight 混流输出高度 数值 (必须,且大于0)
outputAudioConfig 混流输出音频编码 数值(可选,默认为0)
outputAudioBitrate 混流输出音频码率 数值 (可选)
outputAudioChannels 混流输出声道数 数值 (可选)
outputBgColor 混流背景颜色 数值 (可选)
outputBgImage 混流背景图片 字符串 (可选)
streamList 混流输入流列表 数组 (不能为空)
extraParams 额外参数 数组 (可选)
  • 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里的一个元素,即每一条输入流的对象结构如下:

参数 含义 类型
streamId 输入流ID 字符串
top 目标位置,上 数值 >=0
left 目标位置,左 数值 >= 0
bottom 目标位置,下 数值 >= 0
right 目标位置,右 数值 >= 0
  • top, left, bottom, right必须为整型

mixStreamInfo对象结构如下:

参数 含义 类型
rtmpUrls 混流Rtmp地址 数组
hlsUrls 混流hls地址 数组
flvUrls 混流flv地址 数组

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

参数 含义 类型
key 参数类型 字符串
value 参数的值 字符串

1.32 结束混流

ZegoClient.stopMixStream(mixStreamConfig, success, error)

参数 含义 类型 是否必填
mixStreamConfig 混流配置信息 对象 必填
success 成功回调函数 function() 必填
error 失败回调函数 function(err) 必填

mixStreamConfig对象结构

参数 含义 类型
outputStreamId 混流输出流ID 字符串
outputUrl 混流输出URL 字符串
  • outputStreamId 和 outputUrl 必须二选一。如果两个都存在,会结束 outputStreamId 指定的混流

1.33 预加载音效资源

ZegoClient.preloadEffect(id, effectUrl, callBack)

参数 含义 类型 是否必填
id 音效资源id 数字 必填
effectUrl 音效资源地址 字符串 必填
callBack 回调函数 function(err) 选填
  • 预加载音效接口用于缓存音效文件,使之能够快速播放,优化性能
  • id 用于区分不同的音效资源,为数字类型,需保证唯一性
  • effectUrl 指音效文件的路径,支持在线地址,为保证通信的流畅,音效资源不应过大

1.34 播放音效

ZegoClient.playEffect(audioMixConfig, start, end)

参数 含义 类型 是否必填
audioMixConfig 播放音效配置信息 对象 必填
start 播放开始回调 function 选填
end 播放结束回调 function 选填

audioMixConfig对象结构

参数 含义 类型
streamId 需混音的流ID 字符串
effectId 已预先加载的音效资源id 数字
loop 是否循环播放 布尔值
playTime 音效开始播放位置 数字
replace 是否替换音轨 布尔值
  • audioMixConfig中streamId指的是需要播放音效的流id,每条流一次只能播放一个音效
  • audioMixConfig对象中loop、replace默认为false,playTime默认为0,即从头开始播放

1.35 暂停音效

ZegoClient.pauseEffect(streamid)

参数 含义 类型 是否必填
streamid 正在混音的流id 字符串 必填

1.36 恢复音效

ZegoClient.resumeEffect(streamid)

参数 含义 类型 是否必填
streamid 正在混音的流id 字符串 必填

1.37 释放音效资源

ZegoClient.unloadEffect(effectid)

参数 含义 类型 是否必填
effectid 音效资源id 数字 必填
  • 该接口用于释放内存中的某个预先加载音效资源,减少内存占用

1.38 开始混音

ZegoClient.startMixingAudio(streamid, localaudio, replace)

参数 含义 类型 是否必填
streamid 需要混音的流id 字符串 必填
localaudio 本地的<audio>对象 文档对象 必填
replace 是否替换音轨 布尔值 必填
  • 该接口需与1.34 播放音效 区分。sdk提供了两种混音方式,一种是通过1.33预加载的方式,混音后通过1.35暂停音效1.36恢复音效的接口对音效进行暂停恢复的操作。另一种则是当前通过传入本地<audio>对象的方式,这种方式对音效的暂停恢复则是通过操作<audio>对象完成。
  • replace 参数表示是否要替换麦克风音轨
  • 此种方式safari暂不支持

1.39 停止混音

ZegoClient.stopMixingAudio(streamid)

参数 含义 类型 是否必填
streamid 正在混音的流id 字符串 必填

1.40 设置混音音量

ZegoClient.setMixingAudioVolume(streamid, volume)

参数 含义 类型 是否必填
streamid 正在混音的流id 字符串 必填
volume 音效音量 数字 必填
  • volume表示音效音量,范围为 0~100,100表示原始音量
  • 设置混音音量接口适用于 1.341.38 两种混音方式

1.41 动态转推CDN

ZegoClient.publishTarget(cdnPublishConfig, success, error)

参数 含义 类型 是否必填
cdnPublishConfig CDN转推配置 对象 必填
success 成功回调 function 选填
error 失败回调 function 选填

cdnPublishConfig对象结构

参数 含义 类型
streamId 需要转推CDN的流ID 字符串
type 转推方式 字符串
appSecret 联系技术支持或控制台获取 字符串
pushUrl 转推CDN地址 字符串
  • type 仅可填"addpush","delpush","clearpush"三种类型,分别表示增加,删除,清空
  • 若需推多路CDN则type填 "addpush" 并多次调用该接口

2 回调接口

  • 以下所有回调接口调用都是通过赋值方式,接收回调;例如:
    ZegoClient.onDisconnect = function(err) {
     //处理回调逻辑.....
    }

2.1 房间连接断开通知

ZegoClient.onDisconnect(err) ,参数如下:

参数 含义 类型
err.code 错误码 字符串
err.msg 错误信息 字符串

2.2 被踢下线通知

ZegoClient.onKickOut(err) ,参数如下:

参数 含义 类型
err.code 错误码 字符串
err.msg 错误信息 字符串

2.3 主播信息更新

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

参数 含义 类型
anchor_userid 主播id 字符串
anchor_username 主播昵称 字符串
  • 登录成功后会回调主播信息

2.4 自定义命令消息通知

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

参数 含义 类型
from_idName 发送者id 字符串
from_nickName 发送者昵称 字符串
custom_content 自定义命令消息 字符串

2.5 流更新通知

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

参数 含义 类型
type 变更类型 数值,0:添加, 1:删除
streamList 变更流列表 对象数组

流信息对象结构:

参数 含义 类型
stream_id 流Id 字符串
anchor_id_name 流对应的用户Id 字符串
anchor_nick_name 流对应的用户昵称 字符串
extra_info 流附加信息 字符串

2.6 流状态变更通知

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

参数 含义 类型
streamList 变更流列表 对象数组

流信息对象结构:

参数 含义 类型
stream_id 流Id 字符串
anchor_id_name 流对应的用户Id 字符串
anchor_nick_name 流对应的用户昵称 字符串
extra_info 流附加信息 字符串

2.7 房间消息通知

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

参数 含义 类型
chat_data 消息内容 数组
server_msg_id 服务器最新消息id 数值
ret_msg_id 当前推送消息id 数值

消息对象结构:

参数 含义 类型
id_name 用户Id 字符串
nick_name 用户昵称 字符串
role 用户角色 数值
msg_id 消息Id 数值
msg_category 消息类别 数值
msg_type 消息类型 数值
msg_content 消息内容 字符串
send_time 发送时间 数值

2.8 拉流状态变更通知

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

参数 含义 类型
type 流状态类型 数值 start:0, error:1, retry: 2
streamId 流id 字符串

拉流失败时会返回error,error对象结构如下:

参数 含义 类型
code 错误码 字符串
msg 错误说明 字符串

错误码有以下类型:

错误码 含义
ZegoPlay.Error.Dispatch 调度信令失败,请联系技术支持
ZegoPlay.Timeout.Dispach 调度信令超时,请检查当前网络状况
ZegoPlay.Error.Token Token错误,请检查token是否正确
ZegoPlay.Timeout.Session 创建会话超时,请检查网络状况
ZegoPlay.Error.Session 创建会话失败,请联系技术支持
ZegoPlay.Timeout.RemoteOffer Server Offer 超时,请检查当前网络状况
ZegoPlay.Error.RemoteOffer Server Offer 错误,请联系技术支持
ZegoPlay.Error.CreateAnswer 创建 Answer 失败,请确认浏览器兼容性
ZegoPlay.Error.LocalDesc 本地 SDP 失败,请确认浏览器兼容性
ZegoPlay.Timeout.Desc 发送 SDP 超时,请检查当前网络状况
ZegoPlay.Timeout.Candidate 发送 Candidate 超时,请检查当前网络状况
ZegoPlay.Timeout.ServerCandidate 接收 Candidate 超时,请检查当前网络状况
ZegoPlay.Error.ServerCandidate 接收 Candidate 错误,请联系技术支持
ZegoPlay.Error.ConnectionFailed 媒体网络连接失败,请检查当前网络状态或联系技术支持
ZegoPlay.Error.ConnectionClosed 媒体网络连接关闭,请检查当前网络状态或联系技术支持
ZegoPlay.Error.SessionClosed 会话关闭,请联系技术支持
ZegoPlay.Error.SocketError WebSocket 连接失败,请检查当前网络状态

2.9 拉流的首帧画面通知

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

参数 含义 类型
streamId 流id 字符串
videoWidth 视频宽度 数值
videoHeight 视频高度 数值

2.10 拉流质量回调

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

参数 含义 类型
streamId 流Id 字符串
streamQuality 流质量 对象

streamQuality对象结构:

参数 含义 类型
videoBitrate 视频码率 数值
audioBitrate 音频码率 数值
videoFPS 帧率 数值
frameHeight 视频高度 数值
frameWidth 视频宽度 数值
videoTransferFPS 传输帧率 数值

2.11 推流状态变更通知

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

参数 含义 类型
type 流状态类型 数值 start:0, error:1, retry: 2
streamId 流id 字符串

拉流失败时会返回error,error对象结构如下:

参数 含义 类型
code 错误码 字符串
msg 错误说明 字符串

错误码有以下类型:

错误码 含义
ZegoPublish.Error.Dispatch 调度信令失败,请联系技术支持
ZegoPublish.Timeout.Dispach 调度信令超时,请检查当前网络状况
ZegoPublish.Error.Token Token错误,请检查token是否正确
ZegoPublish.Timeout.Session 创建会话超时,请检查网络状况
ZegoPublish.Error.Session 创建会话失败,请联系技术支持
ZegoPublish.Error.CreateOffer 创建 Offer 失败,请确认浏览器兼容性
ZegoPublish.Error.LocalDesc 本地 SDP 失败,请确认浏览器兼容性
ZegoPublish.Timeout.Desc 发送 SDP 超时,请检查当前网络状况
ZegoPublish.Timeout.ServerAnswer Server Answer 超时,请检查当前网络状况
ZegoPublish.Error.ServerAnsewer Server Answer 错误,请联系技术支持
ZegoPublish.Error.RemoteDesc Server Desc 错误,请联系技术支持
ZegoPublish.Timeout.Candidate 发送 Candidate 超时,请检查当前网络状况
ZegoPublish.Timeout.ServerCandidate 接收 Candidate 超时,请检查当前网络状况
ZegoPublish.Error.ServerCandidate 接收 Candidate 错误,请联系技术支持
ZegoPublish.Error.ConnectionFailed 媒体网络连接失败,请检查当前网络状态或联系技术支持
ZegoPublish.Error.ConnectionClosed 媒体网络连接关闭,请检查当前网络状态或联系技术支持
ZegoPublish.Error.SessionClosed 会话关闭,请联系技术支持
ZegoPublish.Error.SocketError WebSocket 连接失败,请检查当前网络状态

2.12 推流质量回调

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

参数 含义 类型
streamId 流Id 字符串
streamQuality 流质量 对象

streamQuality对象结构:

参数 含义 类型
videoBitrate 视频码率 数值
audioBitrate 音频码率 数值
videoFPS 帧率 数值
videoTransferFPS 传输帧率 数值

2.13 房间成员变化回调

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

参数 含义 类型
roomId 房间Id 字符串
userList 成员列表 对象数组

成员对象结构:

参数 含义 类型
action 行为 数值 1:进入房间 2:退出房间
idName 用户id 字符串
nickName 用户昵称 字符串
role 角色类型 数值 1:主播 2:观众
logintime 登录时间 字符串

2.14 房间所有成员回调

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

参数 含义 类型
roomId 房间Id 字符串
userList 成员列表 对象数组

成员对象结构:

参数 含义 类型
idName 用户id 字符串
nickName 用户昵称 字符串
role 角色类型 数值 1:主播 2:观众

2.15 收到请求连麦信令

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

参数 含义 类型
requestId 请求Id 字符串
from_idName 请求者userId 字符串
from_nickName 请求者userName 字符串
roomid 房间id 字符串
  • 回复连麦请求respondJoinLive时需要使用此requestId

2.16 收到邀请连麦信令

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

参数 含义 类型
requestId 请求Id 字符串
from_idName 邀请者userId 字符串
from_nickName 邀请者userName 字符串
roomid 房间id 字符串
  • 回复连麦请求respondJoinLive时需要使用此requestId

2.17 收到结束连麦信令

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

参数 含义 类型
requestId 请求Id 字符串
from_idName 连麦者userId 字符串
from_nickName 连麦者userName 字符串
roomid 房间id 字符串

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

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

参数 含义 类型
type 消息类型 字符串
seq 消息序列号 数值
data 消息内容 字符串

2.19 收到大房间的IM消息

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

参数 含义 类型
messageList 消息列表 对象数组
roomId 房间ID 字符串

消息结构如下:

参数 含义 类型
idName 用户ID 字符串
nickName 用户昵称 字符串
messageId 消息ID 字符串
category 消息分类 数值
type 消息类型 数值
content 消息内容 字符串
time 发送消息时间 数值

2.20 更新房间当前在线人数

ZegoClient.onUpdateOnlineCount(roomId, userCount)

参数 含义 类型
roomId 房间ID 字符串
userCount 在线人数 数值

3 工具方法

3.1 浏览器支持度检测

ZegoClient.supportDetection(success, error)

参数 含义 类型 是否必填
success 成功回调函数 function(result) 必填
error 失败回调函数 function(err) 可选

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

参数 含义 类型
capture 是否支持获取摄像头麦克风设备 布尔值
screenSharing 是否支持屏幕共享 布尔值
videoDecodeType 是否支持视频编码 object
webRtc 是否支持webRTC协议 布尔值

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

3.2 浏览器是否支持webrtc

ZegoClient.isSupportWebrtc() ,返回true或false;

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

3.3 浏览器是否支持H264编码

ZegoClient.isSupportH264(sucCallBack,errCallBack);

sucCallBack参数返回true或false,true代标支持;不支持H264的浏览器,不能推拉视频流

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

3.4 获取当前sdk版本号

ZegoClient.getCurrentVersion()

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

3.5 获取流音量

ZegoClient.getAudioInfo(localVideo, error)

参数 含义 类型 是否必填
localVideo 本地预览的<video>对象 文档对象 必填
error 失败回调函数 function(reason) 可选

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

3.6 视频截屏(保存到图片或下载)

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

参数 含义 类型 是否必填
videoElement 截取源<video>对象 文档对象 必填
imgElement 目标img对象 文档对象 必填
name 保存图像名称(不需要带格式后缀) string 必填

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

3.7 录制视频

ZegoClient.startRecord(videoElement)

参数 含义 类型 是否必填
videoElement <video>对象 文档对象 必填

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

3.8 暂停录制视频

ZegoClient.pauseRecord()

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

3.9 恢复录制视频

ZegoClient.resumeRecord()

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

3.10 停止录制视频

ZegoClient.stopRecord()

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

3.11 保存录制视频

ZegoClient.saveRecord(name)

参数 含义 类型 是否必填
name 保存视频名称(不需要带格式后缀) string 必填

该方法为静态方法,不需要先初始化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

火狐获取屏幕共享媒体流

参数 含义 类型
mediaSource 屏幕共享区域 只能是'screen', 'application', 'window'中一个
auido 是否捕捉声音 bool
callback(suc,mediaStream) 获取共享媒体流回调 suc是bool类型代表成功与否,mediaStream为获取到的媒体流

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

4.3.2 startScreenShotChrome

chrome获取屏幕共享媒体流

参数 含义 类型
callback(suc,mediaStream) 获取共享媒体流回调 suc是bool类型代表成功与否,mediaStream为获取到的媒体流

4.3.3 startScreenSharing

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

参数 含义 类型
screenConfig 屏幕共享选项 对象
audio 是否需要音频 布尔值
callBack 回调 Function

screenConfig 对象结构

参数 含义 类型
frameRate 屏幕共享帧率,默认15 数值

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 信令错误码列表

错误码 含义
ZegoClient.Success 成功
ZegoClient.Error.Param 参数错误
ZegoClient.Error.Timeout 超时
ZegoClient.Error.Network 网络错误
ZegoClient.Error.Kickout 用户被踢
ZegoClient.Error.Server 服务返回错误
ZegoClient.Error.Unknown 未知错误