互動接收端 SDK

一、簡介

強大、靈活、易用的新版保利威互動接收端 SDK，支援簽到、抽獎、問卷、優惠券等豐富的互動場景。開發人員可以使用本 SDK 接入互動功能，或者基於本 SDK 客製開發互動功能介面。

二、整體架構

┌─────────────────────────────────────────────────────────────┐
│                     业务应用层                                │
├─────────────────────────────────────────────────────────────┤
│  签到模块   抽奖模块   问卷模块   优惠券模块   ...其他功能模块      │
├─────────────────────────────────────────────────────────────┤
│                   核心模块 (Core)                            │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐            │
│  │ Socket 通信  │ │ API 请求    │ │ 日志监控      │            │
│  └─────────────┘ └─────────────┘ └─────────────┘            │
├─────────────────────────────────────────────────────────────┤
│              保利威直播平台基础服务                             │
└─────────────────────────────────────────────────────────────┘

三、🚀 快速開始

3.1 安裝 core 核心模組包

@polyv/interaction-core 是 SDK 的核心模組包，是對 socket 通訊、API 請求以及日誌等功能的封裝。

// pnpm
pnpm add @polyv/interaction-core

// npm
npm i @polyv/interaction-core

3.2 引入

UMD 方式

其中 rc-20250814 為版本號，請根據實際版本號引入。

<script src="https://websdk.videocc.net/interaction-core/rc-20250814/index.umd.js"></script>

<script>
const InteractionCore = window.PolyvInteractionCore;
</script>

NPM 方式

import { InteractionCore, type TrackEventData } from '@polyv/interaction-core';

3.3 初始化

實例化 InteractionCore 類別，傳入 getSocket、getViewerToken 等參數：

const interactionCore = new InteractionCore({
  // 搭配保利威聊天室 SDK 使用，返回 SocketIOClient.Socket 实例
  getSocket: () => {
    return socket;
  },
  getChannelInfo: () => {
    return {
      // 频道 ID
      channelId: '',
      // 场次 ID
      sessionId: '',
      // 保利威账号 ID
      accountId: '',
      // 观看页地址
      watchUrl: '',
      // 邀请海报选择页地址
      inviteUrl: '',
      // 频道直播状态
      liveStatus: '',
    };
  },
  getChannelConfig: () => {
    return {
      // 是否启用观看页营销埋点
      watchEventTrackEnabled: false,
      // 商品库事件上报开关
      productTrackEnabled: false,
    };
  },
  getUserInfo: () => {
    return {
      // 用户 userId
      userId: '',
      // 用户 unionId
      unionId: '',
      // 用户昵称
      nick: '',
      // 用户头像地址
      pic: '',
      // 用户授权方式
      authType: '',
      // 微信 openid
      wxOpenId: '',
      // 微信 unionId
      wxUnionId: '',
    };
  },
  getViewerToken: () => {
    return {
      // 授权 token
      viewerToken: '',
    };
  },
  getSourceInfo: () => {
    return {
      // 来源类型
      sourceType: '',
      // 来源 ID
      sourceId: '',
    };
  },
  domainInfo: {
    // 观看页域名
    watchPageDomain: '',
    // 直播 api 域名
    polyvApiDomain: '',
    // 聊天室 api 域名
    chatApiDomain: '',
    // 静态资源域名
    staticDomain: '',
  },
});

3.4 viewerToken 取得

本 SDK 呼叫後端介面時，需要使用 viewerToken，它的互動流程如下：

在這個流程中，需要呼叫 polyv 服務端介面。由於該介面的參數涉及 appId 和 appSecret 等敏感資訊，因此需要由接入方的服務端去請求該介面，而不是直接在前端請求。

拿到 viewerToken 後，在初始化 interactionCore 時，透過 getViewerToken 方法將 viewerToken 傳入。

const interactionCore = new InteractionCore({
  // 其他配置...
  getViewerToken: () => {
    return {
      viewerToken: 'your-viewer-token-here',
    };
  },
  // 其他配置...
});

