# livechatroom-example

**Repository Path**: huangfeipeng1998/livechatroom-example

## Basic Information

- **Project Name**: livechatroom-example
- **Description**: 移动端直播聊天室页面通过环信SDK实现聊天等功能。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-11-20
- **Last Updated**: 2024-11-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 环信SDK集成搭建聊天室项目指导文档
## 1. 运行示例项目
1. 安装依赖并运行
```shell
pnpm i
````

```shell
pnpm run dev
```

2. 打开页面
> 页面效果
<img src="./src/assets/images/iShot_2024-11-20_13.43.08.png" alt="chat" width="300px" height="500px">
>

3. 输入账号密码登录
> 已经预先注册了测试账号：`username：hfp2 password：1 / usernmae：hfp1 password：1`

4. 点击进入聊天室
> 点击cell环信聊天室实现演示，跳转即进入聊天室页面，底部输入框可直接输入文字发送消息，点击发送按钮发送消息。

5. 收发测试方式
> 复制一个Tab页面，输入另一个测试账号密码，与上文相同的步骤进入聊天页面，发送消息，观察另一个Tab页面是否收到消息。
## 示例项目核心代码所在位置
1. 环信SDK集成演示代码
- [集成&实例化](./src/easemob/index.ts)

- [连接监听](./src/easemob/emListener/emConnectListener.ts)

> 最终在App.vue中通过`import "./easemob"`导入实例化动作的的文件。
2. 聊天室页面代码
- [聊天室页面](./src/pages/live-chatroom/index.vue)

## 2. 集成环信SDK
### 核心文档地址
#### Web平台
- [集成文档](https://doc.easemob.com/document/web/import_sdk_minicore.html)
- [聊天室相关](https://doc.easemob.com/document/web/room_overview.html)
- [小程序相关](https://doc.easemob.com/document/applet/room_overview.html)

#### 服务端平台
服务端参与的意义？
1. 服务端需要承担注册用户体系的功能，包括环信用户注册、获取用户Token、删除、查询用户信息等。
2. 服务端需要承担聊天室的创建、删除、更新聊天室信息等功能。
3. 服务端可以通过环信IM的API实现聊天室内订单消息发送等功能。

服务端API文档：

[RestAPI文档](https://doc.easemob.com/document/server-side/enable_and_configure_IM.html)
[JavaSDK文档](https://doc.easemob.com/document/server-side/java_server_sdk_2.0.html)

### Web平台（H5&小程序通用）SDK集成详细步骤
1. 下载环信SDK
PC Web或者H5推荐npm形式安装，npm包如下：

```shell
npm i easemob-websdk
```
小程序推荐下载js包形式，下载方式如下：

[下载地址](https://github.com/easemob/webim-weixin-xcx/blob/master/src/sdk/Easemob-chat-4.10.0.js)

2. 导入环信SDK
- 这一步是为了导入环信相关依赖API包，为后续建立连接以及各种API使用做前置工作。
> 导入方式见上文示例项目核心代码所在位置,或直接参考上文Web平台文档。
3. 配置环信SDK
- 这一步是为了配置环信SDK所必须得appKey参数，并将SDK进行实例化，实例化后的`conn`或者`EMClient`即为后续使用的核心对象。
>核心必须实例化时传入`appKey`
```js
const conn = new EC.connection({
  appKey: "your appKey",
});
```
[点击参考文档](https://doc.easemob.com/document/web/overview.html#sdk-%E5%88%9D%E5%A7%8B%E5%8C%96)

5. 注册所需插件（小程序可忽略）
- 这一步是为了注册所需功能的插件包。
[点击参考文档](https://doc.easemob.com/document/web/import_sdk_minicore.html#_3-%E6%B3%A8%E5%86%8C%E6%A8%A1%E5%9D%97%E5%88%B0-minicore)

6. 挂载连接监听回调

- 这一步是为了挂载连接监听回调，监听连接状态变化。
> 核心监听回调见上文示例项目核心代码所在[位置](./src/easemob/emListener/emConnectListener.ts),或直接参考上文Web平台文档。

7. 挂载其他监听回调消息，聊天室事件等监听回调。
- 这一步是为了挂载消息监听以及聊天室事件监听，为接收消息以及聊天室事件做出逻辑处理做准备。
```js
EMClient.addEventHandler('handleId',{
  // 监听消息事件
  onTextMessage: (message) => {
    console.log("onMessage", message);
  },
  onImageMessage: (message) => {
    console.log("onImageMessage", message);
  },
  // ....
  // 监听聊天室事件
  onChatroomEvent: (event) => {
    console.log("onChatRoomEvent", event);
  },
});
```
8. 连接环信服务器

- 这一步是为了连接环信服务器，连接成功后即可进行后续操作。
```js
// 连接环信服务器
EMClient.open({
  username:'your username',
  password:'your password'
});
```
>有效执行后会触发`onConnected`监听回调。

9. 加入聊天室
- 这一步是为了加入聊天室，加入成功后即可进行后续操作，如向聊天室内发送弹幕，或者拉取加入聊天室之前的历史消息。
```js
// 加入聊天室
EMClient.chatroom.joinChatRoom({
  roomId: 'your roomId',
    // 加入聊天室时携带的扩展信息,如用户的昵称，头像等。
    ext: 'custom ext',
})
```
10. 获取聊天室历史消息
- 这一步是为了获取聊天室历史消息，如加入直播间为气氛考虑加入即展示部分弹幕。
```js
// 获取聊天室历史消息
EMClient.contact.getHistoryMessages({
  targetId: 'targetId', // 聊天室=ID。
  chatType: 'chatRoom', // 会话类型：单聊、群组聊天和聊天室分别为 `singleChat`、`groupChat` 和 `chatRoom`。
  pageSize: 20, // 每次获取的消息数量，取值范围为 [1,50]，默认值为 `20`。
  searchDirection: 'up', // 消息搜索方向。`up` 表示按消息时间戳递减的方向获取，即先获取最新消息；
})
```
11. 发送消息
- 这一步是为了发送消息，如发送弹幕。
```js
 const options = {
      to: 'your roomId', // 发送目标 ID，即聊天室 ID。
      msg: 'your message content',// 消息内容
      chatType: "chatRoom", // 聊天类型 聊天室即为`chatRoom`
      type: "txt", //消息类型
    };
 const msg = EMClient.Message.create(options)
 EMClient.send(msg)
