Quick Start

Global IM UIKit is developed based on the IMLib SDK, providing UI interfaces for conversations and messages on top of the IMLib SDK. It can be used to quickly implement the construction of a web chat interface. Global IM UIKit offers easy-to-use building components and UI interactions.

This tutorial introduces the basic process of quickly integrating Global IM UIKit and the UI interfaces it provides.

Browser Compatibility

Chrome	Safari	Edge	WeChat Browser
68 +	13 +	100 +	×

tip

Currently, only Chrome, Safari, and Edge browsers are supported. UI compatibility for mobile H5 browsers in portrait mode is not yet available.

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. 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.

tip
Each application has two different App Keys, corresponding to the Development and Production environments, respectively. Data is isolated between these two environments. Before your application goes live, you can switch to using the App Key for the Production environment for final testing and release.

Demo Project

RC provides a web-side Demo project that showcases the features of Global IM UIKit.

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

tip

Global IM UIKit is not yet adapted for H5 mobile devices in portrait mode.
Currently, only one-to-one chat, group chat, and system conversation types are supported. Chatroom and ultra group conversations are not yet supported.
IMLib v4 Adapter and IMLib v2 Adapter are not supported.

Install Dependencies

To install Global IM UIKit, you need to integrate the instant messaging capability library, IMLib SDK.

NPM

It is recommended to install the Global IM UIKit SDK via a package manager for better IDE syntax support and development experience.

# Install IMLib
npm install @rongcloud/engine @rongcloud/imlib-next --save
# Install Global IM UIKit
npm install @rongcloud/global-im-uikit --save


@rongcloud/engine
@rongcloud/imlib-next@latest
@rongcloud/global-im-uikit

CDN Files

If you prefer not to install the Global IM UIKit SDK via a package manager, you can also include it via CDN. However, this method does not support IDE syntax hints.

<!-- Include IMLib -->
<script src="https://cdn.ronghub.com/RongIMLib-5.9.5.prod.js"></script>
<!-- Include Global IM UIKit -->
<script src="https://cdn.ronghub.com/RCIMKit-1.0.0.prod.js"></script>

Special Configuration for Vue Projects

Since Global IM UIKit uses Web Components to define custom UI components, and Vue prioritizes treating any non-native HTML tags as Vue components, you need to configure your Vue project when using build tools like Vite or Vue-cli to ensure proper compilation.

All internal standard components in the SDK start with rc-.

vite

// vite.config.js
import vue from '@vitejs/plugin-vue'

export default {
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: tag => tag.startsWith('rc-'),
        }
      }
    })
  ]
}

vue-cli

// vue.config.js
module.exports = {
  chainWebpack: config => {
    config.module
      .rule('vue')
      .use('vue-loader')
      .tap(options => ({
        ...options,
        compilerOptions: {
          isCustomElement: tag => tag.startsWith('rc-')
        }
      }))
  }
}

Webpack

// webpack.config.js
module: {
    rules: [
    {
      test: /\.vue$/,
      loader: "vue-loader",
      options: {
        compilerOptions: {
          isCustomElement: tag => tag.startsWith("rc-"),
        },
      },
    },
  ]
}

Initialization

Global IM UIKit relies on the instant messaging capabilities of the IMLib SDK. Therefore, you need to complete the initialization of both the IMLib SDK and Global IM UIKit in sequence.

Initialize the IMLib SDK

The App Key is the unique identifier of your RC application. Please pass in the App Key for your application's Production or Development environment.

import * as RongIMLib from '@rongcloud/imlib-next';
// You can also reference IMLib as follows. For easier understanding of the documentation examples, we use import * as RongIMLib here.
// import { init } from '@rongcloud/imlib-next';

// Initialize IMLib
RongIMLib.init({ appkey: '<YOUR-APP-KEY>' });

The initialization configuration of the IMLib SDK ([IInitOption]) encapsulates configurations such as the area code (AreaCode). The IMLib SDK will obtain valid navigation service addresses, file service addresses, data statistics service addresses, and log service addresses based on the area code.

