Skip to main content
Android
iOS
macOS
Web
Windows
Electron
Flutter
React Native
React JS
Unity
Unreal Engine
Unreal (Blueprint)

Connection status management

In real-time audio and video scenarios, the connection state between the app and Agora SD-RTN™ changes as the client joins or leaves the channel. The connection may also be interrupted due to network or authentication issues.

This page describes the various channel connection states, reasons for state changes, and how to handle these changes to better manage your users and troubleshoot network faults.

Understand the tech

The following figure shows the various connection states and how the connection state changes between a user joining and leaving a channel:

Connection State

Disconnection and reconnection

During the communication process, if the user is disconnected due to network problems, the SDK automatically enables the disconnection and reconnection mechanism. The following figure shows the callbacks received by the local user UID1 and the remote user UID2 when:

  • A local user joins the channel
  • A network exception occurs
  • The connection is interrupted
  • The user rejoins the channel

Disconnection Connection

In the diagram:

  • T0: The Video SDK receives a joinChannel request from UID1.

  • T1: After 200 ms of calling joinChannel, UID1 joins the channel. At the same time, UID1 receives onConnectionStateChanged(CONNECTING, CONNECTING) callback. After successfully joining the channel, UID1 receives onConnectionStateChanged(CONNECTED, JOIN_SUCCESS) and onJoinChannelSuccess callbacks.

  • T2: Due to the transmission delay between networks, UID2 observes a delay of about 100 milliseconds for UID1 to join the channel, and at this point UID2 receives a onUserJoined callback.

  • T3: When UID1 client's connection deteriorates due to a network issue or some other reason, the Video SDK automatically tries to rejoin the channel.

  • T4: If UID1 does not receive any data from the server for 4 consecutive seconds, UID1 receives the onConnectionStateChanged(RECONNECTING, INTERRUPTED) callback. Meanwhile, the Video SDK continues to try to rejoin the channel.

  • T5: If UID1 does not receive any data from the server for 10 consecutive seconds after receiving onConnectionStateChanged(RECONNECTING, INTERRUPTED), UID1 receives the onConnectionLost callback. Meanwhile, the Video SDK continues to try to rejoin the channel.

  • T6: If UID2 does not receive any data from UID1 for 20 consecutive seconds, the Video SDK determines that UID1 is offline. So UID2 receives the onUserOffline callback.

  • T7: If UID1 fails to rejoin the channel for 20 consecutive minutes after receiving onConnectionStateChanged(RECONNECTING, INTERRUPTED), the SDK stops retrying. UID1 receives the onConnectionStateChanged(FAILED, JOIN_FAILED) callback and the user must exit and then rejoin the channel.

Prerequisites

Ensure that you have implemented the SDK quickstart project.

Implement connection status management

When the connection state changes, Video SDK sends an onConnectionStateChanged callback. This section shows you how to use the onConnectionStateChanged callback to monitor changes in the connection state.

Use the following code in your IRtcEngineEventHandler to log the connection state changes and the reason for the state change.


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

The state parameter in onConnectionStateChanged reports the current connection state. The reason parameter indicates why the connection state changed to help you troubleshoot your network. See State description and troubleshooting.

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

Connection states

The app may have the following connection states before joining, during a session, and after leaving a channel:

Connection stateDescription
DisconnectedInitial connection state. Usually occurs:
  • Before calling joinChannel.
  • After calling leaveChannel.
ConnectingThe transient state after calling joinChannel.
ConnectedOccurs after the app successfully joins a channel. The SDK also triggers the onJoinChannelSuccess callback to report that the local client has joined the channel. At this point, the user can publish or subscribe to the audio and video in the channel.
ReconnectingOccurs when the connection is interrupted. The SDK automatically tries to reconnect after an interruption.
  • If the client successfully rejoins the channel, the SDK triggers the onRejoinChannelSuccess callback.
  • If the channel is not rejoined within 10 seconds, the SDK triggers onConnectionStateChanged(Reconnecting, Lost), and continues trying to rejoin the channel.
FailedConnection failed. Occurs when the SDK is unable to join a channel for 20 minutes and stops attempting to reconnect to the channel. In this case, call leaveChannel to leave the current channel, and then call joinChannel to join the channel again.

State description and troubleshooting

The reason parameter in onConnectionStateChanged describes the reason for the connection state change.

The following table maps the relationships between different connection states and the causes of state change, as well as how to handle the situation when network outages occur:

Connection stateDescription and troubleshooting guide
Disconnected
  • LEAVE_CHANNEL (5): The user leaves the channel.
  • INVALID_TOKEN (8):The token is invalid. Please use a valid token to join the channel.
ConnectingCONNECTING (0): The app is trying to join the Agora channel.
ConnectedJOIN_SUCCESS (1): The app has successfully joined the channel.
Reconnecting
  • INTERRUPTED (2): When the network connection is interrupted, the SDK automatically reconnects to the channel and the connection state continues to change. For details on how the connection state changes during automatic reconnection, see Disconnection and reconnection.
  • LOST (16): The SDK lost connection with the server.
  • SETTING_PROXY_SERVER (11): The SDK attempts to reconnect because a proxy server is configured.
  • CLIENT_IP_ADDRESS_CHANGED (13): The client IP address has changed. If this status code occurs multiple times, prompt the user to rejoin the channel after changing networks.
  • KEEP_ALIVE_TIMEOUT (14): The keep-alive connection between the SDK and the server has timed out, causing the SDK to enter an automatic reconnection state.
  • RENEW_TOKEN (12): Updating the token has caused a change in the network connection status.
Failed
  • BANNED_BY_SERVER (3): The user is banned by the server.
  • JOIN_FAILED (4): The SDK stopped trying to reconnect after continued failed attempts to join the channel for 20 minutes. Call leaveChannel to leave the current channel and then call joinChannel to rejoin the channel.
  • INVALID_APP_ID (6): The app ID is invalid. Use a valid app ID to join the channel.
  • INVALID_CHANNEL_NAME (7): The channel name is invalid. Please check if the channel name contains illegal characters and use a valid channel name to join the channel.
  • TOKEN_EXPIRED (9): The token has expired. Obtain a new token from the app server, and then call joinChannel to rejoin the channel.
  • REJECTED_BY_SERVER (10): The user is banned by the server. May also occurs under the following circumstances:
    • The app calls joinChannel again after the local user has joined the channel.
    • The app called startEchoTest, but did not call stopEchoTest to end the echo test.

API reference

Interactive Live Streaming