小程序SDK API文档

---

1 请求接口

1.1 初始化配置

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

1.2 登录房间

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

streamList数组中stream的对象结构

1.3 鉴权登录房间

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

streamList数组中stream的对象结构

1.4 登出房间

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

1.5 发送自定义命令

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

回调参数说明：

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

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

1.6 设置推流地址选项

ZegoClient.setPreferPublishSourceType(sourceType) ，参数如下：

1.7 开始推流

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

1.8 结束推流

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

1.9 更新推流附加信息

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

1.10 设置拉流地址选项

ZegoClient.setPreferPlaySourceType(souceType) ，参数如下：

• 自动 表示首先从CDN拉流，在进行连麦时，切换到Zego服务器
  
• 注意 若设置为0且未配置CDN,会导致无拉流地址

1.11 开始播放流

ZegoClient.startPlayingStream(streamid, streamParams) , 参数如下:

1.12 停止播放流

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

1.13 小程序播放状态事件

ZegoClient.updatePlayerState(streamId, event, type) ，参数如下：

• 在小程序 <live-player> 和 <live-pusher> 组件中设置bindstatechange属性，小程序回调的事件完全透传给SDK
  
• SDK底层会根据event进行流状态更新，必须回调给SDK
  

1.14 小程序网络状态通知事件

ZegoClient.updatePlayerNetStatus(streamId, event, type) ，参数如下：

• 在小程序 <live-player> 和 <live-pusher> 组件中设置bindnetstatus属性，小程序回调的事件完全透传给SDK
  

1.15 请求连麦

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

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

1.16 邀请连麦

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

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

1.17 响应连麦结果

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

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

1.18 结束连麦

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

1.19 发送房间消息

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

1.20 释放流资源

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

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

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

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

1.22 发送可靠消息

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

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

1.23 向业务服务器转发消息

ZegoClient.sendRelayMessage(type, data, success, error) （如，直播答题中的观众答题），参数如下：

1.24 发送大房间的实时消息

ZegoClient.sendBigRoomMessage( msg_category,msg_type, msg_content, success, error) （如，直播答题中的观众评论），参数如下

1.25 更新混流信息

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.26 结束混流

ZegoClient.stopMixStream(mixStreamConfig, success, error)

mixStramConfig对象结构

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

1.27 开始播放混流

ZegoClient.startPlayingMixStream(mixStreamId, streamParams) , 参数如下:

• 播放混流的处理过程和播放普通流的处理过程一致

1.28 停止播放混流

ZegoClient.stopPlayingMixStream(mixStreamId) , 参数如下:

1.29 动态转推CDN

ZegoClient.publishTarget(cdnPublishConfig, success, error)

cdnPublishConfig对象结构

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

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_userid, from_idname, 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) , 参数如下:

chat_data对象结构：

2.8 获取到推拉流的Rtmp地址

ZegoClient.onStreamUrlUpdate(streamId, url, type) ，参数如下:

• 收到此回调后需要更新小程序 <live-player> 和 <live-pusher> 组件的src属性
• 根据type类型调用小程序接口启动推流或拉流
• 不更新src属性会导致小程序无法推拉流

2.9 拉流状态变更通知

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

• 小程序开始拉流时本接口回调start事件
  
• 小程序拉流失败时本接口回调stop事件，error为错误码。error > 10000 表示即构调度错误。否则表示小程序拉流错误
  

2.10 拉流质量回调

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

streamQuality对象结构：

• 如果没有调用updatePlayerNetStatus不会有此回调
  

2.11 推流状态变更通知

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

• 小程序开始推流时本接口回调start事件
  
• 小程序推流失败时本接口回调stop事件，error为错误码。error > 10000 表示即构调度错误。否则表示小程序拉流错误
  

2.12 推流质量回调

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

streamQuality对象结构：

• 如果没有调用updatePlayerNetStatus不会有此回调
  

2.13 房间成员变化回调

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

成员对象结构:

2.14 房间所有成员回调

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

成员对象结构:

2.15 收到请求连麦信令

ZegoClient.onRecvJoinLiveRequest(requestId, from_userid, from_username, roomid) ，参数如下：

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

2.16 收到邀请连麦信令

ZegoClient.onRecvInviteJoinLiveRequest(requestId, from_userid, from_username, roomid) ，参数如下：

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

2.17 收到结束连麦信令

ZegoClient.onRecvEndJoinLiveCommand(requestId, from_userid, from_username, roomid) ，参数如下：

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

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

2.19 收到大房间的实时消息

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

消息结构如下

2.20 更新房间当前在线人数

ZegoClient.onUpdateOnlineCount(roomId, userCount)

3 工具方法

3.1 小程序是否支持直播组件及是否已授权

ZegoClient.isSupportLive(sucCall, errCall);

sucCall(res)参数返回结果对象,参数如下；

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

状态码有以下类型：

3.2 获取当前sdk版本号

ZegoClient.getCurrentVersion()

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

4 直播组件<live-room>,<rtc-room>

4.1 说明

小程序sdk本质上只提供了即构实时音视频及信令等服务，在客户端播放拉流和推流，都是需要依赖微信小程序提供的,原生组件；开发者可以选择自己灵活整合两者之间的功能，同时即构也提供了将两者组合后的组件<live-room>,<rtc-room>

4.2 <live-room>和<rtc-room>区别

主要是应用场景不一样： live-room适用与单主播推流场景，默认观众从CDN拉流,推流mode为live模式；优先保证高质量音视频输出，低延迟优先级靠后 rtc-room适用于多主播场景，优先从服务器拉流，优先保证低延迟

live-room连麦时，自动切换城rtc模式，此时live-room和rtc-room两者之间没有区别

4.3 属性定义

4.4 方法

4.5 获取组件

组件以示例代码形式，存储在即构的 github 仓库上，组件代码放在 components 文件夹下；更多用法请下载参考示例代码。

4.6 特别说明

组件默认提供了常见的‘1v1’，‘1v3’，‘vertical1v3’,'wrap'视频排列格式，若不满足需求，可以拷贝任意一个 template，修改其中的 wxss 样式。

5 错误码列表