JSPM

  • Created
  • Published
  • Downloads 4
  • Score
    100M100P100Q68186F

SDK for using chat service of Polyv

Package Exports

  • @polyv/chat-sdk
  • @polyv/chat-sdk/lib/polyv-chat.common.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@polyv/chat-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

聊天室 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 要用实例说明以下属性是什么情况下需要调用,只列出来客户还是不知道怎么用。也可以放到后续章节内容中。

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

常用实例方法

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

方法名 入参 出参 说明
setChatEnabled 设置全体禁言 Boolean Promise

事件处理

事件名

可通过 chat.eventsChat.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 文档。

事件名 参数 说明
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 方法发送普通文字消息。

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 等初始事件。