Skip to main content

Quick Start

This tutorial is designed to help beginners quickly get acquainted with RC's Instant Messaging capability 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 China (Beijing) Data Center.

  • Obtain the application 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 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 officially goes live, you can switch to using the production environment App Key for testing and final release.

You need to record the application App Key shown above for use in this tutorial.

The application's App Key / Secret is a necessary condition for obtaining the identity credentials to connect to the RC server. Please ensure it is not leaked.

Demo Project​

RC provides a Demo project without any chat UI, which demonstrates the calling methods of various interfaces.

https://github.com/rongcloud/rongcloud-react-native-im-wrapper

Install SDK​

npm install @rongcloud/react-native-im-wrapper

After installation, you can import the IMLib library.

import { RCIMIWEngine, RCIMIWEngineOptions } from '@rongcloud/react-native-im-wrapper';

Initialize​

Before using all the features of the SDK, you must call this method to initialize the SDK.

During initialization, you need to pass in the App Key obtained above. For engine configuration, please refer to Engine Configuration.

let options: RCIMIWEngineOptions = {};
let engine: RCIMIWEngine = RCIMIWEngine.create(appKey, options);

The above provides a simplified initialization example. For more configuration details on initialization, please refer to Initialization.

Obtain User Token​

The user Token is an authentication token corresponding to the user ID and serves as the unique identity identifier for the application's users 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's server to apply for a Token. For details, see 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. Use onConnectionStatusChanged to listen for changes in the IM connection status. When the connection status changes, it returns [RCIMIWConnectionStatus]. For details, see Connection Status Listener.

  2. Set the listener to obtain the connection status:


engine?.setOnConnectionStatusChangedListener((status: RCIMIWConnectionStatus) => {
    //...
});

  1. Use the Token obtained above to simulate a connection to the RC server for the user with userId 1.

const callback = {
    onDatabaseOpened: (code: number) => {
        //...
    },
    onConnected: (code: number, userId: string) => {
        //...
    },
};
let code = await engine.connect(token, timeout, callback);

The callback for a successful connection, onConnected parameter description:

  • code Connection status code, 0 indicates a successful connection.
  • userId The user ID of the successfully connected user.

The SDK has implemented an automatic reconnection mechanism. Please refer to Connection.

Listen for Messages​

To implement this feature, developers need to implement a message listener callback.

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

  1. message The received message object
  2. left After the client successfully connects, the server will send all compensation messages to the client in the form of message packages, with a maximum of 200 messages per package. After receiving the message package, the client will parse it one by one and notify the application. left indicates the number of messages remaining in the current message package (Package).
  3. offline Whether the message is an offline message
  4. hasPackage Whether there are still undelivered message packages on the server

engine?.setOnMessageReceivedListener((message: RCIMIWMessage, left: number, offline: boolean, hasPackage: boolean) => {
    //...
});

Send Message​

let conversationType = RCIMIWConversationType.PRIVATE;
let targetId = 'xxx';
let channelId = 'xxx';
let text = 'A text message';
engine.createTextMessage(
  conversationType,
  targetId,
  channelId,
  text
)
.then((message: RCIMIWTextMessage) => {
  engine.sendMessage(message);
});

Logout​


let code = await engine.disconnect(receivePush);

Destroy Engine​


engine?.destroy();

RCIMIWConnectionStatus

Last updated on