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.

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

• 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 (the logined 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?