Skip to main content

Quick Start

This tutorial is designed to help beginners quickly get acquainted with RC's Global IM UIKit SDK. In this tutorial, you will experience the basic integration process of the Global IM UIKit SDK and the UI interfaces it provides.

Environment Requirements​

The minimum requirements for Global IM UIKit on Android are:

  • Android 5 (API level 21) or higher

Prerequisites​

  • Register a developer account. Upon 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. 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 production environment App Key for testing and final release.

Demo Project​

RC provides an Android Demo project that showcases the features of Global IM UIKit.

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

Quick Start​

You can implement one-to-one chat, group chat, and receive system conversation messages by integrating the Android version of Global IM UIKit.

Step 1 Create a Project​

First, open Android Studio and create a new project in the Project window as follows:

  1. Click Start a new Android Studio project in the Welcome to Android Studio window.
  2. Select Empty Activity, then click Next.
  3. Enter your project name in the Name field.
  4. Choose your language Java or Kotlin from the language dropdown.
  5. Select a minimum API level of 21 or higher.

Step 2 Import the SDK​

Global IM UIKit supports integration via Maven. Please check the latest version on RC's Maven Repository in advance. Installing Global IM UIKit will automatically integrate the instant messaging capability library.

Gradle​

Please use RC's Maven Repository.

  1. Open the build.gradle file in the root directory (under Project view) and declare RC's Maven repository.

    allprojects {
        repositories {
            ...
            //RC Maven repository URL
            maven {url "https://maven.rongcloud.cn/repository/maven-releases/"}
        }
    }

  2. In the app's build.gradle, add RC's instant messaging UI library (global IM Kit) as a remote dependency.

    dependencies {
    	...
    	//Here, we use the Global IM UIKit library as an example. You can integrate plugins as needed.
    	api 'cn.rongcloud.sdk:global_im_uikit:x.y.z'
    }

    The latest version numbers for each SDK may differ and could be x.y.z.h. Please check RC's Maven Repository for details.

Step 4 Code Obfuscation​

When you build an APK with minifyEnabled true, add the following lines to the module's ProGuard rules file.

-keepattributes Exceptions,InnerClasses

-keepattributes Signature

-keep class io.rong** {*;}
-keep class com.rongcloud.im.uikit** {*;}
-keep class * implements io.rong.imlib.model.MessageContent {*;}

-ignorewarnings

Step 5 Initialize with App Key​

Global IM UIKit relies on the instant messaging capabilities of IMLibCore, which must be initialized before use. Please initialize the SDK in the onCreate() method of the Application, passing in the App Key for either the production or development environment.

public class App extends Application {
    @Override
    public void onCreate() {
        String appKey = "YourAppKey"; // example: bos9p5rlcm2ba
        InitOption initOption = new InitOption.Builder().build();
        RongCoreClient.init(this, appKey, initOption);
    }
}

The initialization configuration (InitOption) encapsulates the area code (AreaCode) 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 pass any configuration, as the SDK defaults to connecting to the Beijing Data Center.
  • If the App Key belongs to an overseas data center, you must pass a valid area code (AreaCode) configuration. Please verify the overseas data center to which the current App Key belongs in the Console, and then find the corresponding enumeration value in AreaCode for configuration.

For example, for an application using the Singapore Data Center's production or development environment App Key:

String appKey = "Singapore_dev_AppKey";
AreaCode areaCode = AreaCode.SG;

InitOption initOption = new InitOption.Builder()
    .setAreaCode(areaCode)
    .build();

RongCoreClient.init(this, appKey, initOption);

The initialization configuration (InitOption) also encapsulates switches for enabling push notifications (enablePush), main process (isMainProcess), and more. Not passing any configuration means using all default settings. For detailed information, refer to the IMLib SDK Documentation · Initialization.

Step 6 Obtain the Current User's 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. The application client must establish an IM connection with RC before using its instant messaging features, and a Token must be passed during the connection.

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

Important

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

Step 7 Connect to RC Server​

On the custom login page, use the token for 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 states. Global IM UIKit will automatically reconnect when switching between foreground and background or when network anomalies occur, ensuring connection reliability. Unless the app logic requires logout, manual disconnection is generally not needed.

Call the IMLib SDK's connection method:

public class LoginActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_login);
        TextView login = findViewById(R.id.login);
        login.setOnClickListener(v -> {
            RongCoreClient.connect("John Doe token", new IRongCoreCallback.ConnectCallback() {
                @Override
                public void onSuccess(String t) {
                    // Login successful, navigate to the default conversation list page.
                }

                @Override
                public void onError(IRongCoreEnum.ConnectionErrorCode e) {

                }

                @Override
                public void onDatabaseOpened(IRongCoreEnum.DatabaseOpenStatus code) {

                }
            });
        });
    }
}

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

Step 8 Set User Information​

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

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

// Allow the SDK to persistently store user information locally
boolean isCacheUserInfo = true;
ConfigCenter.getUserInfoConfig().setUserInfoProvider(userId -> new UserInfo(userId, "John Doe", Uri.parse("userId avatar URL")), isCacheUserInfo);
ConfigCenter.getUserInfoConfig().setUserInfoProvider(userId -> new UserInfo(userId, "Jane Smith", Uri.parse("userId avatar URL")), isCacheUserInfo);
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 interface classes to facilitate the provision of data by the application layer to Global IM UIKIt when the UI needs to display related information. You can implement these interface classes and set them after initialization but before connection. See User Information for details.

Step 9 Display Conversation List​

Global IM UIKit provides a default conversation list page and a conversation page. The conversation list page displays all one-to-one chats, group chats, and system conversations that the current user is participating in. In the conversation page, you can edit, view, reply to, and send messages.

After a successful connection, you can navigate to the default conversation list interface ChatListActivity. For detailed usage of the conversation list, see Conversation List Page.

RouteUtil.routeToChatListActivity(context);
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 is generated and displayed on the conversation list page. If there are no messages in the local database, an empty conversation list will be displayed.

Step 10 Test Sending and Receiving Messages​

You can now run the application on an emulator or a real device.

tip

The default conversation list page and conversation page are based on Activity. Global IM UIKit also supports integrating the conversation list and conversation page into your application's custom Activity in Fragment mode. See Conversation List Page and Conversation Page for details.

Next Steps​

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

  • User Overview: Learn about the user-related services in 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 and customize the conversation list page.
  • Conversation Page: How to build and customize the conversation page.
Last updated on