Skip to main content

Quick Start

This tutorial is designed to help developers quickly understand and master the basic integration process and core communication capabilities of the IMLib SDK (RC Instant Messaging Library). Through this tutorial, you will complete the entire workflow including IMLib SDK import, initialization, listener setup, connection establishment, and message sending.

Environment Requirements​

  • Xcode version 11 or higher is required.
  • Apple devices must run iOS 9.0 or later.
  • If you plan to integrate the SDK via CocoaPods, version 1.10.0 or higher is required. This is because the IMLib SDK switched to XCFramework format after version 5.1.1, and CocoaPods fully supports XCFramework integration starting from version 1.10.0. For details, refer to the Knowledge Base Documentation.

To install the CocoaPods environment, follow the CocoaPods Installation Guide.

Preparation​

  1. Visit the RC Console to register your developer account. Upon successful registration, the console automatically creates an application for you in the development environment.

  2. On the console's Key Management page, obtain your application's AppKey for the development environment. You can view application information on this page, including App Key, App Secret, and the assigned data center. appkey You can also create your own application and obtain the corresponding environment App Key and App Secret.

    tip

    Each application has two distinct App Keys corresponding to the development and production environments, with data isolation between them. Before your application goes live, it's recommended to switch to the production environment App Key for comprehensive pre-launch testing and final release.

Importing the SDK​

RC supports two integration methods: adding remote dependencies via CocoaPods or importing the IMLib XCFramework locally into your project. Starting from IMLib 5.12.2, the SDK also supports import via Swift Package Manager. The following example demonstrates adding remote dependencies via CocoaPods.

  1. If your project doesn't have a Podfile, open Terminal, navigate to your project's root directory, and run the pod init command. This will automatically create a default Podfile. Add the following content to your project's Podfile:

    pod 'RongCloudIM/IMLib', '~> x.y.z'
    tip

    Here, x.y.z represents the specific version number of IMLib. You can find the latest version by executing pod repo update followed by pod search RongCloudIM in Terminal to query the latest IMLib version in the CocoaPods repository.

  2. Open Terminal, navigate to the directory containing the Podfile, and run the following command:

    pod install
    tip

    If you encounter errors like CocoaPods could not find compatible versions for, first execute pod repo update in Terminal, then run the pod install command again.

  3. Open the xcworkspace file in your project directory using Xcode to load the project.

Initializing the SDK​

All IMLib SDK interface calls require importing the SDK header file:

#import <RongIMLibCore/RongIMLibCore.h>

To ensure proper connection to RC servers and use of RC's instant messaging services (IM services), you must initialize the IMLib SDK by calling the init method. Before initialization, you need to obtain the App Key from the RC Console and configure RCInitOption (initialization settings).

RCInitOption encapsulates areaCode (data center region code), naviServer (navigation service address), fileServer (file service address), statisticServer (data statistics service address), and crashMonitorEnable (crash monitoring switch). For details, see Initialization.

If you're using the Beijing data center, you don't need to configure RCInitOption—the IMLib SDK automatically connects to the Beijing data center by default.

NSString *appKey = @"Your_AppKey"; // example: bos9p5rlcm2ba
RCInitOption *initOption = nil;

[[RCCoreClient sharedCoreClient] initWithAppKey:appKey option:initOption];

If you're using an overseas data center, you must specify the corresponding AreaCode.

NSString *appKey = @"Your_AppKey"; // example: bos9p5rlcm2ba
RCInitOption *initOption = [[RCInitOption alloc] init];
initOption.areaCode = RCAreaCodeSG;// Singapore Data Center

[[RCCoreClient sharedCoreClient] initWithAppKey:appKey option:initOption];
tip

If you're using a development version of IMLib SDK below 5.4.2 or a stable version below or equal to 5.3.8, you must call the initWithAppKey method of RCCoreClient and pass the App Key for initialization. For details, see Initialization.

Message Listening​

By setting up a message receiver listener, users can receive all types of real-time and offline messages.

tip

To ensure receipt of all offline messages, set up the listener after initializing the SDK but before connecting to RC IM servers.

[[RCCoreClient sharedCoreClient] addReceiveMessageDelegate:self object:nil];

- (void)onReceived:(RCMessage *)message left:(int)nLeft object:(id)object {

}

Connecting to RC IM Servers​

The user Token is an authentication token corresponding to the user ID, serving as the unique identity credential for application users in RC. Before using RC's instant messaging features, the application client must establish an IM connection with RC, which requires passing the Token during connection.

In actual business operations, the application client needs to obtain the Token by having the application server call the IM Server API. For details, see the Server API documentation User Registration.

  1. To simulate message exchange between users via RC IM servers, you first need to register a user. In actual business scenarios, the application client obtains the token by having the application server call RC's IM Server API. For details, see the Server API documentation User Registration. The call returns the following:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"code":200,"userId":"1","token":"gxld6GHx3t1eDxof1qtxxYrQcjkbhl1V@sgyu.cn.example.com;sgyu.cn.example.com"}
  1. Set up a connection listener to monitor connection status in real-time. You can provide UI feedback to users based on connection status (e.g., displaying "Network connection lost" or "Reconnected") to enhance user experience. It's recommended to set up the IM connection status listener after initializing the SDK but before connecting to IM within the application lifecycle, and remove the listener when no longer needed. For details, see [Setting Connection Status Listener].

@protocol RCConnectionStatusChangeDelegate <NSObject>

// Add delegate
[[RCCoreClient sharedCoreClient] addConnectionStatusChangeDelegate:self];


/*!
 IMLib Connection Status Listener

 @param status  Connection status between SDK and RC servers

 @discussion After setting up the IMLib connection listener, this method will be called back when the connection status between the SDK and RC servers changes.
 */
- (void)onConnectionStatusChanged:(RCConnectionStatus)status {
}
@end

  1. Call the connectWithToken method to connect the user with userId 1 to RC IM services. Note: The IMLib SDK has a reconnection mechanism, so calling connect once per application lifecycle is sufficient. For details, see Connection.
[[RCCoreClient sharedCoreClient] connectWithToken:@"RC token" dbOpened:^(RCDBErrorCode code) {
    //Message database opened, can proceed to main page
} success:^(NSString *userId) {
    //Connection successful
} error:^(RCConnectErrorCode errorCode) {
    if (errorCode == RC_CONN_TOKEN_INCORRECT) {
        //Obtain new token from APP server and reconnect
    } else {
        //Unable to connect to IM server, handle accordingly based on error code
    }
}];

Sending Messages​

Finally, you can simulate sending a text message to the user with userId 2. Besides text messages, you can also send different types of messages including images, files, voice, and more. For details, see Message Types.

RCTextMessage *messageContent = [RCTextMessage messageWithContent:@"Hello, this is a message sent from User 1"];


RCMessage *message = [[RCMessage alloc] initWithType:ConversationType_PRIVATE
                                            targetId:@"2"
                                           direction:MessageDirection_SEND
                                             content:messageContent];

[[RCCoreClient sharedCoreClient] sendMessage:message pushContent:nil pushData:nil attached:^(RCMessage *message) {
    // Message has been saved to local database
} successBlock:^(RCMessage *successMessage) {
    // Success
} errorBlock:^(RCErrorCode nErrorCode, RCMessage *errorMessage) {
    // Failure
}];
Last updated on