Multi-room Login
Function Overview
The same user can join multiple rooms simultaneously, and publish streams, play streams, send real-time messages, and receive message callbacks in multiple rooms at the same time.
- This feature is not enabled by default. To use it, please contact ZEGOCLOUD Technical Support to enable the relevant permissions.
- After this feature is enabled, it supports joining up to 5 rooms simultaneously by default. If you have more requirements, please contact ZEGOCLOUD Technical Support for assistance.
Application Scenarios
This feature can isolate messages and callbacks from multiple rooms, enabling more flexible co-hosting services. ZEGO recommends using it for cross-room co-hosting and online education super small class scenarios.
- Cross-room co-hosting
Host A and Host B perform cross-room co-hosting. Host A can notify all viewers in Room A to login to Host B's room for stream playing, and Host B can similarly notify all viewers in Room B to login to Host A's room for stream playing.
- Super small class
The teacher enters the large class room to publish streams, and all students login to the large class room to play streams, while also logging into group rooms to discuss and co-host with students in the same group. The teaching assistant logs into group rooms to maintain classroom order or answer student questions.
Prerequisites
Before implementing multi-room functionality, please ensure:
- You have created a project in the ZEGOCLOUD Console and applied for a valid AppID and Server address. For details, please refer to Console - Project Management.
- You have integrated the ZEGO Express SDK (version 2.9.0 or above) in your project and implemented basic audio and video publish and play functionality. For details, please refer to Quick Start - Integration and Quick Start - Implementation.
- You have contacted ZEGOCLOUD Technical Support to enable the multi-room feature.
Usage Steps
Taking the example of the same user joining two rooms, the overall implementation process is as follows:
- Initialize the SDK, then set the room mode to multi-room.
- Join the first room. After successful login, you can publish streams, play streams, send and receive real-time messages in that room.
- Join the second room. After successful login, you can publish streams, play streams, send and receive real-time messages in that room.
- Leave the first and second rooms. There is no timing restriction for leaving rooms.
The implementation of specific functions is as follows:
1 Initialize SDK
Please refer to Quick Start - Implementation section "Create engine" to initialize the SDK.
2 Set Multi-room Mode
Must be called after SDK initialization and before login room. Call enableMultiRoom and set to true to enable multi-room
// Initialize SDK
const zg = new ZegoExpressEngine(appID, server);
// Set room mode to multi-room mode
zg.enableMultiRoom(true);
// Login room
zg.loginRoom()If you set multi-room mode without enabling the multi-room feature, login room will fail with an error code "1100001016".
3 Login to Multiple Rooms
After successfully logging in to the first room through the loginRoom interface, call the loginRoom interface again to log in to the second room.
// Login to the first room first
zg.loginRoom('first', token, {userID: 'zegoUser'});
// Login to the second room later
zg.loginRoom('second', token, {userID: 'zegoUser'});After logging in to the first room, you can also switch to another room through the switchRoom interface.
// Login to the first room first
zg.loginRoom('first', token, {userID: 'zegoUser'});
// Login to the second room later
zg.switchRoom('first', 'second', {token: token});4 Publish Stream
Pass in parameters such as Room ID and call the startPublishingStream interface to publish stream in the specified room.
const localStream = zg.createZegoStream();
zg.startPublishingStream(userID, localStream, { roomID: roomID });5 Play Stream
The playing end can play the corresponding stream based on the Stream ID. There is no difference in the stream playing method between multi-room mode and normal single-room mode.
Pass in the Stream ID and call the startPlayingStream interface to play the stream.
const remoteStream = await zg.startPlayingStream(streamID);
// remoteVideo is a local <video> or <audio> object
remoteVideo.srcObject = remoteStream;6 Send and Receive Real-time Messages
- Broadcast message
Call the sendBroadcastMessage interface to send broadcast messages. Other users in the room receive messages through the IMRecvBroadcastMessage callback, and can distinguish which room sent the message by Room ID.
// Others in the room receive the message, distinguish which room sent it by room ID
zg.on(
'IMRecvBroadcastMessage',
(
roomID: string,
chatData: Array<{
fromUser: ZegoUser;
message: string;
sendTime: number;
messageID: number;
}>,
) => {
console.log('IMRecvBroadcastMessage', roomID, chatData);
},
);
// Send room message
zg.sendBroadcastMessage(
roomID,
JSON.stringify({
text: 'rtc.sendBroadcastMessage test',
}),
);
});- Barrage message
Barrage messages are mainly used for high-concurrency scenarios to send some non-essential messages.
Call the sendBarrageMessage interface to send barrage messages. Other users in the room receive messages through the IMRecvBarrageMessage callback, and can distinguish which room sent the message by Room ID.
// Others in the room receive the message, distinguish which room sent it by room ID
zg.on(
'IMRecvBarrageMessage',
(
roomID: string,
chatData: Array<{
fromUser: ZegoUser;
message: string;
sendTime: number;
messageID: string;
}>,
) => {
console.log('IMRecvBarrageMessage', roomID, chatData);
},
);
// Send
zg.sendBarrageMessage(
roomID,
JSON.stringify({
text: 'rtc.sendBarrageMessage test',
}),
);- Custom signaling
Custom signaling allows you to send specific messages to specified users in a room (can specify multiple users).
Call the sendCustomCommand interface to send custom signaling. Other users in the room receive messages through the IMRecvCustomCommand callback, and can distinguish which room sent the message by Room ID.
// Send
zg.sendCustomCommand(
roomID,
// JSON.stringify(
// @ts-ignore
{
text: 'rtc.sendCustomCommand test',
},
// )
[],
);
// Receive custom signaling
zg.on('IMRecvCustomCommand', (roomID: string, fromUser: ZegoUser, command: string) => {
console.log('IMRecvCustomCommand', roomID, fromUser, command);
});- Room extra info
Call the setRoomExtraInfo interface to send room extra info. Other users in the room receive messages through the roomExtraInfoUpdate callback, and can distinguish which room sent the message by Room ID.
// Send, only 1 key is allowed in a room
zg.setRoomExtraInfo(
roomID,
'2',
JSON.stringify({
text: 'rtc.setRoomExtraInfo test',
}),
);
// Receive, through setRoomExtraInfoCallback
zg.on('roomExtraInfoUpdate', (roomID: string, data: any) =>{
console.log('roomExtraInfoUpdate', roomID, data);
});For size and frequency limitations of sending real-time messages, please refer to Restrictions.
7 Logout Room
Pass in the Room ID and call the logoutRoom interface to leave the room.
- In single-room mode, leaving the room will stop all publishing and playing streams.
- In multi-room mode, if only the Room ID is passed in, only the specified room will be left, and the publishing and playing streams of that room will be stopped. If no parameters are passed, all rooms will be left and all publishing and playing streams will be stopped.
zg.logoutRoom("roomid");FAQ
- Whether the enableMultiRoom interface is called after initializing the SDK and before login room.
- Whether it is called repeatedly. This interface is only allowed to be called once in a complete lifecycle.
- Whether the correct parameters are passed.
If you set multi-room mode without enabling the multi-room feature, login room will fail with error code 1100001016.
When the number of rooms logged in at the same time exceeds the maximum number of rooms, error code 1000005022 will be returned. Currently, the default is to join up to 5 rooms at the same time. For more requirements, please contact ZEGOCLOUD Technical Support for extended capabilities.