房间连接状态说明

用户在使用 ZEGO Express SDK 进行音视频通话或直播时，需要先加入房间才能收到来自同一房间内的其他用户的流新增/删除、用户进出等回调通知，所以用户在房间内的连接状态决定了用户是否能正常使用音视频业务。

本文主要介绍如何判断用户在房间内的连接状态，以及各个连接状态的转化过程。

监听房间连接状态

用户可通过 onRoomStateChanged 回调，实时监听自己在房间内的连接状态变化。当用户房间连接状态发生改变时，SDK 会触发该回调，并在回调中给出房间连接状态发生改变的原因（即房间连接状态）和相关错误码。

因网络质量不佳而导致的房间连接中断，SDK 内部会自动进行重试，详情请参考 房间断线重连 章节。

房间状态说明

房间连接状态会因多种情况互相转化，开发者可通过房间连接状态发生改变的原因 ZegoRoomStateChangedReason （即房间连接状态）结合 errorCode 做相应的业务逻辑处理。

开发者可参考以下代码处理常见业务事件：

// 以下代码是根据业务需求进行设置的变量，具体应用需根据开发者自定义安排，仅供参考。
public static boolean isFirstLogin = true;
// 需在 ZEGO 控制台中进行申请
long appID = 1234567890L;
// 需在 ZEGO 控制台中进行申请
String appSign = "xxxxxx";
// 开发者当前的 Application，若在 activity 中可调用 getApplication() 进行获取，也可根据实际业务需求自定义
Application application =  getApplication();
ZegoEngineProfile profile = new ZegoEngineProfile();
// 常见业务事件参考
public void init(){
    // 配置 engine 相关参数
    profile.appID = appID;
    profile.appSign = appSign;
    // 因需设置
    profile.scenario = ZegoScenario.GENERAL;
    profile.application = application;
    ZegoExpressEngine engine = ZegoExpressEngine.createEngine(profile,null);
    engine.setEventHandler(new IZegoEventHandler() {
        @Override
        public void onRoomStateChanged(String roomID, ZegoRoomStateChangedReason reason, int errorCode, JSONObject extendedData) {
            if(reason == ZegoRoomStateChangedReason.LOGINING)
            {
                // 登录中
                // 当调用 loginRoom 登录房间或 switchRoom 切换到目标房间时，进入该状态，表示正在请求连接服务器。
            }
            else if(reason == ZegoRoomStateChangedReason.LOGINED)
            {
                // 登录成功
                // 当前是开发者主动调用 loginRoom 登录成功，或调用 switchRoom 切换房间成功触发的回调。这里可以处理首次登录房间成功的业务逻辑，比如拉取聊天室、直播间基础信息。
            }
            else if(reason == ZegoRoomStateChangedReason.LOGIN_FAILED)
            {
                // 登录失败
                if (errorCode == 1002033) {
                    //当使用登录房间鉴权的功能时，传入的 token 错误或者过期
                }
            }
            else if(reason == ZegoRoomStateChangedReason.RECONNECTING)
            {
                // 重连中
                // 当前是 SDK 断线重连成功触发的回调，这里建议展示一些重连的 UI
            }
            else if(reason == ZegoRoomStateChangedReason.RECONNECTED)
            {
                // 重连成功
            }
            else if(reason == ZegoRoomStateChangedReason.RECONNECT_FAILED)
            {
                // 重连失败
                // 当房间连接彻底断开时，SDK 不会再进行重连，开发者如果需要再次登录房间，可以主动调用 loginRoom 接口
                // 此时可以在业务中退出房间/直播间/课堂，或者手动调用接口再次登录
            }
            else if(reason == ZegoRoomStateChangedReason.KICK_OUT)
            {
                // 被踢出房间
                if (errorCode == 1002050) {
                    // 用户被踢出房间（由于 userID 相同的用户在其他地方登录）
                }
                else if (errorCode == 1002055) {
                    // 用户被踢出房间（开发者主动调用后台的踢人接口
                }
            }
            else if(reason == ZegoRoomStateChangedReason.LOGOUT)
            {
                // 登出成功
                // 开发者主动调用 logoutRoom 登出房间
                // 或调用 switchRoom 切换房间，SDK 内部登出当前房间成功
                // 开发者可以在这里处理主动登出房间回调的逻辑
            }
            else if(reason == ZegoRoomStateChangedReason.LOGOUT_FAILED)
            {
               // 登出失败
               // 开发者主动调用 logoutRoom 登出房间失败
               // 或调用 switchRoom 切换房间，SDK 内部登出当前房间失败
               // 登出房间 ID 错误或者不存在
            }
        }
    });
}

房间断线重连

用户登录房间后，因网络信号问题/网络类型切换问题导致的与房间断连，SDK 内部会进行自动重连。用户与房间断连后重连有三种情况：

• 在 ZEGO 服务端判断用户 A 心跳超时前重连成功
• 在 ZEGO 服务端判断用户 A 心跳超时后重连成功
• 用户 A 重连失败

下图以用户 A 和用户 B 已登录同一个房间的情况下，用户 A 与房间断连后重连的情况为例：

情况一：在 ZEGO 服务端判断用户 A 心跳超时前重连成功

如果用户 A 短暂断线，但是在 90s 内重连成功了，那么用户 B 不会收到 onRoomUserUpdate 的回调通知。

• T0 = 0s：用户 A 的 SDK 收到客户端发起的 loginRoom 请求。
• T1 ≈ T0 + 120 ms：通常在调用 loginRoom 120 ms 后，客户端可以加入房间。加入房间过程中，用户 A 的客户端会收到 2 次 onRoomStateChanged 回调，分别通知客户端正在连接房间（Logining）以及连接房间成功（Logined）。
• T2 ≈ T1 + 100 ms：因网络传输延迟，用户 B 约在 100 ms 后收到 onRoomUserUpdate 回调以通知客户端用户 A 加入房间。
• T3：某个时间点，用户 A 因网络断开等原因导致上行网络变差。SDK 会尝试重新加入房间，同时客户端会收到 onRoomStateChanged 回调以通知客户端用户 A 正在断线重连。
• T5 = T3 + time（小于 90s）：用户 A 在重连时间内恢复网络，重连成功。会收到 onRoomStateChanged 回调以通知客户端用户 A 重连成功。

情况二：在 ZEGO 服务端判断用户 A 心跳超时后重连成功

• T0、T1、T2、T3 时刻的情况同 情况一：在 ZEGO 服务端判断用户 A 心跳超时前重连成功 中的 T0、T1、T2、T3。

• T4' ≈ T3 + 90s：用户 B 此时收到 onRoomUserUpdate 回调以通知用户 A 已断线。

• T5' = T3 + time（大于 90s，小于 20 min）：用户 A 在重连时间内恢复网络，重连成功。会收到 onRoomStateChanged 回调以通知客户端用户 A 重连成功。

• T6' ≈ T5' + 100 ms：因网络传输延迟，用户 B 约在 100 ms 后收到 onRoomUserUpdate 回调以通知客户端用户 A 加入房间。

情况三：用户 A 重连失败

• T0、T1、T2、T3 时刻的情况同 情况一：在 ZEGO 服务端判断用户 A 心跳超时前重连成功 中的 T0、T1、T2、T3。

• T4'' ≈ T3 + 90s：用户 B 此时收到 onRoomUserUpdate 回调以通知用户 A 已断线。

• T5'' = T3 + 20 min：如果用户 A 连续 20min 内无法重新加入房间，SDK 不再继续尝试重新连接。用户 A 将会收到 onRoomStateChanged 回调以通知客户端重连失败。

相关文档

Express SDK 是否支持断线重连机制？