Getting Started

This tutorial is designed to help beginners quickly understand the RC 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

Create a RC Developer Account and obtain an App Key.

The Console will automatically create an application for new accounts. By default, it uses the Singapore Data Center and provides a development environment. If you already have a RC developer account, you can directly create an application.

Note

• The development and production environments of the same application provide different App Keys, and data is isolated between these two environments.
• The App Secret is used to generate data signatures and is only used when requesting RC server APIs. This tutorial does not cover this. The App Key / Secret of the application is essential for obtaining the credentials to connect to the RC server. Please ensure it is not leaked.

Import SDK

Note

IMLib provides friendly typing support for Typescript users. It is recommended that developers use Typescript for business development to enhance code robustness and maintainability.

NPM Installation (Recommended)

1. Dependency Installation

   npm install @rongcloud/engine@latest @rongcloud/imlib-next@latest -S

2. Code Integration

   // CMD
   const RongIMLib = require('@rongcloud/imlib-next')
   
   // ES
   import * as RongIMLib from '@rongcloud/imlib-next'
   

Script element

<script src="https://cdn.ronghub.com/RongIMLib-5.9.5.prod.js"></script>

Initialization

Before using the capabilities of IMLib, you must call the initialization interface of IMLib, and ensure that this interface is called only once during the entire lifecycle of the application.

The App Key is a prerequisite for using IMLib for instant messaging development and is the unique identifier of the application. You must have the correct App Key to initialize. You can log in to the RC Console to view the App Keys of the applications you have created.

Only when the App Key is the same can messages be exchanged between different users.

// Application initialization to obtain the RongIMLib instance object. Please ensure this process is executed only once.
RongIMLib.init({ appkey: '<Your-App-Key>' });

Set up listeners

After initialization, add event listeners to promptly receive relevant event notifications.

// Add event listeners
const Events = RongIMLib.Events

RongIMLib.addEventListener(Events.CONNECTING, () => {
    console.log('Connecting to the server')
})

RongIMLib.addEventListener(Events.CONNECTED, () => {
    console.log('Connected to the server')
})

RongIMLib.addEventListener(Events.MESSAGES, (evt) => {
    console.log(evt.messages)
})

Obtain User Token

The User Token is an authentication token corresponding to the user ID and is the unique identifier of the application user in RC. The application client must establish an IM connection with RC before using the instant messaging functionality, and the Token must be passed in when connecting.

In actual business operations, the application client needs to call the IM Server API through the application server to apply for a 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"}

Connect to the RC server

Use the Token obtained in the above steps to simulate the user with userId 1 connecting to the RC server.

RongIMLib.connect('<Your-Token>').then(res => {
    if (res.code === RongIMLib.ErrorCode.SUCCESS) {
    console.log('Connection successful, connected user id: ', res.data.userId);
    } else {
    console.warn('Connection failed, code:', res.code)
    }
})

Obtain Conversation List

The web client does not have persistent data storage capabilities and cannot locally store historical message records and conversation lists. Therefore, data needs to be obtained from the RC server. To obtain historical messages for one-to-one and group chats from the remote server, you must enable the Cloud Storage for One-to-One and Group Messages service for the current App Key on the Chat pricing plans page in the Console. This service can be enabled with Chat Premium Plan or Chat Ultimate Plan. For specific features and costs, refer to the Billing Instructions document.

Note

This feature must be executed after calling RongIMLib.connect() and successfully establishing a connection.

IMLib uses the conversationType and targetId properties in the conversation data to identify the uniqueness of the conversation. The definitions of these two properties are as follows:

1. conversationType is used to identify the conversation type (e.g., one-to-one chat, group chat...), and its value is defined by constants in RongIMLib.ConversationType.

2. targetId is used to identify the person or group ID with whom the local end is conversing:

   • When conversationType is RongIMLib.ConversationType.PRIVATE, targetId is the other user's ID.
   • When conversationType is RongIMLib.ConversationType.GROUP, targetId is the current group ID.
   • When conversationType is RongIMLib.ConversationType.CHATROOM, targetId is the chatroom ID.

// Obtain conversation list
RongIMLib.getConversationList().then(({ code, data: conversationList }) => {
  if (code === 0) {
    console.log('Successfully obtained conversation list', conversationList);
  } else {
    console.log('Failed to obtain conversation list: ', error.code, error.msg);
  }
});

Send Message

Note

This feature must be executed after calling RongIMLib.connect() and successfully establishing a connection.

Taking sending a text message as an example:

// Specify the target conversation for message sending
const conversation = {
  // targetId
  targetId: '<TargetId>',
  // Conversation type: RongIMLib.ConversationType.PRIVATE | RongIMLib.ConversationType.GROUP
  conversationType: RongIMLib.ConversationType.PRIVATE
};

// Construct text message
const message = new RongIMLib.TextMessage({ content: 'message content' })

// Send message
RongIMLib.sendMessage(conversation, message).then(({ code, data }) => {
  if (code === 0) {
    console.log('Message sent successfully:', data)
  } else {
    console.log('Message sending failed:', code)
  }
});

Receive Message

When the local end is the message receiver, the received messages will be thrown to the business layer through the message listener registered with RongIMLib.addEventListener and Events.MESSAGES. For details, refer to the Set Up Listeners section above.

Obtain Historical Messages

The web client does not have persistent data storage capabilities and cannot locally store historical message records and conversation lists. Therefore, data needs to be obtained from the RC server. To obtain historical messages for one-to-one and group chats from the remote server, you must enable the Cloud Storage for One-to-One and Group Messages service for the current App Key on the Chat pricing plans page in the Console. This service can be enabled with Chat Premium Plan or Chat Ultimate Plan. For specific features and costs, refer to the Billing Instructions document.

Note

This feature must be executed after calling RongIMLib.connect() and successfully establishing a connection.

const conversation = {
  targetId: '<TargetId>',
  conversationType: RongIMLib.ConversationType.PRIVATE
};
const option = {
  // Timestamp for obtaining historical messages, default is 0, indicating obtaining from the current time
  timestamp: +new Date(),
  // Number of messages to obtain, valid value 1-100, default is 20
  count: 20,
};
RongIMLib.getHistoryMessages(conversation, option).then(result => {
  const list = result.data.list;       // Obtained message list
  const hasMore = result.data.hasMore; // Whether there are more historical messages to obtain
  console.log('Successfully obtained historical messages', list, hasMore);
}).catch(error => {
  console.log('Failed to obtain historical messages', error.code, error.msg);
});

Disconnect

Note

Disconnect the current user. After disconnection, you cannot receive messages, send messages, obtain historical messages, or obtain conversation lists... Upon the next successful connection to RC, messages received since the last offline will be retrieved. Offline messages are saved by default for 7 days.

RongIMLib.disconnect().then(() => console.log('Disconnected successfully'));

Next Steps

The above steps cover the quick integration and beginner experience process of the IMLib SDK. You have experienced basic IM communication capabilities and the UI interface. For more detailed explanations, please refer to the subsequent chapters.