Channel connection status management

Feature introduction

In real-time audio and video scenarios, the connection between the client and server changes as users join or leave channels, and may also shift due to network issues that trigger reconnection or disconnection. Properly managing these connection states is essential to maintaining a stable, reliable user experience.

How it works

Connection status

When the connection status changes, the ARTC SDK triggers the onConnectionStatusChange callback. The following figure shows various connection statuses and how they change when users join and leave channels.

Automatic reconnection

During a call, if the connection is lost due to network issues, the SDK automatically attempts to reconnect. The following figure shows the callbacks that User A and User B receive when User A joins a channel where User B is present, loses connectivity, reconnects automatically, and ultimately fails to reconnect.

At T0: User A initiates a joinChannel request.
At T1: User A successfully joins the channel and receives the onJoinChannelResult(result=0) and onConnectionStatusChange callbacks.
At T2: User B detects that User A has joined the channel and receives the onRemoteUserOnLineNotify callback.
At T3: User A's connection is lost due to client network disconnection or other reasons.
At T4: User A's SDK detects the disconnection or stops receiving data from the server, initiates automatic reconnection, and User A receives the onConnectionStatusChange callback.
At T5: After multiple retry attempts within 100 seconds, the SDK still cannot rejoin the channel and stops trying. It sends the onConnectionStatusChange callback to User A. The user must then leave the current channel, verify local network connectivity, and rejoin after the network recovers.

Sample code

Android

onConnectionStatusChange - Network connection status change callback

@Override
public void onConnectionStatusChange(AliRtcEngine.AliRtcConnectionStatus status, AliRtcEngine.AliRtcConnectionStatusChangeReason reason) {
    super.onConnectionStatusChange(status, reason);
    Log.e(TAG, "onConnectionStatusChange.");
    ThreadUtils.runOnUiThread(new Runnable() {
        @Override
        public void run() {
            if (mLogView != null) {
                mLogView.logI("Network connection changed to: " + status + ", reason: " + reason);
            }
        }
    });
}

IOS

onConnectionStatusChange - Network connection status change callback

/**
 * @brief Channel connection status change callback
 * @param status Current status value, refer to AliRtcConnectionStatus enumeration for corresponding values
 * @param reason Specific reason for the status change, refer to AliRtcConnectionStatusChangeReason enumeration for corresponding values
*/
- (void)onConnectionStatusChange:(AliRtcConnectionStatus)status reason:(AliRtcConnectionStatusChangeReason)reason{
    NSString *stateStr = [NSString stringWithFormat:@"\nNetwork status: %@ status: %ld  Reason: %@ reason: %ld\n",[self callbackNetstatus:status], (long)status,[self callbackNetstatusReason:reason], (long)reason];
    MyLog(@"%@", stateStr);
}

Windows

OnConnectionStatusChange - Network connection status change callback

void AliSDKEventListener::OnConnectionStatusChange(int status, int reason)
{
    if (win_rtc_listener_)
    {
        win_rtc_listener_->OnConnectionStatusChange(status, reason);
    }
}

Status description

Connection status

Connection status	Description
Init	Initial status. Occurs before calling `joinChannel`.
Connecting	Transient status after calling the `joinChannel` method.
Connected	The app has successfully joined the channel. The SDK also triggers the `onJoinChannelResult` callback to confirm that the local client has joined the channel. The SDK then automatically publishes and subscribes to audio and video streams; users can also control publishing and subscribing manually.
Disconnected	Occurs after calling `leaveChannel`.
Reconnecting	The connection was interrupted. The SDK automatically attempts to reconnect. If rejoining succeeds, the SDK triggers onConnectionStatusChange (AliRtcConnectionStatusConnected, AliRtcConnectionChangedSignalingJoinChannelSuccess)
Failed	Connection failed. The SDK could not join the channel within 100 seconds and has stopped reconnecting. The user must call `leaveChannel`, verify local network connectivity, and call `joinChannel` again after the network recovers.

Status reason description

Connection status (status)	Status reason description (reason)
Init	No reason, initial status.
Connecting	Connecting: Joining the channel.
Connected	JoinChannelSuccess: Successfully joined the channel.
Disconnected	LeaveRoom: User actively left the channel.
Reconnecting	HeartbeatTimeout: No data received from the server for a period of time. Possible reasons include downstream network issues or high packet loss. NetworkInterrupted: Client network disconnection.
Failed	JoinChannelFailure: Failed to join or rejoin the channel, possibly due to persistent network disconnection or an invalid token.