互动功能接收端 SDK

概述

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

使用

安装

npm i -S @polyv/interactions-receive-sdk

引入

在线文件引入方式

// script 标签引入，根据版本号引入JS版本。
<script src="https://websdk.videocc.net/interactions-receive-sdk/0.24.0/lib/polyv-ir.umd.js"></script>

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

import 方式引入（推荐）

import { updateConfig } from '@polyv/interactions-receive-sdk';

初始化

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

// 账号 appSecret
const appSecret = '';
// 账号 appId
const appId = '';
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: (callback) => {
    myViewerApiTokenGetter(callback);
  },
})

async function myViewerApiTokenGetter(cb) {
    var params = {
        appId: appId, // 账号appId
        channelId: channelId, // 频道号
        timestamp: new Date().getTime(),// 时间戳
        viewerId: userId, // 观看者用户Id
    };
    params.sign = getSign(params, appSecret);
    $.ajax({
        url: "https://api.polyv.net/live/v3/channel/watch/get-api-token",
        type: "POST",
        async: false,
        data: params,
        success: (data) => {
            const token = data.data.token;
            cb({viewerApiToken: token});
        },
    });
}

function getSign(obj, appSecret) {
    const arr = Object.keys(obj)
        .filter((item) => item !== 'sign')
        .sort(); // 拿到除sign外字母顺序排列的key
    let query = '';
    arr.forEach((key) => {
        let value = obj[key];
        if (typeof value === 'object') {
            value = JSON.stringify(value);
        }
        query += key + value;
    });
    // md5 加密
    return md5(appSecret + query + appSecret)
        .toString()
        .toUpperCase();
}

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

• 当观众修改昵称后，需要再次设置 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的 'CHANNEL_DATA_INIT' 事件参数中的 sessionId 字段，获取频道当前场次 id。

socket 参数

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

• 保利威聊天室 SDK。

• 保利威直播 SDK。

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

示例代码

• 搭配保利威聊天室 SDK

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

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

• 搭配保利威直播 SDK

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

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

getViewerApiToken参数

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

获取 apiToken 时序图

在这个流程中，需要调用 polyv 服务端接口。由于该接口的参数涉及 appId 和 appSecret 等敏感信息，因此需要由接入方的服务端去请求该接口，而不是直接在前端请求。

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

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

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

API 文档

点击此处可查看 API 文档。

功能模块

完成配置后，即可进行各模块SDK的实例化使用。 具体见各模块详细文档。

• 答题卡（AnswerCard）：答题卡 SDK 文档

• 签到（CheckIn）：签到 SDK 文档

• 抽奖（Lottery）：抽奖 SDK 文档

• 公告（Announcement）：公告 SDK 文档

• 问卷（Questionnaire）：问卷 SDK 文档

• 卡片推送（PushCard）：卡片推送 SDK 文档

• 条件抽奖（WelfareLottery）：条件抽奖 SDK 文档

• 图文直播（Tuwen）：图文直播 SDK 文档

• 商品库（Product）：商品库 SDK 文档