跳到主要内容
版本：5.X

超级群快速上手

本教程是为了让新手快速了解融云即时通讯能力库（IMLib）。在本教程中，你可以体验集成 SDK 的基本流程和 IMLib 的超级群通信能力。

融云开发者账户​

融云开发者账户是使用融云 SDK 产品的必要条件。在开始之前，请先前往融云官网注册开发者账户。注册后，控制台将自动为你创建一个应用，默认为开发环境应用，使用国内数据中心。请获取该应用的 App Key，在本教程中使用。

注意

App Secret 用于生成数据签名，仅在请求融云服务端 API 接口时使用。本教程中暂不涉及。

如果您已拥有融云开发者账户，你可以直接选择合适的环境，创建应用。

您需要记录应用的 App Key，在本教程中使用。

应用的 AppKey 与 Secret 是获取连接融云服务器身份凭证的必要条件，请注意不要泄露。

导入 SDK​

注意

IMLib 对 Typescript 的使用者提供了友好的类型化支持，推荐开发者使用 Typescript 进行业务开发以提升代码健壮性及可维护性。

NPM 引入（推荐）

  1. 依赖安装

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

  2. 代码集成

    javascript
    // 非 ESModule
    const RongIMLib = require('@rongcloud/imlib-next')
    // ESModule
    import * as RongIMLib from '@rongcloud/imlib-next'

CDN 引入

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

App Key​

App Key 是使用 IMLib 进行即时通讯功能开发的必要条件，也是应用的唯一性标识。在集成使用 IMLib 之前，请务必先通过控制台注册并获取开发者的专属 App Key。

只有在 App Key 相同的情况下，不同用户之间的消息才能互通。

初始化​

在使用 IMLib 的能力之前，必须先调用 IMLib 的初始化接口，且务必保证该接口在应用全生命周期内仅被调用一次。

typescript
// 应用初始化以获取 RongIMLib 实例对象，请务必保证此过程只被执行一次
RongIMLib.init({ appkey: '<Your-App-Key>' })

设置监听​

初始化完成后，添加事件监听器，及时获取相关事件通知。IM 在初次连接成功后，需立即同步消息，获取全量超级群会话列表，列表同步完成前，所有超级群相关功能接口不可用

javascript
// 添加事件监听
const Events = RongIMLib.Events

RongIMLib.addEventListener(Events.CONNECTING, () => {
  console.log('正在连接服务器')
})

RongIMLib.addEventListener(Events.CONNECTED, () => {
  console.log('已经连接到服务器')
})

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

// 会话列表同步完成，可通过监听 Events.ULTRA_GROUP_ENABLE 事件以通知业务层会话列表同步完成
RongIMLib.addEventListener(Events.ULTRA_GROUP_ENABLE, () => {
  // 5.20.0 版本开始，回调不再提供会话列表数据
  console.log('超级群会话列表同步完成')
})

// 会话状态变动监听 包含：会话未读数、@ 未读数、免打扰状态
RongIMLib.addEventListener(Events.CONVERSATION, ({ conversationList }) => {
  console.log(conversationList)
})

建立 IM 连接​

App Key 是应用的唯一性标识，Token 则是用户的唯一性标识，是用户连接融云 IM 服务所必需的身份凭证。Token 一般由开发者的应用服务器调用融云 Server API 获取 Token 接口获取之后，由应用服务器下发到应用客户端。

注意

以下示例代码假定客户端已获取 Token

javascript
RongIMLib.connect('<Your-Token>').then((res) => {
  if (res.code === RongIMLib.ErrorCode.SUCCESS) {
    console.log('连接成功, 连接用户 id 为: ', res.data.userId)
  } else {
    console.warn('连接失败, code:', res.code)
  }
})

获取所有超级群会话列表​

注意

Web 端不具备持久化的数据存储能力，需要开发者开启超级群消息云端存储功能才能生效。 该功能需要在调用 RongIMLib.connect() 并且建立连接成功之后执行。

IMLib 通过会话数据中的 conversationType 与 targetId 与 channelId 三个属性值来标识会话的唯一性，对于三个属性的定义如下：

  1. conversationType 用来标识会话类型（如：超级群...），其值为 RongIMLib.ConversationType 中的常量定义
  2. targetId 用来标识与本端进行对话的超级群会话 Id：

  • 当 conversationType 值为 RongIMLib.ConversationType.ULTRA_GROUP，targetId 为对方超级群会话 Id

    javascript
    // 获取超级群会话列表
    RongIMLib.getUltraGroupList().then(({ code, data: conversationList }) => {
      if (code === 0) {
        console.log('获取超级群会话列表', conversationList)
      } else {
        console.log('获取超级群会话列表: ', error.code, error.msg)
      }
    })

发送消息​

注意

该功能需要在调用 RongIMLib.connect() 并且建立连接成功之后执行。

以发送文本消息为例：

javascript
// 指定消息发送的目标会话
const conversation = {
  // targetId
  targetId: '<TargetId>',
  // 会话类型：RongIMLib.ConversationType.ULTRA_GROUP
  conversationType: RongIMLib.ConversationType.ULTRA_GROUP,
  // 频道 ID
  channelId: '<频道 ID>',
}

// 构建文本消息
const message = new RongIMLib.TextMessage({ content: 'message content' })

// 发送消息
RongIMLib.sendMessage(conversation, message).then(({ code, data }) => {
  if (code === 0) {
    console.log('消息发送成功：', data)
  } else {
    console.log('消息发送失败：', code)
  }
})

接收消息​

当本端作为消息接收的一方，所接收的消息将通过 RongIMLib.addEventListener 和 Events.MESSAGES 注册的消息监听向业务层抛出。具体可参考上述 设置监听 部分

获取历史消息​

注意

Web 端不具备持久化的数据存储能力，需要开发者开启超级群消息云端存储（参见开通超级群服务）功能才能生效。 该功能需要在调用 RongIMLib.connect() 并且建立连接成功之后执行。

javascript
const conversation = {
  targetId: '<TargetId>',
  conversationType: RongIMLib.ConversationType.ULTRA_GROUP,
  channelId: '<频道ID>',
}
const option = {
  // 获取历史消息的时间戳，默认为 0，表示从当前时间获取
  timestamp: +new Date(),
  // 获取条数，有效值 1-100，默认为 20
  count: 20,
}
RongIMLib.getHistoryMessages(conversation, option)
  .then((result) => {
    const list = result.list // 获取到的消息列表
    const hasMore = result.hasMore // 是否还有历史消息可获取
    console.log('获取历史消息成功', list, hasMore)
  })
  .catch((error) => {
    console.log('发送文字消息失败', error.code, error.msg)
  })

断开连接​

注意

断开当前用户连接，连接断开后无法接收消息、发送消息、获取历史消息、获取会话列表... 在下次连接融云成功后，会收取上次离线后的消息，离线消息默认保存 7 天。

javascript
RongIMLib.disconnect().then(() => console.log('断开连接成功'))

后续步骤​

以上步骤即 IMLib SDK 的快速集成与新手体验流程，您体验了基础 IM 通信能力，更多详细介绍请参考后续各章节详细说明。

最后于 更新