Channel Connection

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, to help you better manage users and troubleshoot when network interruption occurs.

Understand the tech

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

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, lises connection, and rejoins the channal.

In the above diagram:

• T0: The SDK receives the joinChannel request from UID 1.
• T1: 200 ms after calling joinChannel, UID 1 joins the channel. In the process, UID 1 also receives the connectionChangedToState(Connecting, Connecting) callback. When successfully joining the channel, UID 1 receives the connectionChangedToState(Connected, JoinSuccess) and didJoinSuccess callbacks.
• T2: Due to network latency, UID 2 detects UID 1 100 ms after UID 1 joins the channel. UID 2 receives the didJoinedOfUid 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 connectionChangedToState(Reconnecting, Interrupted); 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 connectionChangedToState(Reconnecting, Interrupted), UID 1 receives the rtcEngineConnectionDidLost 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 didOfflineOfUid.
• T7: If UID 1 fails to rejoin the channel in 20 minutes after receiving connectionChangedToState(Reconnecting, Interrupted), the SDK stops trying. UID 1 receives the connectionChangedToState(Failed, JoinFailed) callback. UID 1 needs to leave the channel and call the joinChannel method to join the channel.

Prerequisites

Before proceeding, ensure that you have a project that has implemented the basic real-time engagement functionality.

Implement channel connection management

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

In your Agora project, open the file used to manage AgoraRtcEngineDelegate and copy the following code to the AgoraRtcEngineDelegate initialization process.

func rtcEngine(_engine: AgoraRtcEngineKit, connectionChangedToState 
                 state: AgoraConnectionStateType 
                reason: AgoraConnectionChangedReadon) {
    LogUtils.log(message: "Connection state changed: \(state) \(reason)")
}

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

To help you troubleshoot network interruption, connectionChangedToState also has the reason parameter that explains why the connection state changes. For the reasons for the change and how to troubleshoot, refer to Connection state change reasons.

Reference

This section provides reference information you may need when managing the channel connection state.

Connection states

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

Connection state change reasons

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

API Reference

• getConnectionState
• connectionChangedToState