Room Connection Status

When users use ZEGO Express SDK for audio and video calls or live streaming, they need to join a room first to receive callback notifications for stream additions/deletions and user entries/exits from other users in the same room. Therefore, the user's connection status in the room determines whether users can normally use audio and video services.

This document mainly introduces how to judge the user's connection status in the room, and the conversion process of each connection status.

Monitor Room Connection Status

Users can monitor their connection status changes in the room in real time through the onRoomStateChanged callback. When the user's room connection status changes, the SDK will trigger this callback and provide the reason for the room connection status change (i.e., room connection status) and relevant error codes in the callback.

For room connection interruptions caused by poor network quality, the SDK will automatically retry internally. For details, please refer to the Room Disconnection and Reconnection section.

Room Status Description

Room connection status will convert to each other due to various situations. Developers can make corresponding business logic processing based on the reason for the room connection status change ZegoRoomStateChangedReason (i.e., room connection status) combined with errorCode.

Developers can refer to the following code to handle common business events:

void onRoomStateChanged(const std::string &roomID, ZegoRoomStateChangedReason reason, int errorCode, const std::string &extendedData) {
    if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_LOGINING)
    {
        // Logging in
        // When calling loginRoom to log in to the room or switchRoom to switch to the target room, enter this status, indicating that a request is being made to connect to the server.
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_LOGINED)
    {
        /// Login successful
        // Currently triggered by the developer's active call to loginRoom for successful login, or calling switchRoom for successful room switching. Here you can handle the business logic of first successful login to the room, such as pulling chat room and live room basic information.
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_LOGIN_FAILED)
    {
        // Login failed
        if (errorCode == 1002033) {
            //When using the login room authentication function, the passed-in Token is incorrect or expired
        }
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_RECONNECTING)
    {
        // Reconnecting
        // Currently triggered by successful SDK disconnection and reconnection. Here it is recommended to display some reconnection UI
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_RECONNECTED)
    {
        // Reconnection successful
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_RECONNECT_FAILED)
    {
        // Reconnection failed
        // When the room connection is completely disconnected, the SDK will not retry reconnection anymore. If developers need to log in to the room again, they can actively call the loginRoom interface
        // At this time, you can exit the room/live room/classroom in the business, or manually call the interface to log in again
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_KICK_OUT)
    {
        // Kicked out of the room
        if (errorCode == 1002050) {
            // User is kicked out of the room (because a user with the same userID logs in elsewhere)
        }
        else if (errorCode == 1002055) {
            // User is kicked out of the room (developer actively calls the backend's kick out user interface)
        }
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_LOGOUT)
    {
        // Logout successful
        // Developer actively calls logoutRoom to log out of the room successfully
        // Or calls switchRoom to switch rooms, SDK internally logs out of the current room successfully
        // Developers can handle the logic of active logout room callback here
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_LOGOUT_FAILED)
    {
        // Logout failed
        // Developer actively calls logoutRoom to log out of the room failing
        // Or calls switchRoom to switch rooms, SDK internally logs out of the current room failing
        // The reason for the error may be incorrect logout room ID or does not exist
    }
}

