@polyv/chat-sdk v0.4.0-rc.1

聊天室 JS-SDK

概述

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

使用

安装

npm i @polyv/chat-sdk

初始化

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

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: () => {
    // 返回一个Promise
    return new Promise(resolve => {
      // TODO: 获取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 内部会进行合并更新）。

chat.updateConfig({
  channelInfo: {
    sessionId: '',
  }
});

销毁实例

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

chat.destroy();

常用实例属性

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

常用实例方法

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

事件处理

事件名

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

console.log(chat.events);

事件的监听与取消监听

// 事件处理函数
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 字段判断当前是否加载到末页。

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

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 文档。

消息类型列表

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

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

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

发送消息

发送文字消息

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

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

发送图片消息

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

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

一、配置图片上传实例

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

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 中获取到。

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

chat.uploader.selectFile()

聊天室控制

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

聊天室禁言

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

注意：必须为聊天室SDK配置 getChannelToken 参数，用作相应接口的权限认证。

async function setChatEnabled(enabled) {
  // enabled 为 Boolean，true 表示开启聊天室，false 表示关闭聊天室
  await chat.setChatEnabled(enabled);
}

其他注意事项

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