保利威文档中心

幫助中心

互動功能接收端 SDK

更新時間：2024-04-22 19:18:32

概述

本專案是保利威直播互動功能接收端（觀眾端）的邏輯層 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
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的實例化使用。 具體見各模組詳細文件。

联系客服，在线咨询