多房间

---

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 之前，将房间模式 ZegoAPIRoomMode 设置为多房间模式 “ ZEGOAPI_ROOM_MODE_MULTI_ROOM”。

// 设置房间模式为多房间模式
[ZegoLiveRoomApi setRoomMode:ZegoAPIRoomMode::ZEGOAPI_ROOM_MODE_MULTI_ROOM];

3.2 登录房间

3.2.1 设置房间配置信息

• 设置房间配置信息

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

bool audienceCreateRoom = true;
bool userStateUpdate = false;
[api setRoomConfig:audienceCreateRoom userStateUpdate:userStateUpdate room:@"roomID"];

• 设置房间最大在线人数

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

[api setRoomMaxUserCount:100 room:@"roomid"];

• 设置 Token

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

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

NSString *token = @"create token"; 
[api setToken:token room:@"roomid"];

3.2.2 注册房间回调接口

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

unsigned int  appID = 1;
NSData *appSign;
// 创建 ZegoLiveRoomApi 的单例对象
ZegoLiveRoomApi *api = [ZegoLiveRoomApi alloc] initWithAppID:appID appSignature:appSign;
// 当前对象实现 IRoomCallback 类
[api setRoomDelegate:self];

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

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

// 参数 roomID 表示房间 ID
- (void)onKickOut:(int)reason roomID:(NSString *)roomID customReason:(NSString *)customReason;

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

// 参数 roomID 表示房间 ID
- (void)onDisconnect:(int)errorCode roomID:(NSString *)roomID;

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

// 参数 roomID 表示房间 ID
- (void)onTempBroken:(int)errorCode roomID:(NSString *)roomID;

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

// 参数 roomID 表示房间 ID
- (void)onReconnect:(int)errorCode roomID:(NSString *)roomID;

3.2.3 登录房间

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

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

[api loginRoom:@"roomID" role:1 withCompletionBlock:^(int errorCode, NSArray<ZegoStream*> *streamList){}];

3.3 推流

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

ZegoAPIPublishStreamParams *params = [ZegoAPIPublishStreamParams new];
params.streamID = @"streamid";
params.streamTitle = @"title";
params.extraInfo = @"";
params.publishFlag = ZegoAPIPublishFlag::ZEGOAPI_JOIN_PUBLISH;
params.publishParams = @"";
params.channelIndex = ZegoAPIPublishChannelIndex::ZEGOAPI_CHN_MAIN;
params.roomID = @"roomid";

[api startPublishingWithParams:params];

3.4 拉流

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

ZegoAPIPlayStreamParams *params = [ZegoAPIPlayStreamParams new];
params.streamID = @"streamid";
params.displayView = view; // display view
params.extraInfo = nil; // extra info
params.roomID = @"roomid";

api startPlayingStreamWithParams:params];

3.5 发送、接收实时消息

• 广播消息

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

// 发送
[api sendRoomMessage:@"content" type:ZegoMessageType::ZEGO_TEXT category:ZegoMessageCategory::ZEGO_CHAT completion:^(int errorCode, NSString *roomId, unsigned long long messageId){}];

// 房间其他人收到消息，通过房间 ID 来区分是哪个房间发送的
- (void)onRecvRoomMessage:(NSString *)roomId messageList:(NSArray<ZegoRoomMessage*> *)messageList;

• 弹幕消息

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

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

// 发送
[api sendBigRoomMessage:@"content" type:ZegoMessageType::ZEGO_TEXT category:ZegoMessageCategory::ZEGO_CHAT completion:^(int errorCode, NSString *roomId, NSString *messageId){}];

// 房间其他人收到消息，通过房间 ID 来区分是哪个房间发送的
- (void)onRecvBigRoomMessage:(NSString *)roomId messageList:(NSArray<ZegoBigRoomMessage*> *)messageList;

• 自定义信令

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

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

// 发送
NSArray<ZegoUser*> *memberList = [NSMutableArray new];
...
[api sendCustomCommand:memberList content:@"content" room:@"roomid" completion:^)(int errorCode, NSString *roomID){}];

// 接收
- (void)onReceiveCustomCommand:(NSString *)fromUserID userName:(NSString *)fromUserName content:(NSString*)content roomID:(NSString *)roomID;

• 房间附加信息

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

// 发送，一个房间内只允许 1 个 key 
[api setRoomExtraInfo:@"key" value:@"value" room:@"roomid" completion:^(int errorCode, NSString *roomId,NSString *key){}];

// 接收，ZegoLiveRoomExtraInfoDelegate
- (void)onRoomExtraInfoUpdated:(NSString *)roomId roomExtraInfoList:(NSArray<ZegoRoomExtraInfo *> *)roomExtraInfoList;

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 技术支持提供扩展能力。