Quick Start

This tutorial is designed to help beginners quickly get familiar with RC's Instant Messaging Library (IMLib). In this tutorial, you will experience the basic process of integrating the SDK and the fundamental communication capabilities of IMLib.

Prerequisites

• Register a developer account. After successful registration, the Console will automatically create your first application by default, generating an App Key for the development environment and using the Singapore Data Center.

• Obtain the App Key for the development environment application here. If you are not using the default application, please refer to How to create an application and obtain the corresponding App Key and App Secret for the environment.

  tip

  Each application has two different App Keys, corresponding to the development and production environments, with data isolation between the two environments. Before your application goes live, you can switch to using the App Key for the production environment for testing and final release.

Environment Requirements

Name	Version
Xcode	11 +
iOS	9.0 +
CocoaPods	1.10.0 +

SDK 5.1.1 and later require CocoaPods 1.10.0 +. For details, please refer to the Knowledge Base Documentation.

Importing the SDK

Method 1: CocoaPods

1. Add the following content to your Podfile:

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

   x.y.z represents the specific version. Please check the latest version on the CocoaPods repository.

2. Run the following command in the terminal:

   pod install
   tip

   If you encounter issues finding the relevant version, you can first execute pod repo update, then run pod install.

3. After the previous step is completed, CocoaPods will generate an xcworkspace file in your project's root directory. Simply open this file with Xcode to load the project.

Method 2: Swift Package Manager

tip

The method of importing via Swift Package Manager has been supported since IMLib 5.12.2.

1. Open your Xcode project.

2. Go to File > Add Package Dependency.

3. In the pop-up window, paste one of the following URLs:

   • https://github.com/rongcloud/RongCloudIM-iOS
   • https://gitee.com/rongcloud/RongCloudIM-iOS

4. Xcode will prompt you to select the product. IMLibCore provides core IM capabilities, and the remaining components can be selected based on your business needs.

Component Overview

RC IM SDK provides the following components for developers to choose from. The components below can be used in combination, and their capabilities are described as follows:

Swift Package	Dynamic Library	Description
IMLibCore	RongIMLibCore.xcframework	Core IM features.
ChatRoom	RongChatRoom.xcframework	Chatroom features (includes IMLibCore)
CustomerService	RongCustomerService.xcframework	Customer service features (includes IMLibCore)
Discussion	RongDiscussion.xcframework	Discussion group features (includes IMLibCore)
PublicService	RongPublicService.xcframework	Official account features (includes IMLibCore)

Initializing the SDK

The core classes of RC's Instant Messaging Client SDK are RCCoreClient and RCIMClient. When initializing the SDK, you need to pass in the App Key for the production or development environment.

Import the SDK header file.

#import <RongIMLib/RongIMLib.h>

If the SDK version is ≧ 5.4.2, please use the following initialization method.

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

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

The initialization configuration (RCInitOption) encapsulates the area code (RCAreaCode), navigation service address (naviServer), file service address (fileServer), and data statistics service address (statisticServer). If no settings are made, the default configurations will be used. The SDK connects to the China (Beijing) Data Center by default.

If the App Key does not belong to the China (Beijing) Data Center, a valid initialization configuration must be passed in. For detailed initialization instructions, refer to Initialization.

Obtaining User Token

The User Token is an authentication token corresponding to the user ID, serving as the unique identifier for the application's user in RC. Before using RC's instant messaging features, the application client must establish an IM connection with RC, and the Token must be passed in during the connection.

In actual business operations, the application client needs to call the IM Server API through the application server to apply for and obtain the Token. For details, refer to the Server API documentation User Registration.

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"}

Establishing an IM Connection

Using the Token obtained in the previous step, simulate the user with userId 1 connecting to the RC server.

[[RCCoreClient sharedCoreClient] connectWithToken:@"RC token" dbOpened:^(RCDBErrorCode code) {
    // The message database is opened, and you can proceed to the main page
} success:^(NSString *userId) {
    // Connection successful
} error:^(RCConnectErrorCode errorCode) {
    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
    }
}];

The SDK has implemented an automatic reconnection mechanism. For details, refer to Connection.

After calling the connection, you can Set Up Connection Status Monitoring to monitor the IM connection status in real-time, providing users with prompts in the UI to enhance the experience.

Listening for Messages

Set up a message receiver listener to receive all types of real-time or offline messages. Implementing this functionality requires developers to comply with the RCIMClientReceiveMessageDelegate protocol.

1. Set the listener's delegate after initialization and before connecting.

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

2. Implement the delegate method

   When the SDK receives a message, developers can handle it through the following method. The SDK will receive all messages, including one-to-one chat, group chat, chatroom, and system messages, through this method. Developers only need to set this up globally once; multiple setups will cause other delegates to fail.

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

Sending Messages

Send a text message to the user with userId 2. In the following example, the text message content messageContent is first constructed, followed by the RCMessage message instance, which specifies the recipient's user ID as 2 and the current conversation type as private chat ConversationType_PRIVATE.

RCTextMessage *messageContent = [RCTextMessage messageWithContent:@"Test text message"];

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) {
    // The message has been saved to the local database
} successBlock:^(RCMessage *successMessage) {
    // Success
} errorBlock:^(RCErrorCode nErrorCode, RCMessage *errorMessage) {
    // Failure
}];