```
12. 退出聊天室
- 这一步是为了退出聊天室，退出成功后即可进行后续操作，如关闭聊天室页面。
```js
// 退出聊天室
EMClient.chatroom.leaveChatRoom({
  roomId: 'your roomId', // 聊天室 ID。
})

```

13. 关闭连接
- 这一步是为了关闭连接，离开聊天室后并关闭聊天室页面前可执行此操作。
```js
// 关闭连接
EMClient.close()
```
>这一步会触发`onDisconnected`监听回调。

## 常见问题
- 1. 登录连接失败
  - 1.1 检查appKey是否正确
  - 1.2 检查是否已经注册用户
  - 1.3 检查登录token是否正确

- 2. 发送消息失败
  - 2.1 检查是否已经加入聊天室
  - 2.2 检查构建消息的参数是否正确

- 3. 收不到聊天室消息
  - 3.1 检查是否已经加入聊天室
  - 3.2 检查是否已经挂载消息监听回调
  - 3.3 检查登录连接状态是否正常
- 4. 网路连接问题
  - 4.1 网络连接断开，SDK内会进行默认5次重连，重连完全失败后会触发`onDisconnected`监听回调，网络变化也会引起SDK的重连，并会在用户发送消息时也会触发重连
- 5. 其他问题
  - 4.1 聊天室内收到不属于当前聊天室的消息，可检查是否退出了之前加入的聊天室，并在消息监听处增加当前加入的聊天室id判断
  - 4.2 日志收集，在线上问题追踪时，可以将日志收集到服务端，方便排查问题，具体开启需要提供appKey，联系商务同事进行开启，小程序日志开启则需要在小程序中实例化部分增加`enableReportLogs:true`参数。
  - 4.3 聊天室漫游拉取失败，漫游需要主动开通，且需要在单独开启聊天室漫游配置项，具体开通事宜可联系商务同事进行开启。
## 特别说明
>对于聊天室消息，环信即时通讯提供消息分级功能，将消息的优先级划分为高、普通和低三种级别，高优先级的消息会优先送达。你可以在创建消息时对指定聊天室消息类型或指定成员的消息设置为高优先级，确保这些消息优先送达。这种方式确保在聊天室内消息并发量很大或消息发送频率过高时，重要消息能够优先送达，从而提升重要消息的可靠性。 当服务器的负载较高时，会优先丢弃低优先级的消息，将资源留给高优先级的消息。不过，消息分级功能只确保消息优先到达，并不保证必达。服务器负载过高的情况下，即使是高优先级消息依然会被丢弃。
1. 服务端设置消息优先级
>构建消息体时在消息体内传入`chatroom_msg_level`字段，值为`high`，代表高优先级消息。
- [点击参考文档](https://doc.easemob.com/document/server-side/message_chatroom.html#http-%E8%AF%B7%E6%B1%82)
2. 客户端设置消息优先级
>构建消息体时在消息体内传入`priority`字段，值为`high`，代表高优先级消息。如果不设置，默认值为 `normal`，即“普通”优先级。

PS:建议客户端普通弹幕可设置为低优先级`low`
- [点击设置参考文档-聊天室消息](https://doc.easemob.com/document/web/message_send_receive.html#%E5%8F%91%E9%80%81%E6%96%87%E6%9C%AC%E6%B6%88%E6%81%AF)

```js
  const options = {
    to: 'your roomId', // 发送目标 ID，即聊天室 ID。
    msg: 'your message content',// 消息内容
    chatType: "chatRoom", // 聊天类型 聊天室即为`chatRoom`
    type: "txt", //消息类型
    priority: 'low', // 消息优先级
  };
  const msg = EMClient.Message.create(options)
  EMClient.send(msg)
```

## 错误码
[错误码文档地址](https://doc.easemob.com/document/web/error.html)