登录多房间

---

功能简介

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

应用场景

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

• 跨房间连麦

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

• 超级小班

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

前提条件

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

• 已在 ZEGO 控制台 创建项目，并申请有效的 AppID 和 Server 地址，详情请参考 控制台 - 项目管理。
• 已在项目中集成 ZEGO Express SDK（2.9.0 版本及以上），并实现了基本的音视频推拉流功能，详情请参考 快速开始 - 集成 和 快速开始 - 实现流程。
• 已联系 ZEGO 技术支持开通多房间功能。

使用步骤

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

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

具体功能的实现如下：

1 初始化 SDK

请参考 快速开始 - 实现流程 的 “创建引擎” 进行 SDK 的初始化。

2 设置多房间模式

必须在初始化 SDK 之后，登录房间前调用，调用 enableMultiRoom 设置为true开启多房间

// 初始化 SDK
const zg = new ZegoExpressEngine(appID, server);
// 设置房间模式为多房间模式
zg.enableMultiRoom(true);
// 登录房间
zg.loginRoom()

3 登录多房间

通过 loginRoom 接口成功登录第一个房间后，再次调用 loginRoom 接口登录第二个房间。

// 先登录第一个房间
zg.loginRoom('first', token, {userID: 'zegoUser'});

// 后登录第二个房间
zg.loginRoom('second', token, {userID: 'zegoUser'});

登录第一个房间后，也可以通过 switchRoom 接口切换到另一个房间。

// 先登录第一个房间
zg.loginRoom('first', token, {userID: 'zegoUser'});

// 后登录第二个房间
zg.switchRoom('first', 'second', {token: token});

4 推流

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

const localStream = zg.createZegoStream();
zg.startPublishingStream(userID, localStream, { roomID: roomID });

5 拉流

拉流端根据流 ID 即可拉取到对应的流，多房间模式与普通单房间模式的拉流方式没有差别。

传入的流 ID，调用 startPlayingStream 接口即可进行拉流。

const remoteStream = await zg.startPlayingStream(streamID);

// remoteVideo 为本地<video>或<audio>对象
remoteVideo.srcObject = remoteStream;

6 发送、接收实时消息

• 广播消息

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

// 房间其他人收到消息，通过房间 ID 来区分是哪个房间发送的
zg.on(
    'IMRecvBroadcastMessage',
    (
        roomID: string,
        chatData: Array<{
            fromUser: ZegoUser;
            message: string;
            sendTime: number;
            messageID: number;
        }>,
    ) => {
        console.log('IMRecvBroadcastMessage', roomID, chatData);
    },
);

// 发送房间消息
zg.sendBroadcastMessage(
        roomID,
        JSON.stringify({
            text: 'rtc.sendBroadcastMessage test',
        }),
    );
});

• 弹幕消息

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

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

// 房间其他人收到消息，通过房间 ID 来区分是哪个房间发送的
zg.on(
    'IMRecvBarrageMessage',
    (
        roomID: string,
        chatData: Array<{
            fromUser: ZegoUser;
            message: string;
            sendTime: number;
            messageID: string;
        }>,
    ) => {
        console.log('IMRecvBarrageMessage', roomID, chatData);
    },
);

// 发送
zg.sendBarrageMessage(
    roomID,
    JSON.stringify({
        text: 'rtc.sendBarrageMessage test',
    }),
);

• 自定义信令

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

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

// 发送
zg.sendCustomCommand(
    roomID,
    // JSON.stringify(
    // @ts-ignore
    {
        text: 'rtc.sendCustomCommand test',
    },
    // )
    [],
);

// 接收自定义信令
zg.on('IMRecvCustomCommand', (roomID: string, fromUser: ZegoUser, command: string) => {
    console.log('IMRecvCustomCommand', roomID, fromUser, command);
});

• 房间附加信息

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

// 发送，一个房间内只允许 1 个 key
zg.setRoomExtraInfo(
    roomID,
    '2',
    JSON.stringify({
        text: 'rtc.setRoomExtraInfo test',
    }),
);

// 接收，通过 setRoomExtraInfoCallback
zg.on('roomExtraInfoUpdate', (roomID: string, data: any) =>{
    console.log('roomExtraInfoUpdate', roomID, data);
});

7 退出房间

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

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

zg.logoutRoom("roomid");

常见问题

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

• 是否在初始化 SDK 之后 登录房间前调用 enableMultiRoom 接口。
• 是否重复调用，一次完整的生命周期中仅允许该接口调用 1 次
• 是否传入正确的参数。

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

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

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

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