网络连接状态与断网提醒--实时音视频-火山引擎

文档中心

实时音视频

请输入

开发指南

网络连接状态与断网提醒

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

弱网提示（预警）

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

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

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

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

平台

监听方式

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.01.26 16:27:50

这个页面对您有帮助吗？

有用

无用