If the App Key belongs to the China (Beijing) Data Center, you do not need to pass any configuration. The SDK will connect to the Beijing Data Center by default.
If the App Key does not belong to the China (Beijing) Data Center, you must pass a valid area code ([AreaCode]) based on the data center of your application. Example area code values: AreaCode.SG (Singapore), AreaCode.NA (North America).

Initialize Global IM UIKit

Implement the Hooks for Global IM UIKit. To display user avatars and nicknames, group and member avatars, names, etc., on Global IM UIKit, the application layer (App) must actively provide user information to Global IM UIKit. Therefore, when initializing Global IM UIKit, you need to implement the necessary hook functions (Hooks) as required by Global IM UIKit.

The following example only shows the necessary hook function implementation. For more hook functions, please refer to the Hooks documentation.

// To help developers understand the parameters and return values of the hook functions, TypeScript is used here for the example.
const hooks: IRCKitServiceHooks = {
  // Define the method for obtaining user profiles
  async reqUserProfiles(userIds: string[]): Promise<IRCKitUserProfile[]> {
    // userIds is a list of user IDs. The business layer needs to provide corresponding user information based on userIds.
    return userIds.map((userId) => ({
      userId,
      name: '', // User name, please pass a valid value; otherwise, it will affect the display of user information.
      portraitUri: '', // User avatar, please pass a valid value. If the avatar fails to load or is not provided, the SDK will use a default avatar.
    }));
  },

  // Define the method for obtaining group profiles
  async reqGroupProfiles(groupIds: string[]): Promise<IRCKitGroupProfile[]> {
    // groupIds is a list of group IDs. The business layer needs to provide corresponding group information based on groupIds.
    return groupIds.map((groupId) => ({
      groupId,
      name: '', // Group name, please pass a valid value; otherwise, it will affect the display of group information.
      memberCount: 0, // Group member count, please pass a valid value; otherwise, it will affect the display of group information.
      portraitUri: '', // Group avatar, please pass a valid value. If the avatar fails to load or is not provided, the SDK will use a default avatar.
    }));
  },

  // Define the method for obtaining group member profiles
  async reqGroupMembers(groupId: string): Promise<IRCKitGroupMemberProfile[]> {
    // groupId is the group ID. The business layer needs to provide corresponding group member information based on groupId.
    return [
      // The business layer needs to provide the real member information of the group, where nickname is optional.
      // If nickname is empty, the SDK will use the name field from the user information obtained via reqUserProfiles as the group member's nickname.
      // For performance considerations, it is recommended that the business layer provide the real nicknames of group members to avoid multiple calls to the reqUserProfiles method within the SDK.
      { userId: 'user-01', nickname: '' },
      { userId: 'user-02' }
    ]
  },

  // Define the method for obtaining system conversation profiles
  async reqSystemProfiles(systemIds: string[]): Promise<IRCKitSystemProfile[]> {
    // systemIds is a list of system conversation IDs. The business layer needs to provide corresponding system conversation information based on systemIds.
    return systemIds.map((systemId) => ({
      systemId,
      name: '', // System conversation name, please pass a valid value; otherwise, it will affect the display of system conversation information.
      portraitUri: '', // System conversation avatar, please pass a valid value. If the avatar fails to load or is not provided, the SDK will use a default avatar.
    }));
  },
}

Initialize Global IM UIKit and pass the hooks as a parameter.

import * as RCIMKit from '@rongcloud/global-im-uikit';
// You can also reference Global IM UIKit as follows. For easier understanding of the documentation examples, we use import * as RCIMKit here.
// import { RCKitInstaller } from '@rongcloud/global-im-uikit';

// Initialize Global IM UIKit and pass the hooks as a parameter
const kitApp = RongIMLib.installPlugin(RCIMKit.RCKitInstaller, { hooks })

