@xmov/avatar 2.3.1 → 2.4.0-alpha.1

package/src/modules/sentry-reporter.ts

@@ -0,0 +1,171 @@
+import {
+  BrowserClient,
+  defaultStackParser,
+  getDefaultIntegrations,
+  makeFetchTransport,
+  Scope,
+  browserTracingIntegration,
+  startSpan,
+  startInactiveSpan,
+} from '@sentry/browser';
+
+import type { SDKError } from 'types/error';
+
+/** 渲染噪音 / 数据过期等高频低危错误码，直接过滤不上报 */
+const NOISE_ERROR_CODES = ['3205', '3206', '3305', '30005'];
+
+export interface SentryReporterOptions {
+  /** Traces 采样率，默认 1.0（100% 全量） */
+  tracesSampleRate?: number;
+}
+
+/** span 附加属性（兼容 Sentry SpanAttributeValue 的标量子集） */
+type SpanData = Record<string, string | number | boolean | undefined>;
+
+/**
+ * Sentry 错误上报器（隔离实例）
+ *
+ * 使用独立的 BrowserClient + Scope，不污染宿主应用的全局 Sentry 状态。
+ * 此文件仅在公有云构建（ENABLE_SENTRY=true）时被打包，
+ * 私有化构建时通过编译时常量 + 死代码消除完全移除。
+ */
+export class SentryReporter {
+  private client: BrowserClient;
+  private scope: Scope;
+  private tracesSampleRate: number;
+
+  constructor(dsn: string, options: SentryReporterOptions = {}) {
+    this.tracesSampleRate = options.tracesSampleRate ?? 1.0;
+
+    // 过滤掉依赖全局状态的集成，避免与宿主应用的 Sentry 实例冲突
+    const integrations = getDefaultIntegrations({}).filter(
+      (i) =>
+        ![
+          'BrowserApiErrors',
+          'BrowserSession',
+          'Breadcrumbs',
+          'GlobalHandlers',
+          'FunctionToString',
+          'Dedupe',      
+        ].includes(i.name),
+    );
+
+    // 显式加入 BrowserTracing（getDefaultIntegrations 未包含），
+    // 关闭页面加载/导航/请求自动追踪，只保留手动 startSpan 埋点，避免噪音 span
+    integrations.push(
+      browserTracingIntegration({
+        instrumentPageLoad: false,
+        instrumentNavigation: false,
+        traceFetch: false,
+        traceXHR: false,
+      }),
+    );
+
+    this.client = new BrowserClient({
+      dsn,
+      transport: makeFetchTransport,
+      stackParser: defaultStackParser,
+      integrations,
+      release: `xmov-avatar@${VERSION}`,
+      tracesSampleRate: this.tracesSampleRate,
+      beforeSend(event) {
+        // ① 白名单：仅上报 SDK 自身错误（source 标签由 scope 打标），过滤宿主页面异常
+        if (event.tags?.source !== 'xmov-avatar-sdk') {
+          return null;
+        }
+        // ② 噪音码过滤：高频渲染噪音 / 数据过期类，避免事件量过大
+        const errorCode = String(event.tags?.error_code ?? '');
+        if (NOISE_ERROR_CODES.includes(errorCode)) {
+          return null;
+        }
+        // ③ 指纹去重：按「错误码 + 消息前缀」合并，同码同消息收敛为一个 Issue
+        event.fingerprint = [
+          errorCode || 'unknown',
+          String(event.message ?? '').slice(0, 64),
+        ];
+        // ④ 上下文补全：浏览器/UA（app_id / session_id 等已在 scope 打标）
+        event.contexts = {
+          ...(event.contexts ?? {}),
+          browser: { name: navigator.userAgent.slice(0, 200) },
+        };
+        return event;
+      },
+    });
+
+    this.scope = new Scope();
+    this.scope.setClient(this.client);
+    this.scope.setTag('sdk_version', VERSION);
+    this.scope.setTag('source', 'xmov-avatar-sdk');
+    this.client.init();
+  }
+
+  /**
+   * 上报 SDK 错误
+   */
+  captureError(error: SDKError): void {
+    // 在隔离 scope 上设置本次错误的标签和上下文
+    this.scope.setTag('error_code', String(error.error_code));
+    this.scope.setTag('error_name', error.error_name);
+    this.scope.setTag('session_id', error.session_id);
+    this.scope.setExtra('code', error.code);
+    this.scope.setExtra('client_speak_id', error.client_speak_id);
+    this.scope.setExtra('timestamp', error.timestamp);
+    if (error.originalError) {
+      this.scope.setExtra('originalError', error.originalError);
+    }
+    this.scope.captureException(new Error(error.message));
+  }
+
+  /**
+   * 在隔离 scope 上启动一个 span 并执行回调，回调返回时自动结束。
+   * 异常时 span 自动标记 error（由 startSpan 内部处理），span 数据发往本实例的 DSN。
+   */
+  startSpan<T>(name: string, ctx: { op?: string; data?: SpanData }, fn: () => T): T {
+    return startSpan(
+      {
+        name,
+        op: ctx.op,
+        scope: this.scope,
+        attributes: ctx.data,
+      },
+      () => fn(),
+    );
+  }
+
+  /**
+   * 启动一个手动管理生命周期的 span（跨回调/异步时用），
+   * 返回的句柄在操作完成时调用 end() 结束 span。
+   */
+  startInactiveSpan(name: string, ctx: { op?: string; data?: SpanData }): { end(): void } {
+    const span = startInactiveSpan({
+      name,
+      op: ctx.op,
+      scope: this.scope,
+      attributes: ctx.data,
+    });
+    return {
+      end: () => span?.end(),
+    };
+  }
+
+  /**
+   * 设置全局标签
+   */
+  setTag(key: string, value: string): void {
+    this.scope.setTag(key, value);
+  }
+
+  /**
+   * 设置用户信息
+   */
+  setUser(user: { id?: string; ip_address?: string }): void {
+    this.scope.setUser(user);
+  }
+
+  /**
+   * 销毁 Sentry 客户端，flush 未发送的事件
+   */
+  async destroy(): Promise<void> {
+    await this.client.close(2000);
+  }
+}

