多房间

---

1 功能简介

同一个用户可以同时加入多个房间，并同时在多个房间内推流、拉流、发送实时消息和接收消息回调。

1.1 应用场景

本功能可以隔离多个房间的消息及回调，实现更灵活的连麦业务。ZEGO 推荐用于跨房间连麦和在线教育的超级小班场景。

• 跨房间连麦

主播 A 与主播 B 进行跨房间连麦，主播 A 可以通知房间 A 中所有观众登录主播 B 的房间进行拉流，主播 B 同样可以通知房间 B 中所有观众登录主播 A 的房间进行拉流。

• 超级小班

老师进入大班房间推流，学生都登录大班房间拉流，同时登录小组房间与同组学生讨论和连麦。助教老师登录小组房间维持课堂秩序或解答学生问题。

2 前提条件

在实现多房间功能之前，请确保：

• 已在 ZEGO 控制台 创建项目，并申请有效的 AppID 和 AppSign，详情请参考 控制台 - 项目管理。
• 已在项目中集成 ZEGO LiveRoom SDK（2021年6月18日以后），实现基本的实时音视频功能，详情请参考 快速开始 - 集成 等。
• 已联系 ZEGO 技术支持开通多房间功能。

3 使用步骤

以同一用户加入两个房间为例，整体实现流程如下：

1. 在初始化 SDK 之前，将房间模式设置为多房间。
2. 初始化 SDK，根据实际需要，配置房间相关信息。
3. 加入第一个房间，成功登录后，可在该房间内推流、拉流、发送和接收实时消息。
4. 加入第二个房间，成功登录后，可在该房间内推流、拉流、发送和接收实时消息。
5. 离开第一个和第二个房间，针对离开房间不做时序上的限制。

具体功能的实现如下：

3.1 设置多房间模式

必须在初始化 SDK 之前，将房间模式 ZegoRoomMode 设置为多房间模式 “MultiRoom”。

// 设置房间模式为多房间模式
ZegoLiveRoom.setRoomMode(ZegoConstants.ZegoRoomMode.MultiRoom);

3.2 登录房间

3.2.1 设置房间配置信息

• 设置房间配置信息

调用 setRoomMode 接口设置允许观众创建房间以及用户状态更新回调，在房间创建之前设置有效，多房间模式下必须带上房间 ID。

boolean audienceCreateRoom = true;
boolean userStateUpdate = false;
api.setRoomConfig(audienceCreateRoom, userStateUpdate, "roomid");

• 设置房间最大在线人数

调用 setRoomMaxUserCount 接口设置房间最大在线人数，在房间创建之前设置有效，多房间模式下必须传入房间 ID。

api.setRoomMaxUserCount(100, "roomid");

• 设置 Token

调用 setToken 接口设置房间的鉴权 Token，Token 的生成规则请参考 用户权限控制。

在 Token 快要过期的前 30s，会收到 onTokenWillExpired 回调通知。重新生成 Token 后再调用 setToken 接口设置。

String token = "create token"; 
api.setToken(token, "roomid");

3.2.2 注册房间回调接口

在登录房间前，注册房间相关的接口。

// 创建 ZegoLiveRoom 的单例对象
ZegoLiveRoom api = new ZegoLiveRoom();
...
// 当前对象实现 IZegoRoomCallback 类
api.setZegoRoomCallback(this);

房间相关的所有回调接口都会带上房间 ID 参数，用于区分是哪个房间的回调。相关回调如下：

• onKickOut ：用户被踢出房间通知，会停止该用户在房间的推拉流。

// 参数 roomID 表示房间 ID
void onKickOut(int reason, String roomID, String customReason);

• onDisconnect ：客户端与 server 断开通知，会停止该房间的推拉流。

// 参数 roomID 表示房间 ID
void onDisconnect(int errorCode, String roomID);

• onTempBroken ：客户端与 server 的连接被动断开通知，不会停止该房间的推拉流。

// 参数 roomID 表示房间 ID
void onTempBroken(int errorCode, String roomID);

• onReconnect ：客户端与 server 重连成功通知，不会停止该房间的推拉流。

// 参数 roomID 表示房间 ID
void onReconnect(int errorCode, String roomID);

3.2.3 登录房间

传入房间 ID 等参数，调用 loginRoom 接口登录房间。

• 单房间模式下，同一时间只能登录一个房间，调用 loginRoom 接口时，如果之前已经登录其他房间，SDK 内部会自动退出之前的房间，然后登录新房间。
• 多房间模式下，同一时间可以登录多个房间，当超过最大房间个数后，会返回错误码“52005022”。

api.loginRoom("roomid", "room_title", 1, new IZegoLoginCompletionCallback(){

    @Override
    void onLoginCompletion(int errorCode, ZegoStreamInfo[] listStream){}
});

3.3 推流