Parameter	Type	Required	Description
hooks	[IRCKitServiceHooks]	Yes	Hook function definitions, used to obtain user information from the business layer when necessary.
logLevel	[LogL]	No	Log output level, default value `LogL.WARN(2)`.
language	String	No	Initial language configuration, default value `en_US`. Valid values: `en_US`, `zh_CN`. If you have custom language requirements, you can define a custom language identifier as the initial language. For details, refer to Multilingual.
allowedToRecallTime	number	No	The maximum time allowed to recall a sent message, in seconds. If not passed or the value is invalid, the default is 120 seconds.
allowedToReEditTime	number	No	The maximum time allowed to re-edit a recalled message, in seconds. If not passed or the value is invalid, the default is 60 seconds.
modalContainerId	String	No	The SDK has built-in various modal UIs. If this parameter is not passed, the SDK will use `document.body` as the modal container.

Pass the Global IM UIKit global configuration. Global IM UIKit provides various configuration options to allow customization based on business needs, such as defining the on/off state of certain features, customizing conversation or message menus, and extending custom language packs.

All configuration items need to be completed before calling kitApp.ready(), and kitApp.ready() is used to notify Global IM UIKit to end the configuration and start injecting custom tags into the browser.
```
// After completing various configurations, call the ready method to notify the SDK to end the configuration and start injecting custom tags into the browser.
kitApp.ready();
```

tip

After the configuration is completed, the related configuration interfaces will no longer take effect.

Obtain the Current User Token

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

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) and pass the user identifier (userId) assigned by your application to exchange for the Token. The application client can request the Token from the application server before connecting.

Establish an IM Connection

On the custom login page, use the token of user John Joe 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 abnormalities occur, ensuring connection reliability. Unless the App logic requires logout, manual disconnection is generally not needed.

Global IM UIKit is a UI component library, with the instant messaging capabilities provided by the IMLib SDK. The following steps will call methods provided by the IMLib SDK.

Before starting the IM connection, you need to add listeners for IMLib connection-related events to respond accordingly when the connection state changes.

RongIMLib.addEventListener(RongIMLib.Events.CONNECTED, () => {
  console.log('Connection successful');
});
RongIMLib.addEventListener(RongIMLib.Events.DISCONNECT, (code) => {
  console.log('Connection disconnected, error code:', code);
});
RongIMLib.addEventListener(RongIMLib.Events.SUSPEND, (code) => {
  console.log('Connection interrupted, waiting for automatic reconnection to restore, error code:', code);
});
RongIMLib.addEventListener(RongIMLib.Events.CONNECTING, () => {
  console.log('Connecting');
});

Use the Token obtained in the previous steps to connect to the IM server.

const { code, data } = await RongIMLib.connect('<TOKEN>');

if (code === RongIMLib.ErrorCode.SUCCESS) {
  // After successful IM connection, you can add UI tags to the DOM to display the chat interface.
  console.log('Connection successful, user ID:', data.userId);
} else {
  console.log('Connection failed, error code:', code);
}

For more details, please refer to the IMLib SDK documentation:

UI Interface

After calling kitApp.ready(), the SDK will register various Web Components custom tag components in the browser, with the main component being the <rc-imkit-app-provider/> component.

After a successful IM connection, you can add this component to the DOM to display the chat interface.

const appElement = document.createElement('rc-imkit-app-provider');
// Define the component's width and height
appElement.style.width = '100%';
appElement.style.height = '100%';
// Add the component to the DOM
document.body.appendChild(appElement);

tip

The image below is a reference design and not the default implementation of

IMLib

Global Chat UIKit

push notification

IMLib

Global Chat UIKit

Chat Server

Chat Server SDK

Quick Start

Browser Compatibility​

Prerequisites​

Demo Project​

Install Dependencies​

NPM​

CDN Files​

Special Configuration for Vue Projects​

vite​

vue-cli​

Webpack​

Initialization​

Initialize the IMLib SDK​

Initialize Global IM UIKit​

Obtain the Current User Token​

Establish an IM Connection​

UI Interface​