CITV 数据采集

@citv-cn/citv-live-analytics-sdk 是用于采集直播间页面访问数据的轻量级 Web SDK。直播间页面每次加载时调用一次 init，SDK 会记录本次页面访问并自动上报至 CITV，用于统计页面访问量（PV）和独立访客数（UV）。

参考资料

npm

查看 SDK 安装方式与使用说明

GitHub

查看 SDK 源代码

一、安装 SDK

在直播间前端项目中安装依赖：

npm install @citv-cn/citv-live-analytics-sdk

二、初始化

在直播间页面加载时导入 SDK，并调用一次 analytics.init：

import { analytics } from "@citv-cn/citv-live-analytics-sdk";

analytics.init({
  appid: "app-1",
  ccid: "room-001",
});

初始化参数

参数名	类型	必填	说明
`appid`	string	是	CITV 分配的应用唯一标识
`ccid`	string	是	当前直播间的唯一标识

每次加载直播间页面只需调用一次 init。如果是单页应用，请在进入直播间页面、且 appid 和 ccid 已经准备好之后调用。

三、数据上报

初始化后，SDK 会向以下固定地址发送 POST 请求，无需业务方自行拼装请求：

https://checker.citv.cn/api/v2/analytics/page-views

上报数据格式如下：

{
  "appid": "app-1",
  "ccid": "room-001",
  "visitor_id": "de840a34-fad8-410c-af35-aec2078d10fa",
  "event_id": "3f242e95-cbd7-44c8-b73b-7912db97300f",
  "occurred_at": "2026-08-14T07:30:00.000Z",
  "page_url": "https://checker.citv.cn/live/room-001"
}

上报字段

字段名	说明
`appid`	初始化时传入的应用唯一标识
`ccid`	初始化时传入的直播间唯一标识
`visitor_id`	访客唯一标识，首次生成后持久化到浏览器 `localStorage`
`event_id`	本次访问事件的唯一标识，每次调用 `init` 时重新生成
`occurred_at`	事件发生时间，采用 ISO 8601 格式
`page_url`	发生访问事件时的完整页面地址

四、PV 与 UV 统计规则

PV（页面访问量）：每次成功上报计为一次 PV。
UV（独立访客数）：服务端根据持久化的 visitor_id 去重计算。
刷新页面时，visitor_id 保持不变，但调用 init 会生成新的 event_id，因此会产生新的 PV。

五、上报机制

为平滑服务端瞬时流量，SDK 不会在初始化后立即发出请求，而是在 3–5 分钟的随机延迟 后使用 fetch 和 keepalive 顺序发送。

如果用户在延迟期间切换页面、关闭标签页或将页面置于后台，SDK 会在页面隐藏时优先使用 navigator.sendBeacon 发送待上报事件；发送失败时会自动回退到 fetch。

请确保直播间页面允许访问 https://checker.citv.cn。如果项目配置了内容安全策略（CSP），需要将该域名加入 connect-src 白名单；同时不要在上报完成前清除 SDK 写入的 localStorage 数据，否则可能影响 UV 去重结果。

六、接入检查

接入完成后，可按以下步骤确认数据采集是否正常：

打开直播间页面，确认初始化使用了正确的 appid 和 ccid。
在浏览器开发者工具的 Network 面板中筛选 page-views 请求。
等待 3–5 分钟，或在页面加载后将页面切换到后台，检查是否发起上报。
确认请求地址为 CITV 固定上报地址，且请求体包含 visitor_id、event_id、occurred_at 和 page_url。

CITV 数据采集

npm

GitHub

On this page