互动接收端 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 组件