开吧融媒体上报平台

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

功能特点

• 融合个推（Gsido）、天目云（Tmuyun） 和 中宣（Scio） 三平台埋点上报能力
• 一次调用 reportVisit 自动向三个平台同时上报稿件浏览事件
• 动作事件自动路由：个推全量上报，中宣仅上报点赞/转发等标准动作
• 内置 DocVisitStartEvent 统一事件模型，自动为各平台生成对应载荷
• 异步加载核心上报 SDK，避免包体积过大
• 完全 TypeScript 支持，提供完整的类型定义

安装方式 1：npm

npm install @kbapp/media-fusion-tracker

import { MediaFusionTracker } from '@kbapp/media-fusion-tracker';

const kbTracker = new MediaFusionTracker({
  gsidoTracker: {
    sdkUrl: 'https://page.kaiba315.com.cn/js/gsido-h5-min-1.0.7.1_final.js',
    appid: '由开吧分配',
    enableLog: false, // 开发环境可设为 true，开启个推埋点日志
  },
  scioTracker: {
    appKey: '由中宣分配',
    trackDomain: '收数域名',
    enableLog: false, // 开发环境可设为 true，开启中宣埋点日志
  },
  tmuyunTracker: {
    enableLog: false, // 开发环境可设为 true，开启天目云埋点日志
  },
});

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

通过 script 标签引入后，SDK 将作为全局变量 kbMediaFusionTracker 挂载在 window 对象上

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

<script>
const kbTracker = new kbMediaFusionTracker.MediaFusionTracker({
  gsidoTracker: {
    sdkUrl: 'https://page.kaiba315.com.cn/js/gsido-h5-min-1.0.7.1_final.js',
    appid: '由开吧分配',
    enableLog: false,
  },
  scioTracker: {
    appKey: '由中宣分配',
    trackDomain: '收数域名',
    enableLog: false,
  },
  tmuyunTracker: {
    enableLog: false,
  },
});
</script>

基本使用

如何设置全局公共属性（个推）

设置全局公共属性后，所有上报到个推的埋点将自动携带这些属性。

kbTracker.setReportGlobalAttrs({
  userId: '123456',      // 用户唯一标识
  platform: 'h5',        // 平台类型（h5/ios/android）
  appVersion: '1.0.0',   // APP版本号
});

// 支持多次调用，属性将合并
kbTracker.setReportGlobalAttrs({
  channel: 'official',
});

如何上报稿件浏览事件

调用 reportVisit 一次调用，同时上报到个推、天目云和中宣三个平台。

import { DocVisitStartEvent } from '@kbapp/media-fusion-tracker';

kbTracker.reportVisit(new DocVisitStartEvent({
  biz: 'NEWS_NEO',                        // 业务类型（必填）
  title: '稿件标题',                       // 稿件标题（必填）
  pubTime: 1700000000000,                 // 稿件发布时间戳（必填）
  ref1: 'article_id',                     // 对象标识1（必填）
  unit: 'ARTICLE',                        // 业务单元（选填）
  ref2: 'sub_id',                         // 对象标识2（选填）
  ref3: 'detail',                         // 对象标识3（选填）
  sid: 1,                                 // 站点ID（选填）
  channel: '所属单位',                     // 所属单位（选填）
  depart: '所属部门',                      // 所属部门（选填）
  authorName: '记者姓名',                  // 稿件作者（选填）
  referer: '来源页面稿件标识',              // 访问来源（选填）
  suid: '分享人用户ID',                    // 分享人ID（选填）
}));

DocVisitStartEvent 内部会自动为各平台生成对应载荷：

• 个推：生成 DocVisitEvent，docId 按 biz-unit-ref1-ref2-ref3-sid 规则拼接
• 天目云：生成 DocVisitEvent，docId 同上
• 中宣：根据业务类型自动判断上报 ArticleVisitStartEvent（稿件类）或 HomeVisitStartEvent（首页/非稿件类）

如何上报稿件动作事件

调用 reportAction 上报动作，自动路由到个推和中宣（仅限标准动作）。

// 点赞 → 个推全量上报 + 中宣上报（自动映射为"点赞"动作）
kbTracker.reportAction({ act: 'like' });

// 分享 → 个推全量上报 + 中宣上报（自动映射为"转发"动作）
kbTracker.reportAction({ act: 'share' });

// 评论 → 仅个推上报（中宣无评论动作，自动忽略）
kbTracker.reportAction({ act: 'reply' });

// 自定义动作 → 仅个推上报
kbTracker.reportAction({ act: 'vote' });

标准动作标识参考：

| 动作 | 标识 | 个推 | 中宣 | |------|------|:----:|:----:| | 点赞 | like | ✅ | ✅ | | 分享 | share | ✅ | ✅ | | 评论 | reply | ✅ | — | | 评论的评论 | reply_r | ✅ | — | | 评论的点赞 | reply_l | ✅ | — | | 投票 | vote | ✅ | — | | 签到 | sign | ✅ | — | | 购买 | buy | ✅ | — | | 打赏 | reward | ✅ | — |

如何上报结束事件

调用 reportEnd 结束当前稿件浏览会话，仅上报到中宣。

// 一般无需手动调用，reportVisit 切换稿件时会自动结束上一个会话
kbTracker.reportEnd();

事件路由规则

| 方法 | 个推（Gsido） | 天目云（Tmuyun） | 中宣（Scio） | |------|:---:|:---:|:---:| | reportVisit | ✅ | ✅ | ✅ | | reportAction | ✅ | — | ✅（仅 like/share） | | reportEnd | — | — | ✅ |

