Establish Connection

To use the message sending and receiving features of RC's IM SDK, the application client must successfully connect to the RC server.

Upon receiving a connection request from the client, the RC server will determine 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 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 retrieve 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 until it expires. Once the Token expires, a new Token must be obtained. If necessary, you can actively call the server 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 directly call the server API to obtain a Token on the client side. Obtaining a Token requires providing the App Key and App Secret. If these credentials are stored on the client side, 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

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

Please note the following:

• The connect method must be called after the SDK is initialized. Otherwise, there may be no callback.
• The SDK internally implements a reconnection mechanism. When the IM connection is lost due to network anomalies, it will automatically reconnect until the application actively disconnects (see Disconnect).

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 in seconds. In cases where the connection times out due to poor network conditions, you can use the timeout error callback to remind the user on the UI, such as suggesting the client user to wait until the network is normal before reconnecting.

Once the connection is successful, the SDK's reconnection mechanism will immediately take effect and handle all reconnection processes. When the connection is lost due to network reasons, the SDK will continuously reconnect until the connection is successful, without requiring additional connection operations from you. Active disconnection by the application will exit the reconnection mechanism. For details, see Disconnect. For other cases, please refer to the reconnection mechanism details below.

If password-free login is used, it is recommended to set the timeLimit parameter to 0, and perform page navigation in the dbOpenedBlock callback to prioritize displaying local historical data. The connection logic is then entirely managed by the SDK.

Example Call

[[RCIMClient sharedRCIMClient] connectWithToken:@"The token value obtained by the developer's server through the server API"
    timeLimit:5
    dbOpened:^(RCDBErrorCode code) {
        //The message database is opened, and you can proceed to the main page
    } success:^(NSString *userId) {
        //Connection successful
    } error:^(RCConnectErrorCode status) {
        if (status == RC_CONN_TOKEN_INCORRECT) {
            //Token error, check if the App Key used for SDK initialization matches the one used by the App server to obtain the Token
        } else if(status == RC_CONNECT_TIMEOUT) {
            //Connection timeout, prompt the user to wait until the network is normal before reconnecting
        } else {
            //Unable to connect to the IM server, handle accordingly based on the error code
        }
    }]

Input Parameter Description

Parameter	Type	Description
token	NSString	Must be obtained by the App server calling the RC server API for the first connection. See the server API documentation Register User
timeLimit	int	SDK connection timeout, in seconds
dbOpenedBlock	Block	Callback when the local message database is opened
successBlock	Block	Callback when the connection is successfully established
errorBlock	Block	Callback when the connection fails to establish

• timeLimit Parameter Description:

  Parameter	Value Range	Description
  timeLimit	≦ 0	The SDK will keep trying to connect until it succeeds or encounters an error that the SDK cannot handle (e.g., invalid token), equivalent to the above connection interface.
  timeLimit	> 0	The SDK will try to connect for up to timeLimit seconds. If it times out, it will return the RC_CONNECT_TIMEOUT error and stop reconnecting.

Return Parameter Description

• dbOpenedBlock Description:

  Callback Parameter	Callback Type	Description
  code	RCDBErrorCode	Whether the database is opened

• successBlock Description:

  Callback Parameter	Callback Type	Description
  userId	NSString	The user ID of the successful connection

• errorBlock Description:

  Callback Parameter	Callback Type	Description
  status	RCConnectErrorCode	The error code for connection failure. See Connection Status Codes below.

Interface (No Timeout Setting)

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

Since the user already has historical data, it is not strictly necessary to depend on a successful connection. You can perform page navigation in the dbOpenedBlock callback to prioritize displaying local historical data. The connection logic can be entirely 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 reconnect until the connection is successful, without requiring additional connection operations from you. Active disconnection by the application will exit the reconnection mechanism. For details, see Disconnect. For other cases, please refer to the reconnection mechanism details below.

Example Call

