Connection state transitions and recovery

During communication between the Signaling SDK and the server, the connection goes through multiple states. You observe and respond to these state transitions by listening to state change event notifications.

info

The information on this page is applicable to Signaling SDK versions 2.2.0 or later.

In real-world scenarios, disruptions affect a user's network connection. These disruptions cause corresponding changes in 's connection state. To maintain a seamless user experience despite these changes, the SDK ensures continuity of channel subscriptions and the temporary user status. Upon reconnecting from a disconnected state, the SDK automatically restores the previous subscriptions and the temporary user status, eliminating the need for user intervention.

This continuity assurance does not apply if you actively disconnect by logging out from Signaling. Logging out clears the channel subscriptions and the temporary user status, and resets the connection state to idle. In such cases, you must log in to the server again, re-establish channel subscriptions, and restore the previous usage status.

The Signaling SDK handles the following connection management tasks:

• Intelligently selects the nearest edge server for access and enables quick switchover to an alternate server in case of access failure.
• Selects the appropriate connection protocol and establishes connections with the server based on user configuration. To ensure service availability, Signaling employs a dual-protocol link mechanism and maintains both TCP and UDP connections simultaneously.
• Manages and preserves channel subscriptions and ensures continuity of temporary user status upon recovery from a temporary disconnection.
• Promptly notifies users of connection state changes to facilitate timely observation and response to a specific state change. This feature empowers you to enhance user experience through logical interventions at the business level.

This section describes the various connection states and their transitions in both message and stream channels.

To use a message channel, you initialize the SDK and log in to initiate a connection with the server. In case of an unexpected interruption, the SDK automatically makes attempts to restore the connection at increasing time intervals (2, 4, 8, 16... seconds) for up to 2 minutes. If the attempts are still unsuccessful, the SDK transitions to a long suspended state and retries at fixed 30-second intervals.

The following table gives an overview of the various connection states:

State	Description
IDLE	Idle state: The SDK enters this state when you create a client instance or after you explicitly call the logout method. In this state, the SDK does not attempt to establish or maintain a connection with the server. The SDK clears the session cache upon entering this state.
CONNECTING	Connecting state: When you call the login method, the SDK immediately enters this state. It also enters this state during each reconnection attempt after the connection is accidentally disconnected.
CONNECTED	Connected state: In this state, the client and the server are connected normally; users can access all Signaling capabilities.
DISCONNECTED	Disconnected state: The connection is temporarily disconnected. The SDK enters this state after the connection is lost due to a temporary network failure, or after an unsuccessful reconnection attempt. In this state, the client attempts to restore the connection to the server after 2, 4, 8, ... seconds. If the connection is restored, the SDK restores the previous channel subscription and the user status. In this state, users cannot send or receive messages. This state lasts for up to 2 minutes and switches to SUSPENDED if the connection cannot be restored within this time.
SUSPENDED	Connection pending state: This is a long-term disconnection state entered into due to no network connection or server unavailability. If the connection cannot be restored within 2 minutes, it enters a suspended state after attempts to restore the connection fail. In this state, the SDK periodically tries to restore the connection every 30 seconds. You can also call the login method to try to reconnect. Users cannot send or receive messages while in this state. If automatic reconnection is successful, the SDK automatically restores the channel subscriptions and the temporary user status. You can actively call the logout method to return to the IDLE state. However, note that doing so clears the session cache, and the SDK no longer guarantees the continuity of channel subscriptions and restoration of the user status.
FAILED	Failed state: If the client encounters an unrecoverable failure, such as a fatal error due to an incorrect app ID or expired token, the client enters this state. In this state, the SDK does not attempt to reconnect, and the client is unable to send or receive messages. To attempt reconnection, call the login method again.

The following figure shows possible transitions between message channel connection states:

The state of the connection between the SDK and the Signaling server undergoes several transitions during communication. The following figure illustrates the state transitions during some common message channel connection scenarios.

