Skip to main content

Quick Start

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

Prerequisites​

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

  • Obtain the App Key for the development environment from the App Key page. If you're not using the default application, refer to How to Create an Application and Obtain the Corresponding 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. Before your application goes live, you can switch to using the production environment App Key for testing and final release.

Environment Requirements​

  • (SDK ≧ 5.6.3) Requires Android 5.0 (API 21) or higher
  • (SDK < 5.6.3) Requires Android 4.4 (API 19) or higher

Start Integration​

IMLib supports integration via Maven. Please check the latest version on the RC's Maven Repository.

Import SDK​

This tutorial demonstrates adding remote dependencies in Gradle to import the IMLib SDK into your application project. Make sure to 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 your app's build.gradle, add RC's Instant Messaging Library (IMLib) as a remote dependency.

    dependencies {
    	...
    	// Here, we use IMLib as an example
    	api 'cn.rongcloud.sdk:im_lib:x.y.z'
    }
    tip

    The latest version numbers for each SDK may differ and could be x.y.z.h. Check the RC's Maven Repository for updates.

For other ways to import the SDK, refer to Import SDK.

Initialize SDK​

The core classes of RC's Instant Messaging Client SDK are RongCoreClient and RongIMClient. In the onCreate() method of your Application, call the initialization method of RongCoreClient, passing the App Key for either the production or development environment.

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

String appKey = "Your_AppKey"; // example: bos9p5rlcm2ba
InitOption initOption = new InitOption.Builder().build();

RongCoreClient.init(getApplicationContext(), appKey, initOption);

The initialization configuration (InitOption) encapsulates the area code (AreaCode), navigation service address (naviServer), file service address (fileServer), data statistics service address (statisticServer), and the push notification switch (enablePush) and main process switch (isMainProcess). Not passing any configuration means using all default settings. The SDK connects to the China (Beijing) Data Center by default.

If the App Key does not belong to the China (Beijing) Data Center, you must pass valid initialization configurations. For detailed initialization instructions, refer to Initialization.

Obtain User Token​

The user Token is an authentication token corresponding to the user ID and serves 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 during the connection.

In actual business operations, the application client needs to call the IM Server API through the application server to obtain the Token. Refer to the Server API documentation Register User.

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

Establish IM Connection​

  1. Monitor changes in the IM connection status to provide user prompts on the UI and enhance the experience. It is recommended to set this up within the application lifecycle. To avoid memory leaks, remove the listener when it's no longer needed. Refer to Connection Status Monitoring.

    private IRongCoreListener.ConnectionStatusListener connectionStatusListener = new IRongCoreListener.ConnectionStatusListener() {
      @Override
      public void onChanged(ConnectionStatus status) {
            // Developers should handle different business logic based on the connection status code
      }
    };
    public void setIMStatusListener() {
        // Add connection status listener since 5.1.6
        RongCoreClient.addConnectionStatusListener(ConnectionStatusListener);
    }

  2. Use the Token obtained in the previous steps to simulate the connection of the user with userId 1 to the RC server.

    String token = "User Token";
    RongCoreClient.connect(token, new IRongCoreCallback.ConnectCallback() {
        /**
         * Database callback.
         * @param code Database open status. DATABASE_OPEN_SUCCESS indicates success; DATABASE_OPEN_ERROR indicates failure
         */
        @Override
        public void OnDatabaseOpened(IRongCoreEnum.DatabaseOpenStatus code) {

        }
        /**
         * Success callback
         * @param userId Current user ID
         */
        @Override
        public void onSuccess(String userId) {

        }
        /**
         * Error callback
         * @param errorCode Error code
         */
        @Override
        public void onError(IRongCoreEnum.ConnectionErrorCode errorCode) {

        }
    });

The SDK has implemented an automatic reconnection mechanism. Refer to Connection.

Listen for Messages​

Set up a message reception listener to receive all types of real-time or offline messages.

RongCoreClient.addOnReceiveMessageListener(
    new io.rong.imlib.listener.OnReceiveMessageWrapperListener() {
        @Override
        public void onReceivedMessage(Message message, ReceivedProfile profile) {
            // When receiving offline messages, the server packages 200 messages into a single bundle sent to the client. This parameter indicates the remaining number of messages after the bundle is parsed.
            int left = profile.getLeft();
            // Whether the message is offline
            boolean isOffline = profile.isOffline();
            // Whether there are still undelivered message bundles on the server
            boolean hasPackage = profile.hasPackage();
        }
    }
);

Send a Message​

Send a message to the user with userId 2.

String content = "Hello, this is a message from user 1";
String targetId = "2";
ConversationType conversationType = ConversationType.PRIVATE;
// Construct the message
TextMessage messageContent = TextMessage.obtain(content);
Message message = Message.obtain(targetId, conversationType, messageContent);

// Send the message
RongCoreClient.getInstance().sendMessage(message, null, null, new IRongCoreCallback.ISendMessageCallback() {
    @Override
    public void onAttached(Message message) {

    }

    @Override
    public void onSuccess(Message message) {

    }

    @Override
    public void onError(Message message, IRongCoreEnum.ErrorCode errorCode) {

    }
});

Last updated on