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, user entries/exits, etc. from other users in the same room. Therefore, the user's connection status in the room determines whether the user can normally use audio and video services.

This article mainly introduces how to determine the user's connection status in the room, as well as the transition process of each connection status.

Monitor room connection status

Users can monitor changes in their connection status 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 related 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 transform into each other due to various situations. Developers can perform corresponding business logic processing based on the reason ZegoRoomStateChangedReason for the room connection status change (i.e., room connection status) combined with errorCode.

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

-(void)onRoomStateChanged:(ZegoRoomStateChangedReason)reason errorCode:(int)errorCode extendedData:(NSDictionary *)extendedData roomID:(NSString *)roomID {
    if(reason == ZegoRoomStateChangedReasonLogining)
    {
        // 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 to connect to the server is in progress.
    }
    else if(reason == ZegoRoomStateChangedReasonLogined)
    {
        // Login successful
        // Currently triggered by the developer actively calling loginRoom successfully or calling switchRoom successfully to switch rooms. Here you can handle business logic for successful first login to the room, such as pulling basic information for chat rooms and live rooms.
    }
    else if(reason == ZegoRoomStateChangedReasonLoginFailed)
    {
        // Login failed
        if (errorCode == 1002033) {
            //When using the login room authentication feature, the passed-in Token is incorrect or expired
        }
    }
    else if(reason == ZegoRoomStateChangedReasonReconnecting)
    {
        // Reconnecting
        // Currently triggered by the SDK's successful disconnection and reconnection. Here it is recommended to display some reconnection UI
    }
    else if(reason == ZegoRoomStateChangedReasonReconnected)
    {
        // Reconnection successful
    }
    else if(reason == ZegoRoomStateChangedReasonReconnectFailed)
    {
        // Reconnection failed
        // When the room connection is completely disconnected, the SDK will not retry 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 == ZegoRoomStateChangedReasonKickOut)
    {
        // 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 user interface)
        }
    }
    else if(reason == ZegoRoomStateChangedReasonLogout)
    {
        // Logout successful
        // Developer actively calls logoutRoom to successfully log out of the room
        // Or calls switchRoom to switch rooms, and the SDK successfully logs out of the current room internally
        // Developers can handle the logic of active logout room callback here
    }
    else if(reason == ZegoRoomStateChangedReasonLogoutFailed)
    {
        // Logout failed
        // Developer actively calls logoutRoom to fail to log out of the room
        // Or calls switchRoom to switch rooms, and the SDK fails to log out of the current room internally
        // The reason for the error may be that the logout room ID is incorrect or does not exist
    }
}

-(void)onRoomStateChanged:(ZegoRoomStateChangedReason)reason errorCode:(int)errorCode extendedData:(NSDictionary *)extendedData roomID:(NSString *)roomID {
    if(reason == ZegoRoomStateChangedReasonLogining)
    {
        // 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 to connect to the server is in progress.
    }
    else if(reason == ZegoRoomStateChangedReasonLogined)
    {
        // Login successful
        // Currently triggered by the developer actively calling loginRoom successfully or calling switchRoom successfully to switch rooms. Here you can handle business logic for successful first login to the room, such as pulling basic information for chat rooms and live rooms.
    }
    else if(reason == ZegoRoomStateChangedReasonLoginFailed)
    {
        // Login failed
        if (errorCode == 1002033) {
            //When using the login room authentication feature, the passed-in Token is incorrect or expired
        }
    }
    else if(reason == ZegoRoomStateChangedReasonReconnecting)
    {
        // Reconnecting
        // Currently triggered by the SDK's successful disconnection and reconnection. Here it is recommended to display some reconnection UI
    }
    else if(reason == ZegoRoomStateChangedReasonReconnected)
    {
        // Reconnection successful
    }
    else if(reason == ZegoRoomStateChangedReasonReconnectFailed)
    {
        // Reconnection failed
        // When the room connection is completely disconnected, the SDK will not retry 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 == ZegoRoomStateChangedReasonKickOut)
    {
        // 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 user interface)
        }
    }
    else if(reason == ZegoRoomStateChangedReasonLogout)
    {
        // Logout successful
        // Developer actively calls logoutRoom to successfully log out of the room
        // Or calls switchRoom to switch rooms, and the SDK successfully logs out of the current room internally
        // Developers can handle the logic of active logout room callback here
    }
    else if(reason == ZegoRoomStateChangedReasonLogoutFailed)
    {
        // Logout failed
        // Developer actively calls logoutRoom to fail to log out of the room
        // Or calls switchRoom to switch rooms, and the SDK fails to log out of the current room internally
        // The reason for the error may be that the logout room ID is incorrect or does not exist
    }
}

Room disconnection and reconnection

After users log in to the room, if they disconnect from the room due to network signal problems/network type switching problems, the SDK will automatically reconnect internally. There are three situations for users to reconnect after disconnecting from the room:

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

The following diagram takes the situation where user A and user B have logged in to the same room, and user A disconnects from the room and then reconnects:

Situation 1: Successfully reconnect 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 onRoomUserUpdate callback notification.

• 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, notifying the client that it is connecting to the room (Logining) and that the connection to the room is successful (Logined) respectively.
• 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 poor due to network disconnection or other reasons. The SDK will try to rejoin the room. At the same time, the client will receive the onRoomStateChanged callback to notify the client that user A is reconnecting due to disconnection.
• 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 reconnected successfully.

Situation 2: Successfully reconnect after the ZEGO server determines that user A's heartbeat has timed out

• The situations at T0, T1, T2, T3 are the same as T0, T1, T2, T3 in Situation 1: Successfully reconnect 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 + 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 reconnected successfully.

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

Situation 3: User A fails to reconnect

• The situations at T0, T1, T2, T3 are the same as T0, T1, T2, T3 in Situation 1: Successfully reconnect 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 consecutive minutes, the SDK will no longer continue trying 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?