API 参考

MediaFusionTracker 类

构造函数

constructor(params: {
  gsidoTracker: GsidoTracker | {
    sdkUrl: string;         // 个推 SDK URL
    appid: string;          // 个推应用ID，由开吧分配
    enableDebugger?: boolean; // 是否开启个推调试模式
    enableLog?: boolean;      // 是否开启个推日志
  };
  scioTracker: ScioTracker | {
    appKey: string;         // 中宣应用 appKey
    trackDomain: string;    // 中宣收数域名
    enableDebugger?: boolean; // 是否开启中宣调试模式
    enableLog?: boolean;      // 是否开启中宣日志
  };
  tmuyunTracker: TmuyunTracker | {
    enableLog?: boolean;    // 是否开启天目云日志
  };
})

传入已有实例

gsidoTracker、scioTracker 和 tmuyunTracker 除了接受配置对象自动创建实例外，还支持直接传入已有的 Tracker 实例。适用于项目中已经在其他地方初始化了 Tracker、希望与 MediaFusionTracker 共享同一实例的场景：

import { MediaFusionTracker } from '@kbapp/media-fusion-tracker';
import { GsidoTracker } from '@kbapp/gsido-tracker';
import { ScioTracker } from '@kbapp/scio-tracker';
import { TmuyunTracker } from '@kbapp/tmuyun-tracker';

// 项目中已有的实例
const gsidoTracker = new GsidoTracker({ sdkUrl: '...', appid: '...' });
const scioTracker = new ScioTracker({ appKey: '...', trackDomain: '...' });
const tmuyunTracker = new TmuyunTracker({ enableLog: true });

// 直接传入实例，MediaFusionTracker 将复用这些实例
const kbTracker = new MediaFusionTracker({
  gsidoTracker,
  scioTracker,
  tmuyunTracker,
});

传入实例时，配置对象中的 enableLog / enableDebugger 等字段不生效（由实例自身的配置决定），仅对内部自动创建的实例有效。

属性

gsidoTracker

个推埋点实例，可直接调用个推 SDK 的更多方法。

kbTracker.gsidoTracker.report({
  name: 'custom_event',
  params: { key: 'value' },
});

tmuyunTracker

天目云埋点实例，可直接调用天目云 SDK 的更多方法。

kbTracker.tmuyunTracker.report({
  docId: 'xxx',
  title: '标题',
  pubTime: 1700000000000,
});

scioTracker

中宣埋点实例，可直接调用中宣 SDK 的更多方法。

kbTracker.scioTracker.report(event);

scioTrackerPlan

中宣会话管理方案，可直接调用中宣会话的更多方法。

kbTracker.scioTrackerPlan.reportAction({ buttonName: '点赞' });
kbTracker.scioTrackerPlan.reportActionResult({ buttonName: '点赞', success: true });

kbDocTrackerPlan

个推文档埋点方案，管理个推侧的稿件上下文和动作上报。

kbTracker.kbDocTrackerPlan.getCurrentUrlDoc();

方法

setReportGlobalAttrs

设置全局公共属性（个推），将附加到所有上报到个推的事件中。

setReportGlobalAttrs(attrs: Record<string, any>): void

reportVisit

上报稿件浏览事件，同时上报到个推、天目云和中宣三个平台。

reportVisit(event: DocVisitStartEvent): void

reportAction

上报稿件动作事件。个推全量上报；中宣仅上报 like/share 标准动作（自动映射为中宣的点赞/转发），其他动作自动忽略。

reportAction(params: { act: string }): void

reportEnd

上报结束事件，仅上报到中宣。一般无需手动调用，reportVisit 切换稿件时会自动结束上一个会话。

reportEnd(): void

DocVisitStartEvent 类

统一事件模型，构造后通过内部方法自动为各平台生成载荷。

new DocVisitStartEvent(params: {
  biz: string;          // 业务类型（必填）
  title: string;        // 稿件标题（必填）
  pubTime: number;      // 稿件发布时间戳（必填）
  ref1: string;         // 对象标识1（必填）
  unit?: string;        // 业务单元
  ref2?: string;        // 对象标识2
  ref3?: string;        // 对象标识3
  sid?: number;         // 站点ID
  channel?: string;     // 所属单位
  depart?: string;      // 所属部门
  authorName?: string;  // 稿件作者
  referer?: string;     // 访问来源
  suid?: string;        // 分享人用户ID
})

最佳实践

1. 全局唯一实例：建议在应用入口处创建一个全局唯一的 MediaFusionTracker 实例
2. 合理使用全局属性：将通用信息（如用户 ID、平台等）设置为全局属性（个推）
3. 开发环境开启调试：在开发环境设置 enableLog: true 以查看埋点日志
4. 复用标准动作标识：reportAction 中的 act 字段有标准值，语义相同时应复用（如点赞使用 like），以便自动同步到中宣
5. 共享已有实例：若项目中已初始化了 GsidoTracker / ScioTracker / TmuyunTracker，可直接传入实例以避免重复初始化

注意事项

1. gsidoTracker、scioTracker 和 tmuyunTracker 均为必需参数，可传入配置对象（内部自动创建）或已有实例
2. reportVisit 传入的 DocVisitStartEvent 会自动判断稿件类型：符合稿件定义的走中宣 ArticleVisitStartEvent，否则走 HomeVisitStartEvent
3. reportAction 中只有 like 和 share 会同步到中宣，其他动作仅个推上报
4. reportEnd 一般无需手动调用，切换稿件时 reportVisit 会自动结束上一个会话