- Documentation
- Video Call
- Develop your app
- Enhance basic feature
- Check the room connection status
Check the room connection status
Before a user uses ZEGOCLOUD Express SDK to make audio and video calls or perform live streaming, the user must join a room to receive callback notifications about events such as adding or removing streams by other users in the same room, and user login and logout events. Therefore, a connection state of a user in the room determines whether the user can normally use the audio and video services.
This topic describes how to determine a connection state of a user in a room. Further, this topic describes the transition process of connection states.
Listen for room connection states
A user can monitor the connection state of the user in the current room in real time by listening for the roomStateChanged
callback. If the connection state of the user changes, the SDK triggers the callback, and the current connection state and related error code are returned in the callback.
The SDK will retry internally if the connection to the room is interrupted due to poor network quality.
Room connection states
The room connection states flow. The developer can determine a state based on the returned reason and handle corresponding logic based on the return value of the errorCode
parameter.
State | Description | Common trigger event | |||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
ZegoRoomStateChangedReason.LOGINING |
A user is logging in to a room. This state is entered when a user calls the loginRoom operation to log in to a room or calls the switchRoom operation to switch to another room. This state indicates that a request is being initiated to connect to the server. On the application UI, the state of logging in to the room is displayed. |
The | |||||||||||||||||||||
ZegoRoomStateChangedReason.LOGINED | A user has successfully logged in to a room. This state is entered when a user has successfully logged in to a room or switched to another room. In this state, the user can receive callback notifications about other users and stream additions or deletions in the room. |
A user has successfully logged in to a room by calling the ZegoRoomStateChangedReason.LOGIN_FAILED |
A user fails to log in to a room. This state is entered when a user fails to log in to a room or fails to switch to another room due to a reason such as an invalid AppID , AppSign , or Token parameter.ZegoRoomStateChangedReason.RECONNECTING The room connection is temporarily interrupted. The SDK will retry internally if the interruption is caused by poor network quality. The room connection is temporarily interrupted due to poor network quality, and reconnection is triggered. In this case, the return value of the errorCode parameter is 1002051 .ZegoRoomStateChangedReason.RECONNECTED Room reconnection succeeds. The SDK will retry internally if the interruption is caused by poor network quality. If the reconnection succeeds, this state is entered. Reconnection succeeds after the room connection is temporarily interrupted due to poor network quality. In this case, the return value of the errorCode parameter is 0 .ZegoRoomStateChangedReason.RECONNECT_FAILED Room reconnection fails. The SDK will retry internally if the interruption is caused by poor network quality. If the reconnection fails, this state is entered. Reconnection fails after the room connection is temporarily interrupted due to poor network quality. In this case, the return value of the errorCode parameter is 1002053 .ZegoRoomStateChangedReason.KICK_OUT The server forces a user to log out of a room. For example, this state is entered when a user is forced to log out of a room because a user with the same name has already logged in to the room on another platform. ZegoRoomStateChangedReason.LOGOUT A user has successfully logged out of a room. This is the default state before a user logs in to a room. If the user has successfully logged out of a room by calling the logoutRoom or the SDK has successfully logged out of the current room internally when the switchRoom operation is called, this state is also entered.A user has successfully logged out of a room by calling the ZegoRoomStateChangedReason.LOGOUT_FAILED |
A user fails to log out of a room. This state is entered if a user fails to log out of a room by calling the logoutRoom operation, or if the SDK fails to log out of the current room when the switchRoom operation is called.The room ID does not exist when a user calls the logoutRoom operation to log out of a room in a multi-room scenario. |
You can refer to the following code to handle common business events:
// The unique identification of the project AppID, Number type, please get it from the ZEGOCLOUD console.
let appID = ;
// Access server address Server, String type, please obtain it from the ZEGOCLOUD console.
let server = "";
// Initialize instance
const zg = new ZegoExpressEngine(appID, server);
// Room status update callback
zg.on('roomStateChanged', (roomID, reason, errorCode, extendData) => {
if (reason == ZegoRoomStateChangedReason.Logining) {
// logging in
// Represents the callback in the connection triggered by the developer actively calling loginRoom
} else if (reason == ZegoRoomStateChangedReason.Logined) {
// login successful
//Only when the room status is successful login or reconnection, push streaming (startPublishingStream) and pull streaming (startPlayingStream) can normally receive and receive audio videos.
//Push your own audio and video streams to ZEGOCLOUD audio and video cloud
} else if (reason == ZegoRoomStateChangedReason.LoginFailed) {
// Login failed
} else if (reason == ZegoRoomStateChangedReason.Reconnecting) {
// Reconnecting
} else if (reason == ZegoRoomStateChangedReason.Reconnected) {
// Reconnection successful
} else if (reason == ZegoRoomStateChangedReason.ReconnectFailed) {
// Reconnect failed
} else if (reason == ZegoRoomStateChangedReason.Kickout) {
// kicked out of the room
} else if (reason == ZegoRoomStateChangedReason.Logout) {
// Logout successful
} else if (reason == ZegoRoomStateChangedReason.LogoutFailed) {
// Logout failed
}
});
Reconnect to a room after disconnection
After you log in to a room, you may be disconnected from the room due to a network signal issue or network-type switching issue. In this case, the SDK automatically initiates a reconnection. The following figure shows changes in the room connection state of a user A when the user A and a user B both have logged into the same room.
After a room disconnection occurs, the following three reconnection scenarios may be involved:
Scenario 1: Reconnection succeeds before the server determines that the heartbeat of the user A times out
If the user A is reconnected to the room within 90 seconds after the user A is temporarily disconnected from the room, the user B does not receive the roomUserUpdate callback notification.- T0 = 0 s. The SDK of the user A receives a loginRoom request sent by the client.
- T1 is about 120 ms later than T0. Usually, the client can join a room about 120 ms later after the loginRoom operation is called. In the process of logging in to the room, the client of the user A may receive the roomStateChanged callback notifications twice. The notifications are used to notify the client that the connection to the room is being established (the
logining
state) and that the connection to the room has been established (thelogined
state). - T2 is about 100 ms later than T1. Due to a network transmission delay, the user B receives the roomUserUpdate callback notification about 100 ms later than T1. The notification is used to notify the client that the user A joins the room.
- T3 specifies a point in time at which the uplink network status of the user A deteriorates due to network disconnection. Then, the SDK attempts to join the room again. At the same time, the client may receive a roomStateChanged callback notification used to notify the client that the user A is reconnecting to the room after disconnection.
- T5 specifies a point in time (less than 90 s) later than T3. At T5, the user A restores network connection and is reconnected to the room. The user A receives the roomStateChanged callback notification used to notify the client that the user A is reconnected to the room.
Scenario 2: Reconnection succeeds after the server determines that the heartbeat of the user A times out
The definitions of T0, T1, T2, and T3 in this scenario are the same as those in the scenario 1.
T4' is about 90 s later than T3. At T4', the user B receives the roomUserUpdate callback notification used to notify that the user A is disconnected.
T5' specifies a point in time (greater than 90 s but less than 20 min) later than T3. At T5', the user A restores network connection and is reconnected to the room. The user A receives the roomStateChanged callback notification used to notify the client that the user A is reconnected to the room.
T6' is about 100 ms later than T5'. Due to a network transmission delay, the user B receives the roomUserUpdate callback notification about 100 ms later than T5'. The notification is used to notify the client that the user A joins the room.
Scenario 3: The user A fails to reconnect to the room
The definitions of T0, T1, T2, and T3 in this scenario are the same as those in the scenario 1.
T4'' is about 90 s later than T3. At T4'', the user B receives the roomUserUpdate callback notification used to notify that the user A is disconnected.
T5'' is 5 minutes later than T3. If the user A fails to join the room within 5 minutes after T3, the SDK does not attempt to reconnect to the room. The user A receives the roomStateChanged callback notification used to notify the client that the reconnection fails.
Related documents
On the Web platform, does the Express SDK support the disconnection and reconnection mechanism?