需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

频道连接状态管理

  • Android

更新时间不可用

了解实时互动 RTC 在不同平台上的频道连接状态管理方式，包括接入流程、关键配置和平台差异。

在实时音视频场景下，App 端与声网 SD-RTN™ 之间的连接状态会随着客户端加入或离开频道而发生变化，也可能由于网络或鉴权问题而导致连接中断。

本文介绍各种频道连接状态，状态改变原因和处理方式，帮助你更好地管理用户和排除网络故障。

技术原理

连接状态

当连接状态发生变化时，声网会发送 onConnectionStateChanged 回调。下图展示各种连接状态，以及用户从加入到离开频道的过程中连接状态如何改变：

断线重连

通信过程中，如果因网络问题导致连接断开，SDK 会自动开启断线重连机制。下图展示本地用户 (UID1) 和远程用户 (UID2) 在以下过程中收到的回调：本地用户加入频道、发生网络异常、连接中断、重新加入频道。

图解如下：

  • T0：SDK 接收到 UID1 的 joinChannel 请求。
  • T1：调用 joinChannel 200 ms 后，UID1 加入频道。同时，UID1 收到 onConnectionStateChanged(CONNECTING, CONNECTING) 回调。 成功加入频道后，UID1 收到 onConnectionStateChanged(CONNECTED, JOIN_SUCCESS) 和 onJoinChannelSuccess 回调。
  • T2：因网间传输延迟，UID 2 感知 UID 1 加入频道约有 100 毫秒的延迟，此时 UID 2 收到 onUserJoined 回调。
  • T3：某个时间点 UID 1 客户端因断网等原因导致上行网络变差。SDK 自动尝试重新加入频道。
  • T4：如果 UID1 连续 4 秒没有收到服务器发送的任何数据，UID1 收到 onConnectionStateChanged(RECONNECTING, INTERRUPTED) 回调；同时 SDK 继续尝试重新加入频道。
  • T5：如果 UID 1 收到 onConnectionStateChanged(RECONNECTING, INTERRUPTED) 后连续 10 秒没有收到服务器发送的任何数据，UID 1 会收到 onConnectionLost 回调；同时 SDK 继续尝试重新加入频道。
  • T6：如果 UID2 连续 20 秒没有收到来自 UID1 的任何数据，则 SDK 判断 UID1 离线。UID2 收到 onUserOffline 回调。
  • T7：如果 UID 1 收到 onConnectionStateChanged(RECONNECTING, INTERRUPTED) 后连续 20 分钟无法重新加入频道，SDK 不再继续尝试。UID 1 收到 onConnectionStateChanged(FAILED, JOIN_FAILED) 回调；用户需要退出当前频道，然后重新加入频道。

前提条件

在进行操作之前，请确保你已经在项目中实现了基本的实时音视频功能。详见实现音视频互动。

操作步骤

本节介绍如何使用 onConnectionStateChanged 回调来监控频道连接状态的变化。

在你的项目中，打开管理 IRtcEngineEventHandler 的文件，将以下代码复制到 IRtcEngineEventHandler 初始化过程中。

Java
public void onConnectionStateChanged(int state, int reason) {
    super.onConnectionStateChanged(state, reason);
    Log.i(TAG, "onConnectoionStateChanged->" + ", state->" + state + ", reason->" + reason);
}

你可以从日志中读取当前连接状态，以及状态更改的触发原因。

另外，onConnectionStateChanged 中的 reason 参数也解释了连接状态改变的原因，可帮助你进行网络故障排除。 有关频道连接状态变化的原因以及排障方式，详见状态说明及排障指导。

参考信息

连接状态

如前文图中所示，App 在加入和离开频道前后可能出现以下 5 种连接状态：

连接状态描述
Disconnected

初始连接状态。它通常发生在：

  • 调用 joinChannel 之前。
  • 调用 leaveChannel 之后。
Connecting调用 joinChannel 方法后的瞬时状态。
Connected发生在 App 成功加入频道后。SDK 还会触发 onJoinChannelSuccess 回调，上报本地客户端已经加入频道。 此时用户可以发布或订阅频道中的音频和视频。
Reconnecting

发生在连接中断时。SDK 会在中断后自动尝试重新连接。

  • 如果重新加入频道成功，SDK 会触发 onRejoinChannelSuccess 回调。
  • 如果 10 秒内没有加入频道，SDK 会触发 onConnectionStateChanged(Reconnecting, Lost)，同时继续尝试重新加入频道。
Failed连接失败。发生在 SDK 在 20 分钟内无法加入频道、并且 SDK 停止重新连接频道时。 此时需调用 leaveChannel 离开当前频道，再调用 joinChannel 再次加入频道。
表格内容超出当前宽度，可横向滚动查看更多列。

状态说明及排障指导

onConnectionStateChanged 中的 reason 参数描述了连接状态更改原因。

下表列出了不同连接状态和状态变化原因之间的映射关系，以及发生网络中断时故障时的处理方法。

连接状态状态说明和排障指导
Disconnected
  • LEAVE_CHANNEL(5)：用户离开频道。
  • INVALID_TOKEN(8)：Token 无效，请使用有效的 Token 加入频道。
Connecting
  • CONNECTING(0): App 正在尝试加入声网频道。
Connected
  • JOIN_SUCCESS(1)：App 已成功加入频道。
Reconnecting
  • INTERRUPTED(2)：当网络连接中断时，SDK 自动重新连接频道，连接状态持续变化。 关于自动重连时连接状态如何改变， 详见断线重连。
  • LOST(16)：SDK 和服务器失去连接。
  • SETTING_PROXY_SERVER(11)：由于设置了代理服务器，SDK 尝试重连。
  • CLIENT_IP_ADDRESS_CHANGED(13)：客户端 IP 地址变更。如多次收到该状态码，请提示用户更换网络后尝试重新加入频道。
  • KEEP_ALIVE_TIMEOUT(14)：SDK 和服务器连接保活超时，进入自动重连状态。
  • RENEW_TOKEN(12)：更新 Token 引起网络连接状态改变。
Failed

  • BANNED_BY_SERVER(3)：用户被服务器禁止。

  • JOIN_FAILED(4)：SDK 在 20 分钟内持续尝试加入频道失败，停止尝试重连。你需要调用 leaveChannel 离开当前频道，然后调用 joinChannel 重新加入频道。

  • INVALID_APP_ID(6)：App ID 无效，使用有效的 App ID 加入频道。

  • INVALID_CHANNEL_NAME(7)：频道名无效，请检查频道名中是否包含非法字符，并使用有效的频道名加入频道。

  • INVALID_TOKEN(8)：Token 无效，请使用有效的 Token 加入频道。

  • TOKEN_EXPIRED(9)：Token 已过期。请从 App 服务器获取新的 Token，然后调用 joinChannel 重新加入频道。

  • REJECTED_BY_SERVER(10)：此用户被服务器禁止。一般有以下原因：

    • 本地用户已加入频道后，App 再次调用加入频道的 API，如 joinChannel。
    • App 调用了 startEchoTest，但没有调用 stopEchoTest 结束回声测试。
表格内容超出当前宽度，可横向滚动查看更多列。

API 参考

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利