void onRoomStateChanged(const std::string &roomID, ZegoRoomStateChangedReason reason, int errorCode, const std::string &extendedData) {
    if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_LOGINING)
    {
        // Logging in
        // When calling loginRoom to log in to the room or switchRoom to switch to the target room, enter this status, indicating that a request is being made to connect to the server.
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_LOGINED)
    {
        /// Login successful
        // Currently triggered by the developer's active call to loginRoom for successful login, or calling switchRoom for successful room switching. Here you can handle the business logic of first successful login to the room, such as pulling chat room and live room basic information.
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_LOGIN_FAILED)
    {
        // Login failed
        if (errorCode == 1002033) {
            //When using the login room authentication function, the passed-in Token is incorrect or expired
        }
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_RECONNECTING)
    {
        // Reconnecting
        // Currently triggered by successful SDK disconnection and reconnection. Here it is recommended to display some reconnection UI
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_RECONNECTED)
    {
        // Reconnection successful
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_RECONNECT_FAILED)
    {
        // Reconnection failed
        // When the room connection is completely disconnected, the SDK will not retry reconnection anymore. If developers need to log in to the room again, they can actively call the loginRoom interface
        // At this time, you can exit the room/live room/classroom in the business, or manually call the interface to log in again
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_KICK_OUT)
    {
        // Kicked out of the room
        if (errorCode == 1002050) {
            // User is kicked out of the room (because a user with the same userID logs in elsewhere)
        }
        else if (errorCode == 1002055) {
            // User is kicked out of the room (developer actively calls the backend's kick out user interface)
        }
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_LOGOUT)
    {
        // Logout successful
        // Developer actively calls logoutRoom to log out of the room successfully
        // Or calls switchRoom to switch rooms, SDK internally logs out of the current room successfully
        // Developers can handle the logic of active logout room callback here
    }
    else if(reason == ZEGO_ROOM_STATE_CHANGED_REASON_LOGOUT_FAILED)
    {
        // Logout failed
        // Developer actively calls logoutRoom to log out of the room failing
        // Or calls switchRoom to switch rooms, SDK internally logs out of the current room failing
        // The reason for the error may be incorrect logout room ID or does not exist
    }
}

Room Disconnection and Reconnection

After users log in to the room, disconnection from the room caused by network signal issues/network type switching issues will be automatically reconnected by the SDK internally. There are three situations for users reconnection after disconnection from the room:

• Successful reconnection before the ZEGO server determines that user A's heartbeat has timed out
• Successful reconnection after the ZEGO server determines that user A's heartbeat has timed out
• User A fails to reconnect

The following diagram takes the case where user A and user B have logged in to the same room, and user A reconnects after disconnection from the room as an example:

Case 1: Successful reconnection before the ZEGO server determines that user A's heartbeat has timed out

If user A briefly disconnects, but successfully reconnects within 90s, then user B will not receive the callback notification of onRoomUserUpdate.

• T0 = 0s: User A's SDK receives the loginRoom request initiated by the client.
• T1 ≈ T0 + 120 ms: Usually 120 ms after calling loginRoom, the client can join the room. During the room joining process, user A's client will receive 2 onRoomStateChanged callbacks, respectively notifying the client that it is connecting to the room (Logining) and that connecting to the room is successful (Logined).
• T2 ≈ T1 + 100 ms: Due to network transmission delay, user B receives the onRoomUserUpdate callback about 100 ms later to notify the client that user A has joined the room.
• T3: At a certain time point, user A's uplink network becomes worse due to network disconnection or other reasons. The SDK will try to rejoin the room, and the client will receive the onRoomStateChanged callback to notify the client that user A is disconnecting and reconnecting.
• T5 = T3 + time (less than 90s): User A restores the network within the reconnection time and reconnects successfully. Will receive the onRoomStateChanged callback to notify the client that user A has successfully reconnected.

Case 2: Successful reconnection after the ZEGO server determines that user A's heartbeat has timed out

• The situations at moments T0, T1, T2, T3 are the same as T0, T1, T2, T3 in Case 1: Successful reconnection before the server determines that user A's heartbeat has timed out.

• T4' ≈ T3 + 90s: User B receives the onRoomUserUpdate callback at this time to notify that user A has disconnected.

• T5' = T3 + time (greater than 90s, less than 20 min): User A restores the network within the reconnection time and reconnects successfully. Will receive the onRoomStateChanged callback to notify the client that user A has successfully reconnected.

• T6' ≈ T5' + 100ms: Due to network transmission delay, user B receives the onRoomUserUpdate callback about 100 ms later to notify the client that user A has joined the room.

Case 3: User A fails to reconnect

• The situations at moments T0, T1, T2, T3 are the same as T0, T1, T2, T3 in Case 1: Successful reconnection before the ZEGO server determines that user A's heartbeat has timed out.

• T4'' ≈ T3 + 90s: User B receives the onRoomUserUpdate callback at this time to notify that user A has disconnected.

• T5'' = T3 + 20 min: If user A cannot rejoin the room within 20 minutes, the SDK will no longer continue to try to reconnect. User A will receive the onRoomStateChanged callback to notify the client that reconnection has failed.

Related Documentation

Does Express SDK support disconnection and reconnection mechanism?