文档中心

实时音视频

请输入

开发指南

网络连接状态与断网提醒

在网络波动的环境下（如 WiFi 切换、信号弱、路由器故障等），通话可能出现卡顿、黑屏甚至中断。你可以通过 SDK 回调实时监测网络状态，以便在 UI 上给出明确提示（例如 “正在重连...”、“对方已断开” 等），提升弱网下的用户体验。

弱网提示（预警）

当网络变差但尚未断开时，用户可能感受到音视频卡顿。你可以监听 onNetworkQuality 回调，获取本端和每个远端用户的网络评分，提前预警。详见弱网提示。

本端断网提示

本端断网分为两种情况：设备本地网络断开或与 RTC 服务器连接中断。

设备网络断开

例如：WiFi 关闭、蜂窝数据关闭、路由器断电等。

平台	监听方式
Native	监听 onNetworkTypeChanged：当设备网络类型变化（如从 WiFi 切到无网络）时触发。由于平台限制，在 Windows 端及部分 Android 机型，本地网络断开后无法立即收到该事件提示。建议结合 ping 检测作为补充判断。
Web	监听 onNetworkQuality 的 DOWN 状态。

设备与服务器连接中断

即使设备有网，也可能因链路问题无法连接服务器（如防火墙、运营商限制、服务端故障）。你可监听 onConnectionStateChanged 回调获取本端连接状态。

关键状态说明：

状态	触发条件	UI 建议
CONNECTION_STATE_DISCONNECTED	客户端 12 秒内未收到服务器响应	“连接中断，正在重连...”
CONNECTION_STATE_RECONNECTING	SDK 启动自动重连流程（无需手动触发）	（持续显示重连提示）
CONNECTION_STATE_LOST	从进入 DISCONNECTED状态起，10 秒内重连未成功	“网络环境较差，尝试切换网络”

远端断网提示

当房间中的其他用户（远端）因网络中断、App 闪退或主动退出而失去连接时，你可以通过以下回调获取准确判断对方状态并更新 UI。

关键状态说明：

时间点	触发回调	事件含义	UI 建议
T0 + 15s	*	ICE 连接断开：服务端连续 15s 未收到该用户数据包。	“对方网络不佳”
T0 + 18s	onUserPublishStreamVideo(false) onUserPublishStreamAudio(false)	媒体流中断：判定 ICE 断开 3s 后仍未恢复。	维持流中断提示
T0 + 30s	onUserLeave(uid)	正式下线：判定 ICE 断开 15s 后仍未恢复连接。	从成员列表移除

回调参考

平台	回调
Android	onConnectionStateChanged onNetworkTypeChanged
iOS	rtcEngine:onConnectionStateChanged: rtcEngine:onNetworkTypeChanged:
macOS	rtcEngine:onNetworkTypeChanged: rtcEngine:onConnectionStateChanged:
Windows	onConnectionStateChanged onNetworkTypeChanged
Web	onConnectionStateChanged 在 Web SDK V4.45 及之后的版本，本端与服务器断连会触发 CONNECTION_STATE_LOST 状态 onNetworkQuality 在 Web SDK V4.55 及之后的版本，本端网络断开会触发 DOWN 状态。

最近更新时间：2026.07.27 14:26:54

这个页面对您有帮助吗？

有用

无用