Connection

After the application client successfully connects to the RC server, it can use the message sending and receiving functions of the RC IM SDK.

When the RC server receives a connection request from the client, it determines whether to allow the user to connect based on the user authentication token (Token parameter) carried in the connection request.

Prerequisites

• Obtain a token via the server-side API Register User (Get Token). The RC client SDK does not provide a method to obtain a token. The application can call its own server to obtain the token from the RC server.
  • After obtaining the token, the client can save the token as needed for subsequent connections. The specific storage location depends on the application client design. If the token is still valid, there is no need to request a new token from RC.
  • The token validity period can be configured in the Console, with the default being permanently valid. Even if a new token is regenerated, the old token remains valid if it has not expired. Once the token expires, a new token needs to be obtained. If necessary, you can actively call the server-side API Invalidate Token.
• It is recommended that the application set up a connection status listener before connecting.
• The SDK has been initialized.

tip

Do not call the server-side API directly from the client to obtain a token. Obtaining a token requires providing the App Key and App Secret. If these credentials are stored on the client, they could be exposed if the application is decompiled. Therefore, always ensure that the token is obtained from the application server.

Connect to the Chat Server

Decide the appropriate timing (login, registration, or other occasions to avoid being unable to access the application homepage) to initiate a connection request to the RC chat server based on your application's business requirements and design.

Please note the following:

• The connect method must be called after the SDK is initialized. Otherwise, there may be no callback.
• The SDK has a reconnection mechanism. Do not call connect multiple times within an application lifecycle. Otherwise, multiple callbacks may be triggered, leading to the callbacks being cleared.
• Call it once in the application's main process.

Interface (with timeout setting)

When the client user connects to the chat server for the first time, it is recommended to call the interface with a connection timeout (timeLimit) and set the timeout duration. In cases of poor network conditions leading to connection timeout, you can use the timeout error callback of the interface to remind the user on the UI, such as suggesting the client user to reconnect when the network is normal.

Once the connection is successful, the SDK's reconnection mechanism will immediately take effect and handle all reconnection processes. When disconnected due to network issues, the SDK will continuously attempt to reconnect until successful, without requiring additional connection operations from you. If the application actively disconnects, it will exit the reconnection mechanism. For more details, see Disconnect. For other scenarios, refer to Reconnection Mechanism and Reconnection Kick.

If logging in offline subsequently, it is recommended to set the timeLimit parameter to 0, allowing page navigation immediately after the database open callback (onDatabaseOpened) to prioritize displaying local historical data. The connection logic is then fully managed by the SDK.

Interface Prototype

RongIMClient.connect(token, timeLimit, connectCallback);

Parameter Description

Parameter	Type	Description
token	String	The token obtained from the server.
timeLimit	int	Timeout duration (in seconds). No reconnection will be attempted after the timeout. If the value is ≦ 0, the connection will continue until successful or a business error occurs.
connectCallback	ConnectCallback	Connection callback. See Connection Callback Method Description below.

• Detailed Explanation of timeLimit Parameter:

  • timeLimit ≦ 0: The IM will continue to connect until successful or a business error occurs (e.g., invalid token).
  • timeLimit > 0: The IM will attempt to connect for a maximum of timeLimit seconds. If the connection is not successful within timeLimit seconds, it will stop reconnecting and notify the connection timeout via the onError callback. You will need to manually call the connect interface again.

Example Code

public connectIM(String token){
  boolean isCachedLogin == getLoginStatusFromSP(context); //Pseudo code, read whether the user is password-free login from sharedpreference
  int timeLimit = 0;
  if(!isCachedLogin) {
    timeLimit = 5;
  }
  RongIMClient.connect("User Token", timeLimit, new RongIMClient.ConnectCallback() {
    @Override
    public void onDatabaseOpened(RongIMClient.DatabaseOpenStatus code) {
        if(RongIMClient.DatabaseOpenStatus.DATABASE_OPEN_SUCCESS.equals(code)) {
					//Local database opened, navigate to the conversation list page
        } else {
          //Database open failed, you can show a toast prompt.
        }
      }

    @Override
    public void onSuccess(String s) {
        //Connection successful, if no page navigation was done during onDatabaseOpened(), you can navigate here.
    }

    @Override
    public void onError(RongIMClient.ConnectionErrorCode errorCode) {
        if(errorCode.equals(RongIMClient.ConnectionErrorCode.RC_CONN_TOKEN_EXPIRE)) {
            //Request a new token from the APP server, and reconnect with the new token after obtaining it.
        } else if (errorCode.equals(RongIMClient.ConnectionErrorCode.RC_CONNECT_TIMEOUT)) {
            //Connection timeout, show a prompt, and guide the user to reconnect when the network is normal.
        } else {
            //Other business error codes, handle accordingly based on the specific error code.
        }
    }
	})
}

