@polyv/chat-sdk/README.md

SDK for using chat service of Polyv

# 聊天室 JS-SDK

## 概述
本项目是保利威聊天室服务逻辑层 SDK。开发人员可以使用本 SDK 接入聊天室服务、基于本 SDK 定制开发聊天界面。

## 使用

### 安装
```
npm i @polyv/chat-sdk
```

### 初始化

传入参数实例化 SDK 类，然后调用实例方法 `setup`。例如：

```javascript
import { PlvSocket, Chat } from '@polyv/chat-sdk';

// @TODO 以下参数缺少详细说明以及参数注意要点，这里只需展示最小参数范围，要体现“快速”接入。

const plvSocket = new PlvSocket({
  // 聊天室连接授权 token 获取方式参考 https://help.polyv.net/index.html#/live/api/channel/operate/get_chat_token
  token: '聊天室 token',
  // 聊天室用户信息
  userInfo: {
    // 用户id
    userId: '',
    // 用户昵称
    nick: '',
    // 用户头像
    pic: '',
    // 用户身份类型(如普通观众student、讲师teacher、云课堂观众slice)
    userType: 'student',
    // 头衔(如"讲师")
    actor: ''
  },
  // 聊天室频道(房间)信息
  channelInfo: {
    // 频道id
    channelId: '',
    // 房间id
    roomId: '',
    // 频道所属账号id
    accountId: '',
    // 频道当前场次id
    sessionId: '',
  },
  // token过期时，用于重新请求token的异步函数
  // 聊天室连接授权 token 获取方式参考 https://help.polyv.net/index.html#/live/api/channel/operate/get_chat_token
  getToken: (callback) => {
    // ... 获取 token
    callback(token);
  },
});
const chat = new Chat({
  plvSocket: plvSocket,
  // 频道API访问令牌 channelToken 更新函数。对于讲师，部分功能需要传入获取 channelToken 及 appId 的函数才能正常使用。
  // channelToken 获取方式参考 https://help.polyv.net/index.html#/live/api/channel/auth/get_channel_api_access_token
  getChannelToken: (callback) => {
    // ... 获取 channelToken 及 appId
    callback({ channelToken, appId })
  },
});
chat.setup();
```


### 更新配置

在某些情况下，需要更新聊天室SDK的配置信息。

比如频道直播场次已更新，那么为了使用户在聊天室发言消息与新场次关联，此时需要将新的直播场次id传入。

更新配置方法（参数结构与构建函数参数一致，可仅提供某字段，SDK 内部会进行合并更新）。
```javascript
chat.updateConfig({
  channelInfo: {
    sessionId: '',
  }
});
```

### 销毁实例

使用 `destroy` 方法销毁聊天室 SDK 实例，销毁后将断开 Websocket 连接，并清空事件监听逻辑。

```javascript
chat.destroy();
```

### 常用实例属性    

@TODO 要用实例说明以下属性是什么情况下需要调用，只列出来客户还是不知道怎么用。也可以放到后续章节内容中。

| 属性名 | 类型 | 说明 |
| --- | --- | --- |
| events | Object | 聊天室 SDK 事件列表 |
| msgTypes | Object | 聊天室 SDK 封装聊天消息类型 |
| uploader | Object | 聊天室图片消息上传发送工具 |

### 常用实例方法

@TODO 这个不是常用方法（只有讲师、管理人员需要），不用单独列出。

| 方法名 | 入参 | 出参 | 说明 |
| --- | --- | --- | --- |
| setChatEnabled | 设置全体禁言 | Boolean | Promise<void> |

### 事件处理

#### 事件名

可通过 `chat.events` 或 `Chat.EVENTS` 访问SDK事件常量，用以监听聊天室事件并且进行处理。

```javascript
console.log(chat.events);
```

#### 事件的监听与取消监听

```javascript
// 事件处理函数
const listener = (event) => {
  console.log(event); 
};
// 使用 chat.on 监听事件
chat.on(chat.events.SPEAK, listener);
// 使用 chat.off 取消监听事件
chat.off(chat.events.SPEAK, listener);
```


### 历史聊天消息

#### 场次历史消息

