jt-trace

火山引擎 DataRangers SDK 二次封装，提供一套简洁、可替换的分析上报接口。

为什么封装

| 问题 | 方案 | |------|------| | 直接调用 window.collectEvent("track", ...) 字符串拼写易错 | 语义化方法 tracker.track(...) / tracker.pageView(...) | | 火山引擎可能被替换 | 实现 AnalyticsProvider 接口即可切换平台 | | 微前端多应用需重复初始化 | 主应用 init() 后，子应用直接用 window.__tracker |

安装

npm install jt-trace

快速开始

主应用（shell）— 引入并初始化

import { tracker } from 'jt-trace';

tracker.init(10000005, {
  debug: true,
  channelDomain: 'https://snssdk.jtjms-br.com',
  autoFirstScreenTiming: true,   // 自动采集首屏时间，默认 true
});

// 语义化上报
tracker.track('button_click', { button_name: '登录' });
tracker.pageView({ pageName: '首页' });
tracker.identify('user_123');

子应用（微前端 — 无需安装包）

// 主应用 init() 后，window.__tracker 会自动可用
window.__tracker?.pageView({ pageName: '商品详情页' });
window.__tracker?.track('purchase', { amount: 99.9, currency: 'CNY' });

API 文档

tracker.init(appId, options?)

初始化追踪器。在主应用中调用一次即可。

| 参数 | 类型 | 说明 | 默认值 | |------|------|------|--------| | appId | string \| number | 火山引擎 App ID | 必传 | | options.provider | AnalyticsProvider | 自定义 provider | VolcEngineProvider | | options.channelDomain | string | 服务端上报域名 | — | | options.debug | boolean | 开启调试日志 | false | | options.extra | Record<string, unknown> | 透传给 SDK 的额外配置 | — | | options.windowKey | string | 挂载到 window 的属性名 | '__tracker' | | options.autoFirstScreenTiming | boolean | 自动采集首屏时间 | true |

// 最小化
tracker.init(10000005);

// 完整配置
tracker.init(10000005, {
  debug: true,
  channelDomain: 'https://snssdk.jtjms-br.com',
  autoFirstScreenTiming: true,
  extra: {
    disable_sdk_monitor: true,
    // sdkUrl: 'https://自建CDN地址/collect-privity-v5.x.x.js'  // 自定义 SDK 地址
  },
});

tracker.track(eventName, properties?)

上报自定义事件。

tracker.track('purchase', { amount: 99.9, currency: 'CNY' });
tracker.track('button_click');                          // 不带属性

tracker.pageView(properties)

上报页面浏览（PV）。

tracker.pageView({ pageName: '商品详情页' });

tracker.pageView({
  pageName: '商品详情页',
  pageUrl: '/product/10086',
  referrer: document.referrer,
});

tracker.identify(userId)

设置用户唯一标识（登录后调用）。用于 UV 统计。

// 用户登录后
tracker.identify('user_123');

// 用户登出（清除标识）
// 目前直接调用 collectEvent("logout")
// 如需暴露 resetIdentify()，从 tracker 实例获取

tracker.setProfile(properties)

设置用户属性。

tracker.setProfile({
  $user_name: '张三',
  $user_gender: '男',
  $user_age: 28,
  member_level: '金牌会员',
  register_channel: '应用商店',
});

tracker.reportFirstScreenTiming()

手动上报首屏加载时间。返回 Promise<number>。

const ms = await tracker.reportFirstScreenTiming();
console.log(`首屏时间: ${ms}ms`);

默认 autoFirstScreenTiming: true 时，init() 后会自动调用此方法。

首屏时间采集策略

| 优先级 | 方式 | 说明 | |--------|------|------| | 1 | LCP (PerformanceObserver) | 监听最大内容绘制，现代浏览器首选 | | 2 | Navigation Timing API | loadEventEnd - navigationStart 回退 | | 3 | DOMContentLoaded | 最终回退方案 |

上报事件名为 first_screen_timing，携带 duration（毫秒）和 page_url 属性。

替换为其他分析平台

实现 AnalyticsProvider 接口即可：

import type { AnalyticsProvider, InitConfig } from 'jt-trace';

class SensorsProvider implements AnalyticsProvider {
  init(config: InitConfig): void {
    // 初始化神策 SDK
  }
  track(eventName: string, properties?: Record<string, unknown>): void {
    // sensors.track(eventName, properties)
  }
  identify(userId: string): void { /* ... */ }
  resetIdentify(): void { /* ... */ }
  setProfile(properties: Record<string, unknown>): void { /* ... */ }
  destroy(): void { /* ... */ }
}

tracker.init(appId, { provider: new SensorsProvider() });
// 业务代码不用改！
tracker.pageView({ pageName: '首页' });

类型定义

interface AnalyticsProvider {
  init(config: InitConfig): void;
  track(eventName: string, properties?: Record<string, unknown>): void;
  identify(userId: string): void;
  resetIdentify(): void;
  setProfile(properties: Record<string, unknown>): void;
  destroy(): void;
}

interface InitConfig {
  appId: string | number;
  channelDomain?: string;
  debug?: boolean;
  extra?: Record<string, unknown>;
}

interface PageViewProperties {
  pageName: string;
  pageUrl?: string;
  referrer?: string;
  [key: string]: unknown;
}

开发

cd package

npm run build         # TypeScript 编译
npm run build:bundle  # ESM + IIFE 打包
npm run watch         # 监听模式

许可证

MIT