Skip to main content

Getting Started (OC)

In this tutorial, you will experience the basic process of integrating Global IM UIKit and the UI interfaces provided by Global IM UIKit.

Environment Requirements​

The minimum requirements for Global IM UIKit for iOS are as follows.

  • iOS 9.0 or later
  • Xcode 13.0 or later
  • CocoaPods 1.12.0 or later

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, using the Singapore Data Center.

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

    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 is officially launched, you can switch to using the production environment App Key for testing and final release.

Demo Project​

RC provides an iOS Demo project that demonstrates the features of Global IM UIKit.

https://github.com/rongcloud/ios-global-im-uikit-quickdemo

Getting Started​

You can implement one-to-one chat, group chat, and receive system conversation messages by integrating Global IM UIKit for iOS.

Step 1 Create a Project​

Open Xcode and create a new project.

Image|Setting up your project in the Create new project dialog.

Step 2 Import the SDK​

You can use CocoaPods to install RCGlobal/IMUIKit. Please check the latest version on the CocoaPods repository.

CocoaPods​

Please prepare the CocoaPods environment in advance.

  1. Add the RCGlobal/IMUIKit framework to your Podfile in Xcode, as shown below.

    pod 'RCGlobal/IMUIKit', '~> x.y.z'

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

  2. Run the following command to install the RCGlobal/IMUIKit framework via CocoaPods. If you encounter issues finding the relevant version, execute pod repo update first, then pod install.

    pod install

  3. After the previous step is completed, the specified version of RC SDK will be automatically imported. CocoaPods will generate an xcworkspace file in your project root directory. Just open this file with XCode to load the project.

Step 3 Initialize with App Key​

Global IM UIKit relies on the instant messaging capabilities of IMLibCore, which needs to be initialized before use. The core class of IMLibCore is RCCoreClient, and the App Key for the production or development environment needs to be passed during initialization.

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

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

The initialization configuration (RCInitOption) encapsulates the area code (RCAreaCode) configuration. The SDK will obtain valid navigation service addresses, file service addresses, data statistics service addresses, and log service addresses through the area code.

  • If the App Key belongs to the China (Beijing) Data Center, you do not need to configure additional RCInitOption. The SDK will connect to the Beijing Data Center by default.
  • Please verify the overseas data center to which the current App Key belongs in the Console, and find the corresponding enumeration value in RCAreaCode for configuration.

For example, if you are using the Singapore Data Center, configure as follows:

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

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

For detailed instructions, refer to IMLib SDK Documentation · Initialization.

Step 4 Obtain the Current User Token​

The user Token is an authentication token corresponding to the user ID, which is the unique identity of the application user in RC. The application client must establish an IM connection with RC before using the instant messaging function, and the Token must be passed during the connection.

Important

RC's client SDK does not provide an API to obtain the token. During actual business operations, the application server must call the RC Server API /user/getToken.json (see Server API documentation Register User), passing the user identifier (userId) allocated by your application to exchange for the Token. The application client can request the Token from the application server before connecting.

Step 5 Connect to RC Server​

Use the token of user John Doe to connect to the RC server. Global IM UIKit has implemented the display of connection success, connection in progress, and connection failure statuses. Global IM UIKit will automatically reconnect when switching between foreground and background or when network exceptions occur, ensuring connection reliability. Unless the App logic requires logout, manual disconnection is generally not needed.

Call the connection method of the IMLib SDK:

#import <RongIMLibCore/RongIMLibCore.h>

[[RCCoreClient sharedCoreClient] connectWithToken:@"John Doe token" dbOpened:^(RCDBErrorCode code) {
    //Message database opened, 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 service and reconnect
    } else {
        //Unable to connect to the IM server, please handle accordingly based on the error code
    }
}];

Global IM UIKit is a UI component library, and the basic instant messaging capabilities are provided by the IMLib SDK. For example, if the application requires more detailed connection status, you can directly use the RongCoreClient of the IMLib SDK to add a connection status listener. For more details, please refer to the IMLib SDK documentation:

Step 6 Set User Information​

To display user and group avatars, names, etc., on Global IM UIKit, the application layer (App) needs to actively provide user information to Global IM UIKit. To fully experience the UI of Global IM UIKit, we will directly write the corresponding user ID's avatar and name information into the user information database.

Below, we set the avatar and nickname for the local login user John Doe and another user Jane Smith.

[RCIMKitClient shared].enableUserInfoPersistence = YES;

RCUserInfo *currentUserJohnDoe = [[RCUserInfo alloc] initWithUserId:@"userIdJohnDoe" name:@"John Doe" portrait:userPortraitUri];
[RCIMKitClient shared].currentUserInfo = currentUserJohnDoe;

RCUserInfo *JaneSmith = [[RCUserInfo alloc] initWithUserId:@"userIdJaneSmith" name:@"Jane Smith" portrait:@"http://portrait"];
[[RCIMKitClient shared] refreshUserInfoCache:JaneSmith];
tip

It is recommended to dynamically provide user and group avatars, names, etc., when Global IM UIKIt needs to display data. Global IM UIKIt has designed relevant protocols to facilitate the provision of data by the application layer to Global IM UIKIt when the UI needs to display relevant information. You can implement these delegate protocols and set them after initialization but before connection. For details, see User Information.

Step 7 Display Conversation List​

Global IM UIKit provides a default conversation list page and conversation page. The conversation list page displays all one-to-one chats, group chats, and system conversations that the current user participates in. In the conversation page, you can edit, view, reply, and send messages. You can directly initialize the built-in conversation list page RCChatListViewController of Global IM UIKit, or create a subclass by inheritance to build the conversation list page.

After the connection is successful, you can jump to the default conversation list interface. It is recommended that the application inherits the RCChatListViewController in the SDK, such as the TestChatListViewController class, as shown below:

@interface TestChatListViewController : RCChatListViewController

@end

Initialize the custom conversation list page TestChatListViewController. The conversation list supports displaying one-to-one chats, group chats, and system conversations. For detailed usage of the conversation list, see Conversation List Page.

TestChatListViewController *listVC = [[TestChatListViewController alloc] init];

[self.navigationController pushViewController:listVC animated:YES];
tip

The client's conversation list is generated based on local messages. Once a message is stored in the local message database of Global IM UIKit, a new conversation will be generated and displayed on the conversation list page. If there are no messages in the local database, an empty conversation list will be displayed.

Next Steps​

The above steps are the quick integration and beginner experience process of Global IM UIKit. You have experienced the basic IM communication capabilities and UI interfaces. For more detailed introductions, please refer to the subsequent chapters.

  • User Overview: Learn about the user-related services of Global IM UIKit and how Global IM UIKit displays avatars, nicknames, group members, etc.
  • Group Overview: Learn how to use Global IM UIKit to build a group chat experience.
  • Conversation List Page: How to build a conversation list page and customize it.
  • Conversation Page: How to build a conversation page and customize it.
Last updated on