In a stream channel, you join a channel to initiate a connection with the server. In case of unexpected interruptions, the client automatically attempts reconnection for up to 20 minutes. If the attempts are unsuccessful, the stream channel connection state changes to failed, and the client ceases further reconnection attempts.

The table below provides an overview of the various stream channel connection states:

State	Description
IDLE	Idle state: The SDK enters this state after you create a stream channel instance or after you explicitly call the leave method from any state. In this state, the SDK clears the session cache, closes the connection, and does not attempt to establish a connection to the server.
CONNECTING	Connecting state: When you call the join method, the stream channel enters this state immediately. It also enters this state during each reconnection attempt after the connection is accidentally disconnected.
CONNECTED	Connected state: In this state, the client and the server are connected normally; users can access all Signaling stream channel capabilities.
FAILED	Failed state: If the SDK encounters an unrecoverable failure, such as a fatal error due to an incorrect app ID or expired token, it enters this state. In this state, the SDK does not attempt to reconnect, and the user is unable to send or receive messages. To attempt reconnection, call the join method again.

The following figure shows possible transitions between stream channel connection states:

The connection state between the stream channel and the Signaling server undergoes various transitions during communication. The following figure illustrates the state transitions during some common stream channel connection scenarios.

The onLinkStateEvent callback provides the information you need to understand network state transitions.

_7

RtmEventListener listener = new RtmEventListener() {

_7

@Override

_7

public void onLinkStateEvent(LinkStateEvent event) {

_7

}

_7

};

_7

_7

rtmClient.addEventListener(listener);

The event provides the following parameters:

• previousState: The state from which the change occurred.
• currentState: The current state after the change.
• serviceType: The type of service for which the connection state has changed.
• operation: The operation responsible for the change.
• reason: The reason behind the change.

To remove the callback use:

_1

rtmClient.removeEventListener(listener);

After each login operation, the SDK attempts to establish a connection with the server and generates a local session cache. This cache records information regarding channels the user subscribes or joins, and the temporary user status data set in these channels. This includes both the message channel and the stream channel.

When the client experiences temporary disconnection due to a network issue, it automatically attempts to reconnect. Upon successful reconnection, the SDK utilizes the session cache to restore the user's channel subscription and temporary user status data, to ensure continuity of the session. Whether the client recovers from the DISCONNECTED state or the SUSPENDED state, continuity is automatically restored as long as the user does not actively call the logout method to log out. However, if the user initiates logout, the session cache is cleared, and the connection status returns to IDLE. Upon a subsequent login, the user needs to resubscribe to channels and reset their temporary user statuses.

In the event of a sudden network disconnection, you can inspect the names of the affected channels by examining the affectedChannels field returned by the onLinkStateEvent event. The following example shows sample information contained in the affectedChannels field :

_4

"affectedChannels" : [

_4

"ChatRoom",

_4

"VirtualSpace"

_4

]

The Signaling client automatically recovers from non-fatal error states, and notifies you of the transition details through an onLinkStateEvent callback. Handle these events according to your business needs to optimize the user experience.

Some errors are fatal. This means that the SDK is unable to recover automatically from these errors and thus enters the FAILED state. In this state, the SDK does not attempt automatic reconnection. In such cases, troubleshoot potential errors independently and actively trigger reconnection by explicitly calling the login or join method.

Following is a list of issues that may lead to fatal errors:

• An invalid or expired token.
• The user ID of the current user is banned.
• Signaling is not enabled for the current app ID or the app ID is invalid
• Edge server resources are unavailable.
• The MESSAGE service is not deployed in the current environment.
• Usage limit exceeded.
• A stream channel instance was not created.
• The channel name is illegal.

Some errors are non-fatal; for example, a client experiences a brief network outage while passing through an underground tunnel. In such cases, the SDK attempts automatic reconnection. If reconnection is successful, the previously subscribed channels and temporary user status are restored automatically. However, if the user chooses to log out during this process, the client cache is cleared. This means that the cached channel subscriptions and temporary user statuses are removed. In such cases, users must re-login, resubscribe to channels, and reset temporary user statuses to resume the previous status.