package/src/types/index.ts

@@ -111,6 +111,19 @@ export interface IAvatarOptions {
    */
   onAudioPlaybackData?(data: IAudioPlaybackData): void;
   /**
+   * Sentry 错误监控配置
+   * 仅在公有云构建（ENABLE_SENTRY=true）时生效，私有化构建会忽略此配置
+   * 设为 { enabled: false } 可禁用 Sentry 上报
+   */
+  sentry?: {
+    enabled?: boolean
+    /**
+     * 性能 Traces 采样率（0-1），默认 1.0（100% 全量）
+     * 容量受限时可下调，如 0.1（10%）
+     */
+    tracesSampleRate?: number
+  }
+  /*
    * 每帧数据回调
    * 返回当前帧的 face + body 原始数据（帧号、body_id 等）
    */

package/src/utils/encodeToken.ts

@@ -1,9 +1,24 @@
 import md5 from 'blueimp-md5';
+import { generateFingerprint } from './index';
 
 function encodeWithMd5(s: string): string {
   return md5(s);
 }
 
+/**
+ * 生成 request_id：用于 startSession / stopSession 的幂等与兜底销毁。
+ * 组成：md5(机器指纹 + 毫秒时间戳 + appId)
+ * 同一次 init → destroy 生命周期内始终不变，即使 session_id 尚未返回
+ * 也能用 request_id 让服务端销毁已占用的房间资源。
+ */
+export function generateRequestId(appId: string): string {
+  const fingerprint = (() => {
+    try { return generateFingerprint(); } catch { return 'unknown'; }
+  })();
+  const payload = `${fingerprint}|${Date.now()}|${appId}`;
+  return md5(payload);
+}
+
 function escapeNonAsciiForPythonJson(value: string): string {
   return value.replace(/[^\u0000-\u007E]/g, character => {
     return `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`;