每场直播都会对应一个唯一的场次id（sessionId），该场直播中所有用户的发言都关联了该 id，可以通过 `getSessionHistory` 方法获取该场次直播的历史聊天消息。

可根据返回数据中的 `totalPage` 字段判断当前是否加载到末页。

```javascript
async function getSessionHistory() {
  const res = await chat.getSessionHistory({
    // 场次 id(非必传，默认使用实例的 sessionId)
    sessionId: '',
    // 页数
    page: 1,
    // 条数(非必传，默认10)
    size: 20,
  });
  const { curPage, totalPage, count, size, data = [] } = res;
  console.log('场次消息列表数据：', data);
}
```

#### 频道历史消息

可通过 `getChannelHistory` 方法获取频道所有场次的聊天消息（注意，每个频道都有允许保存的最大消息数量，因此消息量超过特定数量时会由新到旧返回历史消息）。

```javascript

async function getChannelHistory() {
  let start = 0;
  let end = 9;

  const msgList = await chat.getChannelHistory({
    // 房间号(若不传，默认为实例中的房间号/频道号)
    roomId: '',
    // 开始索引
    start,
    // 结束索引
    end,
    // 是否获取全部信息。1表示获取全部(默认)，0表示过滤图片和自定义消息
    fullMessage: 1,
    // 是否仅获取特殊角色发言(讲师、助教、嘉宾)，后端默认 0(全部获取) 
    getSpecialMessage: 0,
  });

  console.log('频道消息列表数据', msgList);
  // 可根据返回的消息列表长度是否满足索引跨度，来判断当前是否加载到末尾。
  if (msgList.length < end - start) {
    console.log('已加载到消息列表末尾');
  }
}
```

### 收发聊天消息
他人发言、发送图片、自定义消息及移除消息等，均会在 SDK 内触发相应事件，可监听这些事件，并根据参数去处理实际所需显示的消息。

#### 接收消息

@TODO 事件类型和说明不用放出来了，链接到文档即可。
@TODO 帮助中心子文档

此处列举所有与聊天室消息相关的事件，详细事件参数字段等，请参考 typedoc 文档。  

| 事件名 | 参数 | 说明 |
| --- | --- | --- |
| chat.events.SPEAK | - | 他人发言 |
| chat.events.CHAT_IMG | - | 他人聊天图片消息 |
| chat.events.SEND_MESSAGE | - | 个人发言。调用发言方法后将触发该事件，此时可将个人发言插入到本地消息列表。 | 
| chat.events.SELF_CHAT_IMG | - | 个人开始发送图片消息。在图片开始上传时，即触发该事件，可基于该事件将消息插入本地进行展示，并展示图片上传状态。 |
| chat.events.SYS_MSG | - | 系统消息。比如发送消息过快触发限流时，会触发该事件。可在监听到此事件后给予用户反馈。 |
| chat.events.CUSTOMER_MESSAGE | - | 自定义消息 |
| chat.events.REMOVE_HISTORY | - | 管理员清空聊天室消息。收到该事件时，聊天室记录将被清除，相应地前端也需要将展示中的消息进行清除。 |
| chat.events.REMOVE_CONTENT | - | 管理员移除单条消息。可根据id将对应消息删除。 |
| chat.events.CLOSEROOM | - | 关闭聊天室。管理员等特殊角色关闭了聊天室，此时普通用户禁止发言，前端可给予相应提示。 |
| chat.events.OPENROOM | - | 开启聊天室。恢复普通用户发言权限。 |

##### 消息类型列表

@TODO 没看明白 msgTypes 的作用，如果不好说清楚，可以先不提
@TODO 帮助中心子文档

为了便于快速集成，SDK 基于展示形式对部分消息进行了分类，详细类型常量可通过 `chat.msgTypes` 访问。部分需要展示的事件数据会含有 `msgType` 字段，只需要将其插入本地消息列表并根据该字段展示对应形式的组件/样式，同样，历史消息也会封装此字段。下面列举各 `msgType` 对应的事件。