[[RCIMClient sharedRCIMClient] connectWithToken:@"The token value obtained by the developer's server through the server API"
        dbOpened:^(RCDBErrorCode code) {
            //The message database is opened, and you can proceed to the main page
        }
        success:^(NSString *userId) {
            //Connection successful
        }
        error:^(RCConnectErrorCode status) {
            if (status == RC_CONN_TOKEN_INCORRECT) {
                //Obtain a new token from the App server and reconnect
            } else {
                //Unable to connect to the IM server, handle accordingly based on the error code
            }
        }]

Input Parameter Description

Parameter	Type	Description
token	NSString	Must be obtained by your Server accessing the RC service Token
dbOpenedBlock	Block	Called when the local message database is opened
successBlock	Block	Called when the connection is successfully established
errorBlock	Block	Called when the connection fails to establish

Return Parameter Description

• dbOpenedBlock Description:

  Callback Parameter	Callback Type	Description
  code	RCDBErrorCode	Whether the database is opened

• successBlock Description:

  Callback Parameter	Callback Type	Description
  userId	NSString	The user ID of the successful connection

• errorBlock Description:

  Callback Parameter	Callback Type	Description
  status	RCConnectErrorCode	The error code for connection failure. See Connection Status Codes below.

Connection Status Codes

Please refer to the table below for detailed explanations and suggested handling of RCConnectErrorCode error codes.

tip

Regarding RC_CONN_TOKEN_INCORRECT:

1. In the case of RC_CONN_TOKEN_INCORRECT, you need to request your server to obtain a new Token and establish a connection, but be careful to avoid infinite loops to prevent affecting the App user experience.
2. The callback thread for this method is not the original calling thread. Please switch to the main thread when performing UI operations.

Error Code	Value	Description	Handling Suggestion
RC_CONN_TOKEN_INCORRECT	31004	Token error. Commonly occurs when the App Key used by the client SDK does not match the one used by the App server. RC provides separate App Key / Secret for isolating production and development environments. It is easy to encounter App Key mismatch issues when switching from a test environment to a production environment.	Check if the App Key used by the SDK matches the one used by the App server.
RC_CONN_TOKEN_EXPIRE	31020	Token has expired. Commonly occurs when the Token expiration time is set in the Console. After the Token expires, your App server needs to request a new Token from the RC server, and then use the new Token to establish a connection.	The client needs to request the App server to obtain a new Token from RC. After receiving the new Token, the client should use it to initiate a connection.
RC_DISCONN_KICK	31010	User was kicked offline after successfully connecting	Return to the login page and notify the user that they were kicked offline.
RC_CONN_OTHER_DEVICE_LOGIN	31023	The user logged in on another device during the connection process, causing the current device to be kicked offline.	Return to the login page and notify the user that another device has logged in to the current account.
RC_CONN_USER_BLOCKED	31009	User was banned while online, causing the connection to be disconnected.	Return to the login page and notify the user that they have been banned.
RC_CONNECT_TIMEOUT	34006	Automatic reconnection timeout. Commonly occurs in a no-network environment and only happens when the connection interface is called with a valid timeout setting. After timeout, the SDK will stop reconnecting. Developers need to notify the user and suggest reconnecting when the network is restored.	Reconnect manually by calling the connection interface again.
RC_CONN_APP_BLOCKED_OR_DELETED	31008	Appkey is blocked	Check if the AppKey you are using is blocked or deleted.
RC_CONN_PROXY_UNAVAILABLE	31028	Proxy service is unavailable
RC_CLIENT_NOT_INIT	33001	SDK is not initialized	Initialize the SDK before using any of its features.
RC_INVALID_PARAMETER	33003	Invalid parameter passed by the developer when calling the interface	Check the parameter type and value passed when calling the interface.
DATABASE_ERROR	33002	Database error	Check if the user's userId contains special characters. The SDK supports userIds composed of uppercase and lowercase letters, numbers, and some special symbols + = - _, with a maximum length of 64 bytes.