跳到主要内容

快速上手

本教程旨在帮助开发者快速了解和掌握 IMLib SDK（融云即时通讯能力库）的基础集成流程与核心通信能力。通过本教程，您将完成从 IMLib SDK 导入、初始化、设置监听、建立连接和收发消息等全流程操作。

前置条件​

  • 注册开发者账号。注册成功后，控制台会默认创建您的首个应用，默认生成开发环境下的 App Key，使用国内数据中心。
  • 获取开发环境的应用 App Key。如不使用默认应用，你也可以自己创建应用，并获取对应环境 App Key 和 App Secret。
提示

每个应用具有两个不同的 App Key，分别对应开发环境与生产环境，两个环境之间数据隔离。在您的应用正式上线前，可切换到使用生产环境的 App Key，以便上线前进行测试和最终发布。

Demo 项目​

融云提供了一个不含任何聊天界面的 Demo 项目，集中演示了各个接口的调用方法。

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

安装 SDK​

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

// yarn
yarn add @rongcloud/react-native-im-wrapper

安装完成后，可导入 IMLib 库。

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

初始化 IMLib SDK​

为确保您可以正常连接融云服务器和使用融云即时通讯服务（IM 服务），您须调用 create 方法初始化 IMLib SDK。初始化前，您须在融云控制台中获取 App Key，并设置好 RCIMIWEngineOptions（初始化配置）。详见初始化。 RCIMIWEngineOptions 中封装了 RCIMIWAreaCode （数据中心的区域码），naviServer（导航服务地址）、fileServer（文件服务地址）、statisticServer（数据统计服务地址），enablePush（推送的开关）。详见引擎配置。（注意： RCIMIWAreaCode 跟 naviServer 只设置其中一个即可）。 如果您使用北京数据中心，则不需设置 RCIMIWAreaCode 或者 naviServer ，IMLib SDK 默认连接北京数据中心。

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

监听消息​

通过设置消息接收监听器，用户可接收所有类型的实时消息和离线消息。

  1. message 接收到的消息对象
  2. left 当客户端连接成功后，服务端会将所有补偿消息以消息包的形式下发给客户端，最多每 200 条消息为一个消息包，即一个 Package, 客户端接受到消息包后，会逐条解析并通知应用。left 为当前消息包（Package）里还剩余的消息条数
  3. offline 消息是否离线消息
  4. hasPackage 是否在服务端还存在未下发的消息包
TypeScript

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

连接融云 IM 服务器​

  1. 为模拟用户通过融云 IM 服务器收发消息，您需要首先注册一个用户。在实际业务中，应用客户端通过应用服务端调用融云 IM Server API 获取 token。详见 Server API 文档注册用户。在本教程中，为了快速体验融云服务，您可在控制台「北极星」的 API 调试页面调用获取 Token 接口，获取到 userId 为 1 的用户的 Token。调用返回如下：
HTTP
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"}
  1. 设置连接监听器来实时获取连接状态。您可以将连接状态通过 UI 反馈给用户（例如提示 “网络连接中断” 或 “已重新连接”），提高用户体验。建议在应用生命周期内设置 IM 连接状态监听器，并在不需要的时候移除监听器。详见连接状态监听。
TypeScript

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

  1. 调用 connect 方法，将 userId 为 1 的用户连接融云 IM 服务。注：IMLib SDK 有重连机制，因此一个应用生命周期内调用一次 connect 即可，详见连接。
TypeScript

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

连接成功的回调，onConnected 参数说明：

  • code 连接状态码，0 代表连接成功。
  • userId 连接成功的用户 ID。

发送消息​

TypeScript
let conversationType = RCIMIWConversationType.PRIVATE;
let targetId = 'xxx';
let channelId = 'xxx';
let text = '一条文本消息';
const message: RCIMIWTextMessage = await engine.createTextMessage(
      conversationType,
      targetId,
      channelId,
      text
    );

const callback = {
    onMessageSaved: (message: RCIMIWMessage) => {
        //...
    },
    onMessageSent: (code: number, message: RCIMIWMessage) => {
        //...
    },
};
let code = await engine.sendMessage(message, callback);

退出登录​

TypeScript

let code = await engine.disconnect(receivePush);

引擎销毁​

TypeScript

engine?.destroy();

RCIMIWConnectionStatus

最后于 更新