Connection

To use RC Chat SDK's messaging features, your app client must first establish a successful connection with RC servers.

When receiving a connection request from the client, RC servers will verify the user's identity token (Token parameter) to determine whether to allow the connection.

Prerequisites

• Obtain a Token via server API User Registration (Get Token). RC client SDK doesn't provide Token retrieval methods. Your app should call its own server to obtain the Token from RC servers.
  • After obtaining the Token, clients may store it for future connections. The storage location depends on your app design. If the Token remains valid, there's no need to request a new one.
  • Token validity period can be configured in Console, defaulting to permanent validity. Even when generating a new Token, the old one remains valid until expiration. After expiration, obtain a new Token. You may actively invalidate Tokens using server API Invalidate Token.
• We recommend setting up connection status monitoring before connecting.
• Complete SDK initialization.

tip

Never call server APIs directly from the client to obtain Tokens. Token retrieval requires App Key and App Secret. If these credentials are stored client-side and the app gets decompiled, your App Key/Secret could be compromised. Always obtain Tokens through your app server.

Connecting to Chat Servers

Determine the appropriate timing (login, registration, or other scenarios preventing access to the app homepage) to initiate connection requests to RC chat servers based on your business requirements.

Key considerations:

• You must call the connect method after SDK initialization. Otherwise, callbacks may not trigger.
• The SDK implements automatic reconnection. When network issues cause IM disconnection, it will retry until the app actively disconnects (see Disconnection).

API (With Timeout Setting)

For first-time connections, we recommend using this timeout-enabled interface with timeLimit parameter. In cases of poor network connectivity, use the timeout error callback to notify users (e.g., suggesting retry when network improves).

Once connected successfully, the SDK's reconnection mechanism takes over automatically. For network-related disconnections, the SDK will continuously retry until successful—no manual reconnection needed. Active disconnection by the app will disable this mechanism (see Disconnection). For other scenarios, see Reconnection Mechanism and Multi-Device Kick.

For password-free login, set timeLimit to 0 and perform page navigation in dbOpenedBlock to prioritize displaying local history data, letting the SDK handle all connection logic.

API Prototype

- (void)connectWithToken:(NSString *)token
               timeLimit:(int)timeLimit
                dbOpened:(nullable void (^)(RCDBErrorCode code))dbOpenedBlock
                 success:(nullable void (^)(NSString *userId))successBlock
                   error:(nullable void (^)(RCConnectErrorCode errorCode))errorBlock;

Parameters

Parameter	Type	Required	Description
token	NSString	Yes	For first-time connections, must be obtained by your app server calling RC server API. See server API docs User Registration.
timeLimit	int	Yes	SDK connection timeout in seconds. SDK will attempt connection for max timeLimit seconds. On timeout, returns RC_CONNECT_TIMEOUT error and stops retrying. Set timeLimit < 0 for no timeout—SDK will keep retrying until success or unrecoverable errors (e.g., invalid Token).
dbOpenedBlock	Block	No	Callback when local message database opens. code returns RCDBErrorCode. 0 indicates success.
successBlock	Block	No	Connection success callback. userId returns the successfully connected user ID.
errorBlock	Block	No	Connection failure callback, indicating unrecoverable errors (e.g., invalid Token). status returns error code RCConnectErrorCode.

Sample Code

[[RCIM sharedRCIM] connectWithToken:@"Token obtained by your server via server API" timeLimit:30
    dbOpened:^(RCDBErrorCode code) {
        //Message database opened, proceed to main interface
    } success:^(NSString *userId) {
        //Connection successful
    } error:^(RCConnectErrorCode status) {
        if (status == RC_CONN_TOKEN_INCORRECT) {
            //Token error—verify SDK initialization uses same App Key as your server
        } else if(status == RC_CONNECT_TIMEOUT) {
            //Connection timeout—notify user to retry when network improves
        } else {
            //Connection failed—handle according to error code
        }
    }];

API (Without Timeout)

Recommended for returning users who have previously connected successfully to RC chat servers.

Since these users have historical data, immediate connection success isn't critical. Perform page navigation in dbOpenedBlock to display local history first, letting the SDK handle all connection logic.

tip

In poor network conditions, callbacks may be significantly delayed.

After calling this API, the SDK's reconnection mechanism takes over automatically until successful connection or active disconnection (see Disconnection). For other scenarios, see Reconnection Mechanism and Multi-Device Kick.

API Prototype

- (void)connectWithToken:(NSString *)token
                dbOpened:(nullable void (^)(RCDBErrorCode code))dbOpenedBlock
                 success:(nullable void (^)(NSString *userId))successBlock
                   error:(nullable void (^)(RCConnectErrorCode errorCode))errorBlock;

Parameters

Parameter	Type	Required	Description
token	NSString	Yes	For first-time connections, must be obtained by your app server calling RC server API. See server API docs User Registration.
dbOpenedBlock	Block	No	Callback when local message database opens. code returns RCDBErrorCode. 0 indicates success.
successBlock	Block	No	Connection success callback. userId returns the successfully connected user ID.
errorBlock	Block	No	Connection failure callback, indicating unrecoverable errors (e.g., invalid Token). status returns error code RCConnectErrorCode.

Sample Code

[[RCIM sharedRCIM] connectWithToken:@"Token obtained by your server via server API"
    dbOpened:^(RCDBErrorCode code) {
        //Message database opened, proceed to main interface
    }success:^(NSString *userId) {
        //Connection successful
    }error:^(RCConnectErrorCode status) {
        if (status == RC_CONN_TOKEN_INCORRECT) {
            //Request new Token from your server and reconnect
        } else {
            //Connection failed—handle according to error code
        }
    }];

Connection Status Codes

Refer to the following table for RCConnectErrorCode explanations and handling suggestions.

tip

Regarding RC_CONN_TOKEN_INCORRECT:

1. When this occurs, request a new Token from your server and reconnect—but avoid infinite loops that could degrade user experience.
2. Callbacks don't execute on the original calling thread. Switch to main thread for UI operations.

Error Code	Value	Description	Solution
RC_CONN_TOKEN_INCORRECT	31004	Invalid Token. Typically occurs when client SDK and app server use different App Keys. RC provides separate App Key/Secret pairs for production and development environments. Switching environments often causes mismatches.	Verify consistent App Key usage between SDK and server.
RC_CONN_TOKEN_EXPIRE	31020	Expired Token. Occurs when Token validity period (configured in Console) expires. Your app server must request a new Token from RC servers for reconnection.	Request new Token from your server, then reconnect with it.
RC_CONNECT_TIMEOUT	34006	Reconnection timeout. Occurs in no-network environments when using timeout-enabled connection API. SDK stops retrying after timeout. Prompt users to retry when network recovers.	Manually reconnect by calling connection API again.
RC_CONN_APP_BLOCKED_OR_DELETED	31008	AppKey banned	Check if your AppKey is banned or deleted.
RC_DISCONN_KICK	31010	User kicked after successful connection	Return to login page and notify user about being kicked.
RC_CONN_OTHER_DEVICE_LOGIN	31023	User logged in on another device during connection, causing current device to be kicked	Return to login page and notify user about login on another device.
RC_CONN_USER_BLOCKED	31009	Banned user	Return to login page and notify user about ban.
RC_CLIENT_NOT_INIT	33001	SDK not initialized	Initialize SDK before using any features.
RC_INVALID_PARAMETER	33003	Invalid parameters in API calls	Verify parameter types and values in API calls.
DATABASE_ERROR	33002	Database error	Check if userId contains special characters. SDK supports alphanumeric userIds (max 64 bytes).