Channel Connection

Last updated 2022/05/13 07:37:05

During a real-time engagement session, the connection state between an app client and Agora SD-RTN™TM changes as the client joins and leaves an Agora channel, or goes offline due to network or authentication issues.

This page explains the connection states, how they change, and why they change, in order to help you better manage users and troubleshoot when network interruptions occur.

Understand the tech

Connection states

When the connection state changes, Agora sends the onConnectionStateChanged callback. The following diagram illustrates the various connection states and how the states change as a client app joins and leaves a channel:

Reconnection process

When the network connection is interrupted, the SDK automatically tries to reconnect to the server. The following diagram shows the callbacks received by the local user (UID1) and the remote user (UID2) when the local user joins the channel, gets a network exception, loses connection, and rejoins the channel.

As shown in the preceding diagram:

T0: The SDK receives the joinChannel request from UID 1.
T1: 200 ms after calling the joinChannel, UID 1 joins the channel. In the process, UID 1 also receives the onConnectionStateChanged(CONNECTING, CONNECTING) callback. When successfully joining the channel, UID 1 receives the onConnectionStateChanged(CONNECTED, JOIN_SUCCESS) and the onJoinChannelSuccess callbacks.
T2: Due to network latency, UID 2 detects UID 1 100 ms after UID 1 joins the channel. UID 2 receives the onUserJoined callback.
T3: The uplink network condition of UID 1 deteriorates. The SDK automatically tries rejoining the channel.
T4: If UID 1 fails to receive any data from the server in four seconds, UID 1 receives the onConnectionStateChanged(RECONNECTING, INTERRUPTED) callback; meanwhile the SDK continues to try rejoining the channel.
T5: If UID 1 fails to receive any data from the server in 10 seconds after receiving onConnectionStateChanged(RECONNCTING, INTERRUPTED), UID 1 receives the onConnectionLost callback; meanwhile the SDK continue to try rejoining the channel.
T6: If UID 2 fails to receive any data from UID 1 in 20 seconds, the SDK decides that UID 1 is offline. UID 2 receives the onUserOffline callback.
T7: If UID 1 fails to rejoin the channel in 20 minutes after receiving onConnectionStateChanged(RECONNCTING, INTERRUPTED), the SDK stops trying. UID 1 receives the onConnectionStateChanged(FAILED, JOIN_FAILED) callback. UID 1 needs to leave the channel and call the joinChannel method to join the channel.

Prerequisites

Before proceeding, ensure that you have implemented basic real-time functions in your project. See Start a Call.

Implement channel connection management

This section introduces how to use the onConnectionStateChanged callback to monitor the channel connection state change.

In your Agora project, open the file used to manage the IRtcEngineEventHandler file and add onConnectionStateChanged to the IRtcEngineEventHandler initialization process.

You can read the current connection state and why the state changes from the log.

To help you troubleshoot network interruptions, connectionChangedToState also has the reason parameter to explain why the connection state changes. For more information on these reasons and troubleshooting , refer to Reasons for the state change and how to troubleshoot.

Reference

This section provides reference information for managing the channel connection state.

Connection states

As shown in the preceding diagram, an app might have the following five connection states before and after the app joins and leaves the channel:

Connection states	Description
Disconnected	The initial connection state. It usually occurs under the following circumstances: Before calling `joinChannel`. After calling `leaveChannel`.
Connecting	This is the instantaneous state after calling the `joinChannel` method.
Connected	This state occurs after the app successfully joins the channel. The SDK also triggers the `onJoinChannelSuccess` callback to report that the local client has joined the channel. Users can now publish or subscribe to the audio and video in the channel.
Reconnecting	This state occurs when the connection is interrupted. The SDK automatically tries to reconnect after an interruption. If it successfully rejoins the channel, the SDK triggers the `onRejoinChannelSuccess` callback. If it does not join the channel in 10 seconds, the SDK triggers the `onConnectionStateChanged(Reconnecting, Lost)` while continuing to try to rejoin the channel.
Failed	The connection fails. This state occurs when the SDK cannot join the channel in 20 minutes and the SDK stops reconnecting to the channel. When this state occurs, call `leaveChannel` to leave the current channel, and call `joinChannel` to join the channel again.

Connection state change reasons

To help you troubleshoot network interruptions, onConnectionStateChanged also has the reason parameter that explains why the connection state changes.

The following table lists the mapping relationship between the connection state, reasons for the state change, and how to troubleshoot when an network interruption occurs.

Connection states	Reasons for the state change and how to troubleshoot
Disconnected	`LEAVE_CHANNEL`(5): The user leaves the channel. `INVALID_TOKEN`(8): Use a valid token to join the channel.
Connecting	`CONNECTING`(0): The app is attempting to join an Agora channel.
Connected	`JOIN_SUCCESS`(1): The app successfully joins the channel.
Reconnecting	`INTERRUPTED`(2): When the network connection is interrupted, the SDK automatically reconnects to the channel, and the connection state keeps changing. For how the automatic reconnection affects the connection state, see Reconnection. `LOST`(16): Wait until the SDK successfully reconnects to the server. `SETTING_PROXY_SERVER`(11): Wait until the SDK successfully reconnects to the server. `CLIENT_IP_ADDRESS_CHANGED`(13): Wait until the SDK successfully reconnects to the server. `KEEP_ALIVE_TIMEOUT`(14): Wait until the SDK successfully reconnects to the server. `RENEW_TOKEN`(12): The token is renewed, and the app is attempting to rejoin the channel.
Failed	`INVALID_APP_ID`(6): Use a valid app ID to join the channel. `INVALID_CHANNEL_NAME`(7): Use a valid channel name to join the channel. `TOKEN_EXPIRED`(9): Get a new token from your app server, and call `joinChannel` to join the channel. `BANNED_BY_SERVER`(3): The user is banned by the server. `JOIN_FAILED`(4): The SDK fails to join the channel for more than 20 minutes and stops reconnecting to the channel. Call `leaveChannel` to leave the current channel, and call `joinChannel` to rejoin the channel. `REJECTED_BY_SERVER`(10): This reason occurs in the following situations: The app calls `joinChannel` after the local user has already joined the channel. When the app calls `startEchoTest` but does not call `stopEchoTest` to stop the echo test.

API reference

Is this page helpful?

Yes