@polyv/interactions-receive-sdk/README.md

SDK for receiving interactions of Polyv

# 互动功能接收端 SDK

## 概述
本项目是保利威直播互动功能接收端（观众端）的逻辑层 SDK。开发人员可以使用本 SDK 接入互动功能，或者基于本 SDK 定制开发互动功能界面。

## 使用

### 安装
```bash
pnpm i -S @polyv/interactions-receive-sdk
```

### 引入

#### 在线文件引入方式
```html
// script 标签引入，根据版本号引入JS版本。
<script src="https://websdk.videocc.net/interactions-receive-sdk/0.7.0/lib/polyv-ir.umd.js"></script>

<script>
    const { updateConfig } = window.PolyvIRSDK;
</script>
```

#### import 方式引入（推荐）
```javascript
import { updateConfig } from '@polyv/interactions-receive-sdk';
```

### 初始化

使用本 SDK 的具体功能模块前，必须调用 `updateConfig` 方法传入配置信息，包含频道信息、观众信息和连接聊天室的 Socket.IO 实例等信息。

```javascript
const userInfo = {
  // 昵称
  nick: '观众昵称',
  // 头像
  pic: 'https://example.com/avatar.jpg',
  // 观众id
  userId: '1',
};
const channelInfo = {
  // 频道号
  channelId: '',
  // 房间号
  roomId: '',
  // 频道场次id
  sessionId: '',
};

updateConfig({
  // 观众信息
  userInfo: userInfo,
  // 频道信息
  channelInfo: channelInfo,
  // 此处传入 socketio 实例，具体获取方式请看下文
  socket: socket,
  // viewerApiToken 更新函数
  getViewerApiToken: async (callback) => {
    const viewerApiToken = await myViewerApiTokenGetter();
    callback({ viewerApiToken })
  },
})
```

在配置完成后，支持再次调用并传入新的配置参数（允许仅更新部分参数）。比如：

- 当观众修改昵称后，需要再次设置 userInfo 参数的 nick 字段；
- 直播场次 id 更新后，需要再次设置 channelInfo 的 sessionId 字段。

#### userInfo 参数
userInfo 指观众信息，部分互动功能在请求服务端数据时将需要用到。需传入一个对象类型的参数，详细字段信息如下：

| 属性名 | 类型 | 含义 |
| --- | --- | --- |
| nick | string | 观众昵称（要求具有唯一性） |
| pic | string | 观众头像 |
| userId | string | 观众id（指客户业务系统中的用户id，应当具有唯一性） |

#### channelInfo 参数
channelInfo 指频道信息，需传入一个对象参数，该参数详细字段信息如下：

| 属性名 | 类型 | 含义 |
| --- | --- | --- |
| channelId | string | 直播频道号 |
| roomId | string | 房间号，一般情况下房间号与频道号一致。若频道开启聊天室分房间功能，需传入具体分房间号 |
| sessionId | string | 频道场次id，每次频道直播推流后都会产生一个新的场次id，直播过程中产生的各种互动数据与该场次id相关联 |

**Tips**
- 可通过[保利威直播 SDK](https://help.polyv.net/index.html#/live/js/live_js_sdk/live_js_sdk)的 `'CHANNEL_DATA_INIT'` 事件参数中的 sessionId 字段，获取频道当前场次 id。

#### socket 参数
本参数是发送和接收 WebSocket 消息的对象，主要用于与保利威后端建立长连接来完成各种实时的互动功能。
为了获取到这个参数，本项目必须搭配以下两个 SDK 之一使用：

- [保利威聊天室 SDK](https://help.polyv.net/index.html#/live/js/chat_js_sdk)。
- [保利威直播 SDK](https://help.polyv.net/index.html#/live/js/live_js_sdk/live_js_sdk)。

具体获取方式可参考以下示例代码。
##### 示例代码

- 搭配保利威聊天室 SDK

```javascript
const chatroom = new PolyvChatRoom({
  // 相关参数
});

// 配置互动功能SDK
updateConfig({
  // 此处传入 socketio 实例
  socket: chatroom.chat.socket,
  userInfo: userInfo,
  channelInfo: channelInfo,
  getViewerApiToken,
});
```

- 搭配保利威直播 SDK

```javascript
const liveSdk = new PolyvLiveSdk({
  // 相关参数
});

// 配置互动功能SDK
updateConfig({
  // 此处传入 socketio 实例
  socket: liveSdk.socket,
  userInfo: userInfo,
  channelInfo: channelInfo,
  getViewerApiToken,
});
```

#### getViewerApiToken参数

本 SDK 调用后端接口时，需要用到 apiToken。获取 apiToken 的交互流程如下：

![获取 apiToken 时序图](https://help.polyv.net/live/js/new_sdk/interactions_receive_sdk/sdk/overview.assets/interactions-receive-sdk.jpeg)

在这个流程中，需要调用 [polyv 服务端接口](https://help.polyv.net/index.html#/live/api/channel/operate/get_api_token)。由于该接口的参数涉及 appId 和 appSecret 等敏感信息，因此需要由接入方的服务端去请求该接口，而不是直接在前端请求。

`getViewerApiToken` 是一个异步函数，用于请求接入方的接口获取 apiToken，然后通过调用 `callback` 回调函数返回给 SDK。由于 apiToken 有一定的有效期，所以在 SDK 运行期间，该函数可能会执行多次。

```javascript
async function getViewerApiToken(callback) {
  const viewerApiToken = await api.post('[接入方获取token接口]');
  // 回调函数更新SDK内token
  callback({ viewerApiToken });
};

updateConfig({
  // 其他配置参数
  getViewerApiToken,
});
```

## API 文档
点击<a href="https://help.polyv.net/live/js/new_sdk/interactions_receive_sdk/sdk/docs/index.html" target="_blank" rel="noopener">此处</a>可查看 API 文档。

## 功能模块
完成配置后，即可进行各模块SDK的实例化使用。
具体见各模块详细文档。
- 答题卡（AnswerCard）：[答题卡 SDK 文档](https://help.polyv.net/index.html#/live/js/new_sdk/interactions_receive_sdk/sdk/answer_card)
- 签到（CheckIn）：[签到 SDK 文档](https://help.polyv.net/index.html#/live/js/new_sdk/interactions_receive_sdk/sdk/check_in)
- 抽奖（Lottery）：[抽奖 SDK 文档](https://help.polyv.net/index.html#/live/js/new_sdk/interactions_receive_sdk/sdk/lottery)
- 公告（Announcement）：[公告 SDK 文档](https://help.polyv.net/index.html#/live/js/new_sdk/interactions_receive_sdk/sdk/notice)
- 问卷（Questionnaire）：[问卷 SDK 文档](https://help.polyv.net/index.html#/live/js/new_sdk/interactions_receive_sdk/sdk/questionnaire)
- 卡片推送（PushCard）：[卡片推送 SDK 文档](https://help.polyv.net/index.html#/live/js/new_sdk/interactions_receive_sdk/sdk/push_card)
- 条件抽奖（WelfareLottery）：[条件抽奖 SDK 文档](https://help.polyv.net/index.html#/live/js/new_sdk/interactions_receive_sdk/sdk/welfare_lottery)