| msgType | 事件 |
| --- | --- |
| NORMAL | SEND_MESSAGE、SPEAK |
| CHAT_IMG | CHAT_IMG、CHAT_IMG_UPLOAD_PROGRESS、SELF_CHAT_IMG_RESULT |
| CUSTOMER_MESSAGE | CUSTOMER_MESSAGE |
| SYSTEM | SYS_MSG(本地触发，如发言频繁) |
| RED_PAPER_RESULT | RED_PAPER_RESULT |
| REWARD | REWARD |

在监听到上述事件时，可以考虑将消息体加入到待显示消息列表中，然后根据具体 msgType 采用相应组件进行渲染展示。
#### 发送消息

##### 发送文字消息

可使用 `send` 方法发送普通文字消息。

```javascript
chat.send(
  '消息内容',
  // 第二个参数为引用消息，非必传。
  // 特殊角色使用公屏回复功能时需传入(完整传入，使SDK内部可封装、触发SEND_MESSAGE事件)
  {
    id,
    // ...
  }
);
```

##### 发送图片消息

@TODO 发送图片消息作为子文档，写到帮助中心

本 SDK 还可以支持发送图片消息，内部封装了包含图片上传、图片消息发送等逻辑，请按以下步骤进行接入。

###### 一、配置图片上传实例

在 SDK 实例化完毕后，聊天室实例会有 `uploader` 属性（即为图片上传功能的实例）。接入方需提供一个 file 类型的 input 元素，并在该元素加载完毕后，调用 `uploader.initImgUploader()` 传入 `input` 元素去初始化该图片上传实例。 例如：

```javascript
const $imgUploadInput = document.querySelector('#img-upload-input');
// 配置图片上传实例
chat.uploader.initImgUploader($imgUploadInput);
```

图片上传实例配置完毕后，接入方只需要控制该 `input` 元素的展示样式。当观众点击触发该元素并进行图片选择后，SDK 内部会监听到这个动作，并启动图片上传，过程中触发相应事件。    

###### 二、监听本地发送图片消息相关事件 

(1) `SELF_CHAT_IMG` 事件    
即 “本地发送图片” 事件，当图片开始上传时，该事件会被触发，此时可以将对应的消息插入到本地进行展示。然后监听下列消息，展示上传进度或结果。    

(2) `CHAT_IMG_UPLOAD_PROGRESS` 事件    
“图片上传进度”事件。指示图片开始上传、上传完毕或上传失败等状态。    
当图片上传完成后，SDK 内部会发送对应的图片消息到后端服务，后端将进一步处理。    

当监听到 `chat.events.CHAT_IMG_UPLOAD_PROGRESS` 事件中，eventData.content.status 与 `$chat.uploader.UploadImgStatus.UPLOAD_FAIL` 匹配时，说明上传过程出错，可尝试通过 `chat.uploader.resend(imgMsgId: String)` 来重新上传发送。

(3) `SELF_CHAT_IMG_RESULT` 事件      
“本地发送图片消息结果”事件，指示后端处理图片消息的结果。事件参数的 `result` 字段代表图片是否通过违规鉴定，当且仅当 Boolean 值为 false 表示不通过，此时可展示对应发送结果(如修改已插入本地的消息)。未通过鉴定的图片将不被广播给其他用户，也无法从历史消息 API 中获取到。


###### 三、可通过编程的方式触发文件选择弹窗    

```javascript
chat.uploader.selectFile()
```

### 聊天室控制

此项内容针对讲师/管理员等特殊角色，这些角色拥有部分管理聊天室消息的权限。

#### 聊天室禁言

可通过 `setChatEnabled` 方法关闭聊天室，聊天室关闭后普通用户无法发言。

**注意**：必须为聊天室SDK配置 `getChannelToken` 参数，用作相应接口的权限认证。
```javascript
async function setChatEnabled(enabled) {
  // enabled 为 Boolean，true 表示开启聊天室，false 表示关闭聊天室
  await chat.setChatEnabled(enabled);
}
```

### 其他注意事项
`setup` 是异步方法，返回值是一个 promise，该promise在聊天室连接成功后被 resolve。
@TODO 补充说明什么情况下要等待 promise，什么时候不用。要补充示例代码。
可以不用等待该 promise 完成，setup 并立即进行聊天室事件监听，以便于处理 `CONNECT` 等初始事件。