datareportjs

DataReportJS

数据上报 JavaScript SDK，统一事件上报格式，支持浏览器/设备信息自动采集、自动埋点、版本注入与 UMD/ESM 双产物，适配 React/TS 项目。

安装

npm i datareportjs
# or
yarn add datareportjs
# or
pnpm add datareportjs

浏览器（CDN / 本地构建产物）：

<script src="./dist/datareport.min.js"></script>
<script>
  const dr = new window.DataReport({ serverUrl: 'https://your-endpoint' });
  dr.autoTrack({ appLaunch: true, pageView: true });
  dr.track('custom_event');
  </script>

快速开始（ESM / React / TS）

import DataReport from 'datareportjs';

const dr = new DataReport({
  serverUrl: 'https://your-endpoint',
  appKey: 'your-app-key',     // 可选，用于请求头 AppKey
  uuid: 'your-uuid',          // 可选，不传则自动生成并持久化
  debug: true                 // 可选，开启调试日志
});

dr.autoTrack({ appLaunch: true, pageView: true, click: true });

dr.track('deposit_popup', {
  cdid: '10002',
  'pop-up_type': 4,
  app_version: '1.6.2',
  '#title': document.title,
  '#url': location.href
});

在 React 中建议将 dr 作为单例放在模块级或依赖注入，组件内直接调用 dr.track。

统一上报格式

SDK 每次上报都会生成如下结构（简化示例）：

{
  "uid": "<uuid>",
  "flt": 1754447545,
  "session": "<session-uuid>",
  "ssid": "<ssid>",
  "zo": 480,
  "lang": "en",
  "width": 390,
  "height": 844,
  "sdk": 2,
  "sdkv": "1.0",
  "adtk": 1,
  "os": "iPhone",
  "osi": 0,
  "osv": "18.5",
  "dtype": 1,
  "brand": "Apple",
  "model": "iPhone",
  "ts": 1757909194663,
  "sco": 1,
  "bps": {
    "#platform": "H5",
    "#browser": "Mobile Safari",
    "#browserv": "18.5",
    "#duration": "",
    "#referrer": "https://example.com/",
    "#title": "Page Title",
    "#url": "https://example.com/profile"
  },
  "events": [
    {
      "ts": 1757909190570,
      "eid": "deposit_popup",
      "cdid": "10002",
      "props": {
        "pop-up_type": 4,
        "#title": "title",
        "#url": "https://example.com/profile"
      }
    }
  ]
}

• flt 字段记录 SDK 在页面的首次加载时间（Unix 时间戳），使用 sessionStorage 存储，直到用户刷新页面才重新计算。
• os 字段直接使用 navigator.platform 的值（如 "iPhone", "Win32", "MacIntel"），osi 为原来的数字逻辑值（0 iOS, 1 Android, 2 Windows, 3 MacOS, 4 Linux, 9 Unknown），osv 从 userAgent 提取版本号。
• bps 包含丰富的页面和浏览器信息，所有字段均使用 # 开头：
  • #platform：系统平台（H5）
  • #browser/#browserv：浏览器名称和版本
  • #duration：事件时长（由具体事件设置）
  • #referrer/#title/#url：来源地址、页面标题、完整 URL

API

new DataReport(options)

• serverUrl: string（必填）上报地址
• appKey: string（可选）用于请求头 AppKey 字段
• debug: boolean（可选）是否打印调试日志
• uuid: string（可选）手动设置 uid；不传则自动生成并持久化
• sdk: number（可选）SDK 标识，默认 1（可自定义）
• baseProps: Record<string, any>（可选）补充到 bps 的自定义属性

注：构建时通过 Rollup @rollup/plugin-replace 将 __APP_VERSION__ 注入到 SDK 内部，作为 AppVersion 默认值，参与 bps.app_version 与请求头 AppVersion。

setContext(context)

• 动态更新上下文，如登录后变更 uuid 等。
• 若传入 AppVersion，将更新内部 appVersion，但不会写入 envOptions。

setUserProperties(properties)

• 设置用户级属性，在后续 track 的 props 中自动合并。

getUserProperties()

• 读取当前用户属性。

track(eventName, properties)

• 发送单条事件，按统一结构封装为 events: [{...}] 并立即上报。
• 支持 cdid 字段；props 与 setUserProperties 合并。
• 请求头会包含：Content-Type: application/json、AppKey（如实例化时传入）、AppVersion。

autoTrack(config)

• 内置常用事件：appLaunch、appShow、appHide、pageView、click
• 自动事件会携带 #title、#url 等常用属性；click 还包含 tagName、id、className。

版本注入与打包

• 已在 rollup.config.mjs 集成：
  • @rollup/plugin-replace 将 package.json.version 注入为 __APP_VERSION__
  • 产物：dist/datareport.min.js（UMD）与 dist/datareport.esm.js（ESM）
• 在浏览器请求头里会携带 AppVersion: <version>；同时 bps.app_version 也使用该版本。

TypeScript 支持

• 提供 types/index.d.ts 类型声明，exports 已配置 types，开箱即用。

在 React 中使用建议

• 在应用入口创建单例 dr，在路由切换时调用 dr.track('pageView', {...})。
• 结合框架路由监听或埋点中间件，统一触发上报。

Demo

• 仓库内提供 demo.html，可本地打开测试，上屏展示 Headers/Body/Response 片段。

发布到 npm（可选）

npm login
npm version patch   # or minor / major
npm run build
npm publish         # 确保 package.json 未设置 private: true

许可证

ISC