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:
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
In the diagram:
-
T0: The Voice SDK receives a
joinChannel
request fromUID1
. -
T1: After 200 ms of calling
joinChannel
,UID1
joins the channel. At the same time,UID1
receivesonConnectionStateChanged(CONNECTING, CONNECTING)
callback. After successfully joining the channel,UID1
receivesonConnectionStateChanged(CONNECTED, JOIN_SUCCESS)
andonJoinChannelSuccess
callbacks. -
T2: Due to the transmission delay between networks,
UID2
observes a delay of about 100 milliseconds forUID1
to join the channel, and at this pointUID2
receives aonUserJoined
callback. -
T3: When
UID1
client's connection deteriorates due to a network issue or some other reason, the Voice SDK automatically tries to rejoin the channel. -
T4: If
UID1
does not receive any data from the server for 4 consecutive seconds,UID1
receives theonConnectionStateChanged(RECONNECTING, INTERRUPTED)
callback. Meanwhile, the Voice SDK continues to try to rejoin the channel. -
T5: If
UID1
does not receive any data from the server for 10 consecutive seconds after receivingonConnectionStateChanged(RECONNECTING, INTERRUPTED)
,UID1
receives theonConnectionLost
callback. Meanwhile, the Voice SDK continues to try to rejoin the channel. -
T6: If
UID2
does not receive any data fromUID1
for 20 consecutive seconds, the Voice SDK determines thatUID1
is offline. SoUID2
receives theonUserOffline
callback. -
T7: If
UID1
fails to rejoin the channel for 20 consecutive minutes after receivingonConnectionStateChanged(RECONNECTING, INTERRUPTED)
, the SDK stops retrying.UID1
receives theonConnectionStateChanged(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, Voice 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.
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 state | Description |
---|---|
Disconnected | Initial connection state. Usually occurs:
|
Connecting | The transient state after calling joinChannel . |
Connected | Occurs 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. |
Reconnecting | Occurs when the connection is interrupted. The SDK automatically tries to reconnect after an interruption.
|
Failed | Connection 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 state | Description and troubleshooting guide |
---|---|
Disconnected |
|
Connecting | CONNECTING (0): The app is trying to join the Agora channel. |
Connected | JOIN_SUCCESS (1): The app has successfully joined the channel. |
Reconnecting |
|
Failed |
|