四、API 方法

4.1 設定核心

初始化核心實例，開始監聽 Socket 事件。

Api 方法： setup(): void

範例：

interactionCore.setup();

4.2 取得 socket 實例

Api 方法： getSocket(): Promise<undefined | Socket>

回傳值說明： Socket 實例，Promise<undefined | Socket> 類型

範例：

const socket = await interactionCore.getSocket();
console.log('Socket 状态:', socket?.connected);

4.3 透過 socket 實例取得聊天令牌

Api 方法： getChatToken(): Promise<undefined | string>

回傳值說明： 聊天令牌，Promise<undefined | string> 類型

範例：

const token = await interactionCore.getChatToken();
console.log('聊天令牌:', token);

4.4 發送 socket 資料

Api 方法： emitSocket(socketData: unknown, socketType?: SocketEventType, options?: Object): Promise<D>

參數說明：

• socketData：socket 資料，unknown 類型，必傳

• socketType：socket 類型，預設：message，SocketEventType 類型，選傳，預設 'message'

• options：選項配置，Object 類型，選傳，詳細類型說明如下

回傳值說明： 回傳的資料，Promise<D> 類型

範例：

const result = await interactionCore.emitSocket({
  EVENT: 'GET_USER_INFO'
});
console.log('用户信息:', result);

4.5 新增 socket 事件監聽

為指定應用程式新增 Socket 事件處理器。

Api 方法： addSocketHandles(appName: string, handlers: SocketEventStoreHandlers, socketType?: SocketEventType): void

參數說明：

• appName：應用程式名稱，string 類型，必傳

• handlers：訊息事件處理物件，SocketEventStoreHandlers 類型，必傳

• socketType：socket 事件類型，預設：message，SocketEventType 類型，選傳，預設 'message'

範例：

interactionCore.addSocketHandles('lottery', {
  LOTTERY_START: (data) => {
    console.log('抽奖开始:', data);
  }
});

4.6 取得頻道資訊

Api 方法： getChannelInfo(): Promise<ChannelInfo>

回傳值說明： 頻道資訊，Promise<ChannelInfo> 類型，詳細類型說明如下

範例：

const channelInfo = await interactionCore.getChannelInfo();
console.log('频道ID:', channelInfo.channelId);

4.7 取得頻道配置

Api 方法： getChannelConfig(): Promise<undefined | ChannelConfig>

回傳值說明： 頻道配置，Promise<undefined | ChannelConfig> 類型

範例：

const config = await interactionCore.getChannelConfig();
console.log('是否开启商品推送:', config?.productTrackEnabled);

4.8 取得使用者資訊

Api 方法： getUserInfo(): Promise<UserInfo>

回傳值說明： 使用者資訊，Promise<UserInfo> 類型，詳細類型說明如下

範例：

const userInfo = await interactionCore.getUserInfo();
console.log('用户昵称:', userInfo.nick);

4.9 取得域名資訊

Api 方法： getDomainInfo(): Required<DomainInfo>

回傳值說明： 域名資訊，Required<DomainInfo> 類型

範例：

const domainInfo = interactionCore.getDomainInfo();
console.log('直播API域名:', domainInfo.polyvApiDomain);

4.10 產生用於重新導向的二維碼地址

Api 方法： generateQrcodeUrl(url: string): string

參數說明：

• url：二維碼內容，string 類型，必傳

回傳值說明： 二維碼圖片地址

範例：

const qrUrl = interactionCore.generateQrcodeUrl('https://example.com');
console.log('二维码地址:', qrUrl);

4.11 發送事件日誌

Api 方法： trackEvent(data: TrackEventData): Promise<void>

參數說明：

• data：事件資料，TrackEventData 類型，必傳，詳細類型說明如下

範例：

await interactionCore.trackEvent({
  event_id: 'lottery_participate',
  event_type: 'user_behavior',
  spec_attrs: { lotteryId: 'lottery123' }
});

五、功能模組

六、UI 元件