Connection

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

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

Prerequisites

• Register a user (obtain a Token) via the server API. 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.
  • Once the Token is obtained, the client can save it as needed for future 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's validity period can be configured in the Console, with the default being permanently valid. Even if a new Token is generated, 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 establishing the connection.
• The SDK must be 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 reverse-engineered. Therefore, always ensure that the Token is obtained from the application server.

Connect to the IM Server

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

Method

Future<int> connect(String token, int timeout, {RCIMIWConnectCallback? callback});

Parameter Description

Parameter	Type	Description
token	String	The token obtained by calling the server API.
timeout	int	Connection timeout in seconds.
callback	RCIMIWConnectCallback	Connection event callback. The SDK supports callback-based responses starting from version 5.3.1. Other callback methods are deprecated as of version 5.4.0. If the callback parameter is provided, only the callback will be triggered.

Return Value

Return Value	Description
Future<int>	The status code of the current operation. 0 indicates success, and the specific result requires implementing the interface callback. Non-zero values indicate that the current operation failed, and the interface callback will not be triggered. Refer to the error codes for detailed errors.

Code Example

RCIMIWConnectCallback? callback = RCIMIWConnectCallback(onDatabaseOpened: (int? code) {
//...
}, onConnected: (int? code, String? userId) {
//...
});

int? ret = await engine?.connect(token, timeout, callback:callback);

Callback Methods

• onDatabaseOpened

Callback when the database is opened.

Function(int? code)? onDatabaseOpened;

Parameter Description

Parameter	Type	Description
code	int	The status code of the interface callback. 0 indicates success, while non-zero values indicate an exception.

Code Example

engine?.onDatabaseOpened = (int? code) {
//...
};

• onConnected

Callback for connection status.

Function(int? code, String? userId)? onConnected;

Parameter Description

Parameter	Type	Description
code	int	The status code of the interface callback. 0 indicates success, while non-zero values indicate an exception.
userId	String	The user ID of the successfully connected user.

Code Example

engine?.onConnected = (int? code, String? userId) {
//...
};

tip

1. The SDK has a built-in reconnection mechanism, so it is unnecessary to call connect() multiple times within an application lifecycle. Otherwise, multiple callbacks may be triggered, leading to callback clearance.
2. In the case of 31004, you need to request your server to retrieve a new Token and establish a connection. However, avoid infinite loops to prevent affecting the user experience.

Token Invalid (31004) Troubleshooting

Cause	Troubleshooting
Token Error	Check if the AppKey used for client initialization matches the AppKey used by your server to obtain the Token.
Token Expired	Check if the developer has set a Token expiration time in the Console. After expiration, you need to request your server to retrieve a new Token and establish a connection with the new Token.

Error Codes

Refer to the native platform error code definitions for connection error codes: Android Error Codes and iOS Error Codes