Sentinel Video Player

Appearance

支持矩阵与发布运营 ​

摘自完整使用手册，构建时通过 @include 同步，避免站点与仓库规范漂移。

播放支持矩阵与发布运营：从原始 route 到可执行决策 ​

状态：当前 SDK 接入规范。适用 HLS / FLV / MP4、直播 / 点播和五种接入方式；不在 SDK 内定义业务 上报网络、告警供应商或固定 SLO 数字。

1. 先分清三件事 ​

问题只使用的事实不能用来回答
当前环境实际选中了什么、是否构造前不支持？sourceroute / summary.support是否已显示首帧。
这次启动是否真的开始展示画面？summary.startup播放期是否发生卡顿或后续错误。
用户观看过程是否健康？qoe、recovery、health signals是否支持某种候选源。

因此，support 不是 startup。HLS 被选中只说明路由成功；只有 firstframe 才是启动成功。 E_MEDIA_NOT_SUPPORTED 在 Player 创建前发生时仍会有 sourceroute.unsupported，不能因为没有 contextchange 就从矩阵中遗漏。

2. 宿主必须保存的低基数维度 ​

将完整原始 PlayerEvent 交给 createTelemetrySession()，并从 TelemetrySessionSummary 保存下列字段。 所有字段均来自 SDK 的 Zod 契约；不要从 URL 后缀、宿主传入候选顺序或 raw UA 补猜。

维度来源用途
support.outcome、candidateTypessourceroute计算“不支持候选源”的比率与补流优先级。
mediaType、kernelselected route / context说明实际播放的 HLS / FLV / MP4 与内核，而非配置意图。
streamKindselected route / context拆开直播与点播，避免用直播延迟解释点播首帧。
runtime.platform/browser/mseselected route / context只做 iOS / WebKit / MMS 等闭集分桶，不存 UA 或版本。
startup.status/evidence/errorCodesummary计算启动成功/失败/证据覆盖，定位确定失败原因。
application.release、sessionIdtelemetry对比 SDK 发布版本；sessionId 仅放 context/记录关联，不当指标 label。

禁止维度：完整 URL、query/hash、签名、cookie、用户 ID、任意业务 tag、错误文案和 raw UA。它们要么 泄露授权，要么制造无界基数。业务若要关联 CDN 或内容，应在自己的受控数据仓库按匿名内容/分发标识关联， 不要把该标识塞回 SDK telemetry。

3. 查询口径 ​

3.1 启动率：只以有结论的样本为分母 ​

sql
SELECT
  support.value.mediaType,
  support.value.kernel,
  support.value.streamKind,
  support.value.runtime.platform,
  application.release,
  COUNT(*) FILTER (WHERE startup.status = 'started') AS started,
  COUNT(*) FILTER (WHERE startup.status = 'failed') AS failed,
  COUNT(*) FILTER (WHERE startup.status = 'unknown') AS unknown,
  started::float / NULLIF(started + failed, 0) AS startup_success_rate,
  unknown::float / NULLIF(COUNT(*), 0) AS unknown_coverage
FROM player_session_summary
WHERE support.status = 'observed' AND support.value.outcome = 'selected'
GROUP BY 1, 2, 3, 4, 5;

unknown 不是失败，也不应被静默丢弃：它衡量事件送达、会话正常收口和量具覆盖是否足够。若某个版本或端的 unknown 突增，先查事件链、采样和生命周期，不要直接宣称播放质量下降。

3.2 路由不支持率：回答“缺哪一路流” ​

sql
SELECT
  support.value.candidateTypes,
  support.value.streamKind,
  support.value.runtime.platform,
  support.value.runtime.browser,
  COUNT(*) FILTER (WHERE support.value.outcome = 'unsupported') AS unsupported,
  COUNT(*) AS observed_routes,
  unsupported::float / NULLIF(observed_routes, 0) AS unsupported_rate
FROM player_session_summary
WHERE support.status = 'observed'
GROUP BY 1, 2, 3, 4;

例如 iOS / WebKit 上仅给 FLV 的 unsupported，是媒体供给缺 HLS 的信号，不是“FLV 内核故障”。中途 换源没有形成新 context 的失败尝试不会污染旧 summary；若要统计该类尝试，另从脱敏原始 sourceroute record 聚合。

3.3 failure reason 的使用方式 ​

startup 结论运营含义第一处排查
started / firstframe该会话确实显示过首帧之后的问题进入卡顿、错误与恢复报表。
failed / route_unsupported当前环境没有可用候选检查是否应提供 HLS 兜底或正确标注 type。
failed / nonretryable_error首帧前出现确定性错误按稳定 errorCode 联查内容编码、鉴权、CORS 或 CDN。
unknown证据不足，不能下播放结论查可重试链、用户离开、采样/上报丢失和 session 收口。

不要把 waiting、canplay、一次 playing、HLS non-fatal error 或“没有 error 事件”转成启动结论。

4. 灰度、停止与回滚 ​

SDK 不内置阈值；每个业务应按内容类型、直播/点播、端和历史基线设定门槛。发布前至少明确：

  1. 对照：上一稳定 application.release 与新 release，在同一 mediaType × kernel × streamKind × runtime bucket 比较；总体平均不能替代分桶比较。
  2. 样本资格：每个要做判断的 bucket 先声明最小样本量；样本不足只显示“未决”，不能因波动自动回滚。
  3. coverage 闸门：先确认 support observed 与 startup.unknown 的比例没有异常，再解释成功率；否则 是量具变化，不是可靠体验结论。
  4. 停止条件：当某个合格样本 bucket 的确定启动失败率、route 不支持率或首帧/卡顿分位数显著劣于其 基线时，停止扩大灰度。触发条件必须同时写出负责人和首个排查看板。
  5. 回滚动作：保留上一稳定 npm 包与 embed-app CDN 版本目录。iframe 场景同时回退 SDK 版本和实际 iframe URL；只降 npm 包而 iframe 仍指向新目录不算回滚。

灰度开关可以改变策略（例如是否启用某个恢复策略），但不得篡改 sourceroute、error 或 startup 的真实 事实。回滚后继续保留新旧 release 的样本，作为下一次发布的基线。

5. 上线前检查 ​

  • HLS / FLV / MP4、直播 / 点播，以及“仅 FLV 遇 iOS/WebKit”这类失败样本都有 route 证据。
  • 五种接入方式都从原始 onPlayerEvent / @player-event / embed.onAny 喂给同一 telemetry session。
  • support、startup、QoE 与 recovery 的 unknown/partial 没有被数据管道默认转换为 0 或 false。
  • 看板能从 release → runtime → kernel → media type → error code 逐层下钻，且不展示敏感 URL/用户数据。
  • 灰度负责人、最小样本量、停止条件、上一稳定版本和 iframe CDN 目录已经登记并演练。

关联 ​