Realsee Telemetry

Realsee Telemetry 是一个用于收集和上报用户行为数据的遥测 SDK。

安装

npm install @realsee/telemetry
# 或
yarn add @realsee/telemetry

基础使用

import { setConfig, pushEvent } from '@realsee/telemetry';

// 初始化配置
setConfig({
  env: 'production',
  appKey: 'your-app-key',
  data: {
    userId: 'xxx',
    projectId: 'xxx',
  },
});

// 上报自定义事件
pushEvent({
  id: 'click_button',
  data: { buttonId: 'submit' },
});

完整配置说明

import { RealseeTelemetryConfig } from '@realsee/telemetry';

interface RealseeTelemetryConfig {
  /**
   * 运行环境
   * @default 'production'
   */
  env: 'production' | 'development' | 'test' | 'sandbox';

  /**
   * 开放平台应用密钥
   * @required
   */
  appKey: string;

  /**
   * 是否启用海外节点上报
   * @default false
   */
  i18n?: boolean;

  /**
   * 是否启用 FPS 监控上报
   * @default true
   */
  enableFps?: boolean;

  /**
   * FPS 上报时间间隔(秒)
   * @default 5
   */
  fpsInterval?: number;

  /**
   * FPS 上报阈值，低于此值才会上报
   * @default 55
   */
  fpsThreshold?: number;

  /**
   * 全局事件上报 QPS 限制
   * @default 5
   */
  reportQps?: number;

  /**
   * 特定事件的 QPS 限制配置
   * @example { 'five.stateChange': 10 }
   */
  reportQpsMap?: Record<string, number>;

  /**
   * 是否输出 QPS 限制相关日志
   * @default true
   */
  enableQpsLog?: boolean;

  /**
   * 需要携带完整 session 数据的事件列表
   */
  eventsWithFullSession?: Array<string | number>;

  /**
   * WebSocket 连接时附加的查询参数
   */
  query?: Record<string, unknown>;

  /**
   * 自定义会话数据
   */
  data?: Record<string, unknown>;

  /**
   * 是否自动初始化 Five 事件监听
   * @default true
   */
  autoInitFiveEvent?: boolean;

  /**
   * 是否启用日志输出
   * @default false
   */
  logger?: boolean;

  /**
   * 是否禁用遥测功能
   * @default false
   */
  disabled?: boolean;
}

使用示例

基础配置

import { setConfig } from '@realsee/telemetry';

setConfig({
  env: 'production',
  appKey: 'your-app-key',
  // 基础自定义数据
  data: {
    userId: 'user_123',
    projectId: 'proj_456',
  },
  // 连接参数
  query: {
    version: '1.0.0',
    platform: 'web',
  },
});

QPS 限制配置

setConfig({
  // ... 其他配置

  // 全局限制每秒5次上报
  reportQps: 5,

  // 特定事件的 QPS 限制
  reportQpsMap: {
    // Five 状态变更事件限制为每秒10次
    'five.stateChange': 10,
    // 模型插件状态变更限制为每秒3次
    'dnalogel-modelView.stateChange': 3,
    // 自定义事件限制
    'custom.click': 20,
  },

  // 是否显示 QPS 限制日志
  enableQpsLog: true,
});

FPS 监控配置

setConfig({
  // ... 其他配置

  // 启用 FPS 监控
  enableFps: true,

  // 每10秒上报一次
  fpsInterval: 10,

  // FPS 低于50才上报
  fpsThreshold: 50,
});

完整 Session 数据配置

setConfig({
  // ... 其他配置

  // 指定需要携带完整 session 数据的事件
  eventsWithFullSession: [
    'five.stateChange',
    'five.modeChange',
    'dnalogel-modelView.stateChange',
    'custom.important_action',
  ],
});

自定义事件上报

import { pushEvent } from '@realsee/telemetry';

// 上报点击事件
pushEvent({
  id: 'button_click',
  name: 'ButtonClick',
  data: {
    buttonId: 'submit',
    position: { x: 100, y: 200 },
  },
});

// 上报页面浏览事件
pushEvent({
  id: 'page_view',
  name: 'PageView',
  data: {
    pageId: 'home',
    duration: 5000,
  },
});

事件命名规则

遥测系统中的事件名称遵循以下规则：

1. Five SDK 事件

   • 格式: five.${eventName}
   • 示例:
     • five.stateChange
     • five.modeChange
     • five.panoLoaded

2. Dnalogel 插件事件

   • 格式: dnalogel-${pluginName}.${eventName}
   • 示例:
     • dnalogel-modelView.stateChange
     • dnalogel-floorplan.click

3. 自定义事件

   • 格式: custom.${eventId}
   • 示例:
     • custom.1234
     • custom.button_click
     • custom.page_view

注意事项

1. QPS 限制

   • 每个事件都受 QPS 限制
   • 优先使用 reportQpsMap 中的配置
   • 未配置时使用全局 reportQps

2. 数据大小

   • 建议控制单次上报数据大小
   • 避免频繁上报大量数据

3. 错误处理

   • SDK 内部会处理上报失败
   • 可通过 logger 配置查看详细日志

调试

启用日志输出以便调试：

setConfig({
  logger: true,
  env: 'development',
});

类型定义

完整的类型定义请参考：

• RealseeTelemetryConfig
• EventData
• WebSocketServerCommandData