中宣埋点 SDK

⚠️ 重要提示：本 SDK 基于 TypeScript 开发，所有 API 参数均带有明确的必填 / 选填类型标注。使用时请务必开启 TS 类型检查或在 IDE 中查看参数提示，必填项缺失会直接提示错误，选填项可按需传入，请勿忽略类型提示以避免使用异常。

功能特点

• 自动加载 QuickTracking（aplus）SDK，模块加载时仅注入一次
• 支持 web 端（aplus）和 kbapp 端（桥接）双通道上报，自动根据环境选择通道
• 提供稿件浏览、首页浏览、音视频播放、动作（点赞/转发）等内置事件模型
• 提供 useSessionTrackerPlan 会话管理，自动处理浏览开始/结束配对、动作上报及音视频播放计时
• 完全 TypeScript 支持，提供完整的类型定义

安装方式 1：npm

npm install @kbapp/scio-tracker

import { ScioTracker } from '@kbapp/scio-tracker';

// 创建实例（建议在应用入口处创建并导出，供其他模块复用）
const tracker = new ScioTracker({
  appKey: '由中宣后台分配',
  trackDomain: '由中宣后台分配的收数域名',
  enableLog: false, // 开发环境可设为 true，开启埋点日志输出
});

安装方式 2：通过 script 标签引入

通过 script 标签引入 @kbapp/js-bridge 通过 script 标签引入 @kbapp/scio-tracker

<script src="https://unpkg.com/@kbapp/js-bridge@latest/dist/umd/index.js"></script>
<script src="https://unpkg.com/@kbapp/scio-tracker@latest/dist/umd/index.js"></script>

<script>
// 通过全局变量创建实例
const tracker = new kbScioTracker.ScioTracker({
  appKey: '由中宣后台分配',
  trackDomain: '由中宣后台分配的收数域名',
  enableLog: false,
});
</script>

事件说明

| 事件名 | 说明 | |---|---| | ArticleVisitStartEvent | 上报《稿件详情页》浏览事件，当浏览《稿件详情页》时上报 | | ArticleVisitEndEvent | 上报《稿件详情页》浏览结束事件，当结束浏览《稿件详情页》时，或开始浏览下一篇《稿件详情页》/《首页》前触发 | | ArticleActionEvent | 上报稿件动作，当对《稿件详情页》进行分享、点赞时触发 | | ArticleActionResultEvent | 上报动作结果事件，上报 ArticleActionEvent 后紧跟着上报 | | ArticleTimerStartEvent | 上报《稿件详情页》中的音视频播放事件，当点击播放视频时触发 | | ArticleTimerEndEvent | 上报《稿件详情页》中的音视频暂停事件，当暂停音视频播放时触发 | | HomeVisitStartEvent | 上报《首页》浏览事件 | | HomeVisitEndEvent | 上报《首页》浏览结束事件 |

const tracker = new kbScioTracker.ScioTracker({
  appKey: '由中宣后台分配',
  trackDomain: '由中宣后台分配的收数域名',
  enableLog: false,
});

// 上报《稿件详情页》浏览事件
tracker.report(new ArticleVisitStartEvent({ article_id: '...', ... }))

// 上报《稿件详情页》浏览结束事件
tracker.report(new ArticleVisitEndEvent({ articleId: '...' }))

// 上报《稿件详情页》动作
tracker.report(new ArticleActionEvent({ button_name: '点赞', ... }))

// 上报《稿件详情页》动作结果事件
tracker.report(new ArticleActionResultEvent({ button_name: '点赞', button_status: '点赞', ... }))

// 上报《稿件详情页》音视频播放事件
tracker.report(new ArticleTimerStartEvent({ article_id: '...', ... }))

// 上报《稿件详情页》音视频暂停事件
tracker.report(new ArticleTimerEndEvent({ articleId: '...' }))

// 上报《首页》浏览事件
tracker.report(new HomeVisitStartEvent({ current_channel_name: '推荐', ... }))

// 上报《首页》浏览结束事件
tracker.report(new HomeVisitEndEvent({ current_channel_name: '推荐' }))

页面类型说明

• 《稿件详情页》：对应中宣 article_detail_pg，包括资讯专题、新闻稿件、活动页等，具体由产品定义
• 《首页》：对应中宣 home_pg，除上述页面外的其他页面

动作说明

目前仅支持两种动作：

| 动作 | 说明 | |---|---| | '点赞' | 点赞动作 | | '转发' | 转发动作 |

推荐使用 useSessionTrackerPlan

useSessionTrackerPlan 自动处理所有配对逻辑，无需手动管理 End 事件，也无需传递过多参数。

import { ScioTracker, useSessionTrackerPlan, ArticleVisitStartEvent, HomeVisitStartEvent } from '@kbapp/scio-tracker';

const tracker = new ScioTracker({ appKey: 'xxx', trackDomain: 'xxx' });
const session = useSessionTrackerPlan(tracker);

// 进入《稿件详情页》
session.reportVisit(new ArticleVisitStartEvent({
  current_page_name: '文章详情页',
  current_page_id: 'NEWS_NEO__ARTICLE',
  article_name: '稿件标题',
  article_type: '资讯文章',
  article_id: '12345',
  current_create_date: 1704067200000,
}));

// 对《稿件详情页》点赞 → 自动上报 Action + ActionResult
session.reportActionAuto({ buttonName: '点赞' });

// 对《稿件详情页》转发 → 自动上报 Action + ActionResult
session.reportActionAuto({ buttonName: '转发' });

// 《稿件详情页》点击播放音视频
session.reportTimerStart();

// 《稿件详情页》暂停音视频
session.reportTimerEnd();

// 切换到下一篇《稿件详情页》→ 自动结束上一篇，再上报新的 Start
session.reportVisit(new ArticleVisitStartEvent({ ... }));

// 进入《首页》→ 自动结束之前的《稿件详情页》
session.reportVisit(new HomeVisitStartEvent({
  current_page_name: '首页',
  current_page_id: 'home_pg',
  current_channel_name: '推荐',
}));

// 结束当前浏览（可选，下一个 reportVisit 会自动补 End）
session.reportEnd();

API 参考

ScioTracker 构造函数

new ScioTracker(config: {
  appKey: string;             // 中宣后台分配的应用 Key
  trackDomain: string;        // 收数域名
  enableDebugger?: boolean;   // 是否启用 QuickTracking 调试模式
  enableLog?: boolean;        // 是否开启内部日志输出，默认不开启
  onReportSuccess?: (payload: any) => void;      // 上报成功回调（web + kbapp）
  onWebReportSuccess?: (payload: any) => void;   // 上报成功回调（仅 web）
  onKbappReportSuccess?: (payload: any) => void; // 上报成功回调（仅 kbapp）
})