开吧App埋点平台

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

功能特点

• 异步加载核心上报SDK，避免包体积过大
• 支持全局公共属性设置
• 提供普通事件和持续事件（开始/结束）上报
• 完全TypeScript支持，提供完整的类型定义

安装方式 1：npm

npm install @kbapp/gsido-tracker

import { GsidoTracker } from '@kbapp/gsido-tracker';

// 创建实例（建议在应用入口处创建并导出，供其他模块复用）
const tracker = new GsidoTracker({
  sdkUrl: 'https://page.kaiba315.com.cn/js/gsido-h5-min-1.0.7.1_final.js',
  appid: '由开吧分配',
  enableLog: false, // 开发环境可设为 true，开启埋点日志输出
});

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

请先引入 JS Bridge：<script src="https://unpkg.com/@kbapp/js-bridge@latest/dist/umd/index.js"></script>，再引入本 SDK。

使用 unpkg CDN：

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

使用 jsdelivr CDN：

<script src="https://cdn.jsdelivr.net/npm/@kbapp/gsido-tracker@latest/dist/umd/index.js"></script>

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

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

<script>
// 通过全局变量创建实例
const tracker = new kbGsidoTracker.GsidoTracker({
  sdkUrl: 'https://page.kaiba315.com.cn/js/gsido-h5-min-1.0.7.1_final.js',
  appid: '由开吧分配',
  enableLog: false, // 开发环境可设为 true，开启日志输出
});
</script>

基本使用

1. 如何上报普通事件

// 基本事件上报
tracker.report({
  name: 'page_view', // 事件名称
  params: {
    pageId: 'home_page',
    stayTime: 1000,
    // 其他自定义参数...
  },
});

2. 如何设置全局公共属性

// 设置全局公共属性后, 所有上报的埋点将自动携带全局公共属性
tracker.setReportGlobalAttrs({
  userId: '123456', // 用户唯一标识
  platform: 'h5',   // 平台类型（h5/ios/android）
  appVersion: '1.0.0', // APP版本号
});

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

3. 如何上报持续事件

// 上报 开始持续事件
tracker.reportBeginEvent({
  name: 'video_play',
  params: {
    videoId: 'v001',
    startTime: Date.now(),
  },
});

// 上报 结束持续事件（需要与开始事件使用相同的事件名）
tracker.reportEndEvent({
  name: 'video_play',
  params: {
    videoId: 'v001',
    endTime: Date.now(),
    duration: 60000,
  },
});

API 参考

GsidoTracker

构造函数

new GsidoTracker(params: {
  sdkUrl: string; // 个推SDK地址
  appid: string; // 埋点应用ID
  debugger?: boolean; // 是否开启个推SDK调试模式
  enableLog?: boolean; // 是否开启内部日志输出，默认不开启
})

方法

report

上报普通事件

tracker.report(params: {
  name: string; // 事件名称
  params?: Record<string, string | number | boolean>; // 事件参数
}): void

setReportGlobalAttrs

设置全局公共属性，将附加到所有上报事件中

tracker.setReportGlobalAttrs(attrs: Record<string, string | number | boolean> = {}): void

reportBeginEvent

上报持续事件的开始

tracker.reportBeginEvent(params: {
  name: string; // 事件名称
  params?: Record<string, string | number | boolean>; // 事件参数
}): void

reportEndEvent

上报持续事件的结束

tracker.reportEndEvent(params: {
  name: string; // 事件名称（需与开始事件相同）
  params?: Record<string, string | number | boolean>; // 事件参数
}): void

getGsido

获取原始的 GsIdo 对象

tracker.getGsido(): Promise<typeof GsIdo>

最佳实践

1. 全局唯一实例：建议在应用入口处 new GsidoTracker({...}) 并 export，其他模块直接 import 复用
2. 合理使用全局属性：将通用信息（如用户ID、平台等）设置为全局属性
3. 开发环境开启调试：在开发环境设置enableLog: true以查看埋点日志

注意事项

上报数据类型严格一致

⚠️ 个推埋点后台对字段类型有严格限制：某个字段首次上报的类型是什么，后续就只能上报相同类型，否则该次埋点会静默失败（前端不会报错，无法感知）。

例如首次 report({ params: { ep: 1 } })，ep 被记录为 number 类型，后续再传 report({ params: { ep: '1' } }) 或 report({ params: { ep: true } }) 都会失败。

SDK 内部会自动进行以下处理来降低出错概率：

• 类型过滤：只保留 number（有限值）、string、boolean，其他类型（null、undefined、NaN、Infinity、object、function）会被自动剔除
• 类型规范化：对内置已知字段（如 ep、docId、pubTime 等），会自动尝试转换为正确的目标类型，转换失败则剔除
• 日志提醒：发生类型转换或剔除时，会在控制台输出警告（console.error），帮助及时发现并修正

但自动处理不能替代正确的数据构造，请在上报时确保字段类型稳定。

其他

1. sdkUrl和appid是必需参数，需要正确配置