传入房间 ID 等参数，调用 startPublishingWithParams 接口在指定房间内推流。

ZegoPublishStreamParams params;
params.streamID = "streamid";
params.streamTitle = "title";
params.extraInfo = "";
params.publishFlag = ZegoConstants.PublishFlag.JoinPublish;
params.publishParams = "";
params.channelIndex = ZegoConstants.PublishChannelIndex.MAIN;
params.roomID = "roomid";

api.startPublishingWithParams(params);

3.4 拉流

传入房间 ID 等参数，调用 startPlayingStreamWithParams 接口在指定房间内拉流。

ZegoPlayStreamParams params;
params.streamID = "streamid";
params.displayView = view; // display view
params.extraInfo = null; // extra info
params.roomID = "roomid";

api.startPlayingStreamWithParams(params);

3.5 发送、接收实时消息

• 广播消息

调用 sendRoomMessage 接口发送广播消息，房间其他用户通过 onRecvRoomMessage 回调接收消息，可通过房间 ID 来区分是哪个房间发送的。

// 发送房间消息
api.sendRoomMessage(MessageType.Text, MessageCategory.Chat, "message", "roomid", new IZegoRoomMessageCallback(){
    @Override
    void onSendRoomMessage(int errorCode, String roomID, long messageID){}
});

// 房间其他人收到消息，通过房间 ID 来区分是哪个房间发送的
// IZegoIMCallback
void onRecvRoomMessage(String roomID, ZegoRoomMessage[] listMsg);

• 弹幕消息

弹幕消息，主要用于大并发的场景，发送一些非必须到达的消息。

调用 sendBigRoomMessage 接口发送弹幕消息，房间其他用户通过 onRecvBigRoomMessage 回调接收消息，可通过房间 ID 来区分是哪个房间发送的。

// 发送
api.sendBigRoomMessage(MessageType.Text, MessageCategory.Chat, "message", "roomid", new IZegoBigRoomMessageCallback(){
    @Override
    void onSendBigRoomMessage(int errorCode, String roomID, String messageID){}
});

// 房间其他人收到消息，通过房间 ID 来区分是哪个房间发送的
// IZegoIMCallback
void onRecvBigRoomMessage(String roomID, ZegoBigRoomMessage[] listMsg);

• 自定义信令

自定义信令，指定房间里的用户（可以指定多个），发送特定的消息。

调用 sendCustomCommand 接口发送自定义信令，房间其他用户通过 onRecvCustomCommand 回调接收消息，可通过房间 ID 来区分是哪个房间发送的。

// 发送
ZegoUser[] listMember;
...
api.sendCustomCommand(listMember, "message", "roomid", new IZegoCustomCommandCallback(){
    @Override
    void onSendCustomCommand(int errorCode, String roomID){}
});

// 接收, IZegoRoomCallback
void onRecvCustomCommand(String userID, String userName, String content, String roomID);

• 房间附加信息

调用 setRoomExtraInfo 接口发送房间附加信息，房间其他用户通过 onRoomExtraInfoUpdated 回调接收消息，可通过房间 ID 来区分是哪个房间发送的。

// 发送，一个房间内只允许 1 个 key 
ZegoLiveRoomExtraInfo.getInstance().setRoomExtraInfo("key", "value", "roomid", new IZegoSetRoomExtraInfoCallback(){
    @Override
    void onSetRoomExtraInfo(int errorCode,String roomId, String key){}
}));

// 接收，通过 setRoomExtraInfoCallback(IZegoRoomExtraInfoCallback callback) 注册回调
void onRoomExtraInfoUpdated(String roomId, ZegoRoomExtraInfo[] extraInfoArray);

3.6 退出房间

传入房间 ID ，调用 logoutRoom 接口退出房间。

• 单房间模式下，退出房间，同时会停止所有的推拉流。
• 多房间模式下，退出房间必须传入房间 ID，只会退出指定房间，并停止该房间的推拉流。

api.logoutRoom("roomid");

4 API 参考列表

5 常见问题

1. 调用 setRoomMode 接口返回失败，是什么原因？

• 是否在初始化 SDK 之前调用 setRoomMode 接口。
• 是否特殊编包，带有 loginMultiRoom 接口是无法开启多房间模式的。
• 是否特殊编包，无房间模式是无法开启多房间模式的。
• 是否传入正确的参数。

2. 调用 loginRoom 登录失败，错误码为 “62001016”。是什么原因？

在没有开通多房间功能的情况下设置了多房间模式，登录房间会失败，返回错误码 62001016。

3. 调用 loginRoom 登录失败，错误码为 “52005022”。是什么原因？

同时登录的房间数超过最大房间个数后会返回错误码 52005022。目前默认最多同时加入 5 个房间，如有更多需求，请联系 ZEGO 技术支持提供扩展能力。