Interface (without timeout setting)

If the client user has successfully logged into your application and connected to the RC chat server, it is recommended to use this interface for subsequent offline logins.

Since the user already has historical data, there is no strong dependency on a successful connection. You can navigate immediately after the database open callback (onDatabaseOpened) to prioritize displaying local historical data. The connection logic is fully managed by the SDK.

tip

When the network is poor, there may be no callback for a long time.

After calling this interface, the SDK's reconnection mechanism will immediately take effect and handle all reconnection processes. The SDK will continuously attempt to reconnect until successful, without requiring additional connection operations from you. If the application actively disconnects, it will exit the reconnection mechanism. For more details, see Disconnect. For other scenarios, refer to Reconnection Mechanism and Reconnection Kick.

Interface Prototype

RongIMClient.connect(token, connectCallback);

Parameter Description

Parameter	Type	Description
token	String	The user authentication token obtained from the server.
connectCallback	ConnectCallback	Connection callback. See Connection Callback Method Description below.

Connection Callback Method Description

The connection callback connectCallback provides the following three callback methods:

• onDatabaseOpened(DatabaseOpenStatus code)

  Local database open status callback. When DATABASE_OPEN_SUCCESS is called back, it indicates that the local database is open. At this point, local historical conversations and messages can be pulled, suitable for offline login scenarios.

• onSuccess(String userId)

  Connection successful callback, returning the currently connected user ID.

• onError(ConnectionErrorCode errorCode)

  Connection failed callback, returning the corresponding connection error code. Developers need to refer to Connection Status Codes for different business handling.

  Common errors include:

  • The SDK was not initialized before calling the connect() method.

  • The App Key of the application client and the application server are inconsistent, resulting in a TOKEN_INCORRECT error.

    RC provides two independent App Key / Secret for each application to isolate production and development environments. When switching from the test environment to the production environment, it is easy to encounter inconsistencies between the App Key of the application client and the application server.

  • The token has expired. See [Get Token].

Connection Status Codes

The following table lists the connection-related error codes.

Name	Value	Description
IPC_DISCONNECT	-2	IPC process terminated unexpectedly. Possible reasons: 1. Mobile system policy causing the IPC process to be recycled or unbound, triggering this issue when the application layer calls the IM interface. The SDK will handle automatic reconnection, no additional handling is required from the application. 2. Unable to find the libRongIMLib.so or libsqlite.so corresponding to the CPU architecture. Ensure that the corresponding architecture's so is integrated.
RC_CONN_ID_REJECT	31002	AppKey error, please check if the AppKey you are using is correct.
RC_CONN_TOKEN_INCORRECT	31004	Token invalid Please check if the AppKey used for client initialization matches the AppKey used to obtain the token on your server.
RC_CONN_NOT_AUTHRORIZED	31005	App verification failed (App verification feature is enabled but verification failed).
RC_CONN_APP_BLOCKED_OR_DELETED	31008	App is blocked or deleted. Please check if the AppKey you are using is blocked or deleted.
RC_CONN_USER_BLOCKED	31009	Connection failed, usually because the user is blocked. Please check if the Token you are using is correct and if the corresponding UserId is blocked.
RC_CONN_TOKEN_EXPIRE	31020	Token expired Usually because the token expiration time is set in the Console. You need to request a new token from your server and reconnect with the new token.
RC_CONN_PROXY_UNAVAILABLE	31028	Proxy service unavailable.
RC_CLIENT_NOT_INIT	33001	SDK not initialized. The SDK must be initialized before using any of its functions.
RC_CONNECTION_EXIST	34001	Connection already exists or is in the process of reconnecting.
RC_CONNECT_TIMEOUT	34006	SDK internal connection timeout. This error occurs when calling the connection interface with a timeout setting and setting a valid timeLimit value. The SDK will not continue to reconnect. The APP needs to manually call the connect interface to reconnect.
UNKNOWN	-1	Unknown error.