@vivix-ai/ivi-frontend-sdk 0.3.9 → 0.3.11

package/README.md

@@ -5,6 +5,7 @@
 - 基于 `@vivix-ai/ivi-sdk-ts` 的 runtime 协调层
 - 通过 API 网关创建 IVI Session 的 HTTP 辅助方法
 - 面向舞台渲染的 React 组件与 hooks
+- 基于 OpenTelemetry API 的链路 span（SDK 不内置 exporter/provider）
 
 ## 安装依赖
 
@@ -214,6 +215,46 @@ await runtime.start();
 
 > 浏览器侧不应依赖 TRTC `secret_key`。SDK 在归一化 TRTC 信息时会丢弃 `secret_key` / `secretKey`，播放器只使用拉流所需的 `app_id`、`room_id`、`user_id`、`user_sig`。
 
+### 1.2）OpenTelemetry 链路观测
+
+SDK 只依赖 `@opentelemetry/api` 并创建 spans，不配置上报目的地。业务应用只要在入口处配置自己的 OpenTelemetry provider/exporter，随后把 `telemetry` 透传给 SDK 即可；未配置 provider 时这些调用会自动 no-op。
+
+```ts
+import { context, trace } from "@opentelemetry/api";
+import { createIVISessionRuntime } from "@vivix-ai/ivi-frontend-sdk";
+
+const telemetry = {
+  tracer: trace.getTracer("my-live-page"),
+  context: context.active(), // 可接上按钮点击、页面路由等外部父链路
+  attributes: {
+    "app.feature": "ivi-live"
+  }
+};
+
+const { runtime } = await createIVISessionRuntime(request, {
+  http: {
+    baseUrl: "https://api.example.com",
+    headers: { Authorization: `Bearer ${token}` }
+  },
+  telemetry,
+  fastStart: true,
+  bootstrapSlot: "main"
+});
+
+await runtime.start();
+```
+
+会被串联的关键 spans 包括：
+
+- `sdk.session.create`：HTTP 创建 IVI Session
+- `sdk.runtime.create` / `sdk.runtime.start` / `sdk.runtime.stop`
+- `sdk.client.connect` / `sdk.client.connection`：底层 `@vivix-ai/ivi-sdk-ts` WebSocket 连接与聚合消息计数
+- `sdk.media.trtc.join_room` / `sdk.media.livekit.join_room`：媒体进房耗时
+- `sdk.media.trtc.waiting_remote_video_available` / `sdk.media.trtc.start_remote_video` / `sdk.media.trtc.remote_video_rendered`：TRTC 远端视频事件等待、开始渲染、渲染完成等首屏关键点
+- `sdk.media.livekit.*`：LiveKit 远端视频可用等首屏关键点
+
+SDK span 不会写入 token、`user_sig`、TRTC `secret_key` 或完整业务 payload。低基数字段可以放在 `telemetry.attributes` 中统一附加。
+
 **使用自定义 WebSocket 运行时**（Node.js / 自定义环境）：
 
 ```ts
@@ -244,6 +285,7 @@ await runtime.start();
 | `transport` | `IviRealtimeTransport` | 通用 transport，直接透传给 `@vivix-ai/ivi-sdk-ts`；浏览器 LiveKit 场景可传 `LiveKitBrowserTransport` |
 | `onParseError` | `(error, rawMessage) => void` | 事件解析失败回调 |
 | `onLog` | `(entry) => void` | `IviClient` 链路日志回调，包含发送、transport 状态和重连链路 |
+| `telemetry` | `IviClientTelemetryOptions` | OpenTelemetry 配置；通常由上层 SDK 透传 |
 | `reconnect` | `IviClientReconnectOptions` | 自动重连配置；默认启用，指数退避 |
 | `sendWaitTimeoutMs` | `number` | 发送时等待连接恢复的超时，默认 `30000` ms，`<=0` 表示无限等待 |
 
@@ -480,6 +522,7 @@ function useManagedIviRuntime(config: IviManagedRuntimeConfig): IviRuntimeCoordi
 | `clientConfig` | `Partial<IviFrontendClientConfig>` | — | `IviClient` 配置；`transport` 为空时不创建 runtime |
 | `autoStart` | `boolean` | `true` | 是否自动启动 runtime |
 | `runtimeConfig` | `IviRuntimeCoordinatorConfig` | — | 透传给 `IviRuntimeCoordinator` |
+| `clientConfig.telemetry` / `runtimeConfig.telemetry` | `IviFrontendTelemetryOptions` | — | OpenTelemetry 透传；两处使用同一个配置即可串联 |
 | `onRuntimeInitError` | `(error) => void` | — | 初始化或启动失败回调 |
 | `onLog` | `(entry) => void` | — | 统一日志回调，覆盖 `[IVI-SEND]`、`[IVI-TRANSPORT]`、`[IVI-RECONNECT]`、`[IVI-EVT]`、`[IVI-STATE]`、`[IVI-TRTC]`、`[IVI-LIVEKIT]` |
 
@@ -516,6 +559,7 @@ function useIviSessionRuntime(config: UseIviSessionRuntimeConfig): UseIviSession
 | `websocket` | `IviRuntimeWebSocketOptions` | — | websocket 地址、query、protocols、socketFactory |
 | `runtimeConfig` | `IviRuntimeCoordinatorConfig` | — | 透传给 runtime |
 | `clientConfig` | `Omit<IviClientConfig, "transport">` | — | 透传给 `IviClient` 的非 transport 配置 |
+| `telemetry` | `IviFrontendTelemetryOptions` | — | 同时串联创建 session、runtime 和底层 WebSocket spans |
 | `enabled` | `boolean` | `true` | 是否启用 hook |
 | `autoStart` | `boolean` | `true` | 是否创建后自动调用 `runtime.start()` |
 | `onCreated` | `(session) => void` | — | HTTP 创建会话成功回调 |