blog-tracking-sdk

Blog页面埋点信息 SDK (单页面临时方案)。 支持自动采集：PageView, 15s有效停留, 滚动深度监听, 切后台/页面关闭上报。

特性

• 框架无关核心: SessionManager 统一管理会话生命周期。
• 多框架适配: 提供 React Hook 和 Vue Composable 开箱即用。
• 自动采集: 自动处理 referrer, device_type, os, browser 等环境信息。
• 网络解耦: 不依赖特定 HTTP 库，由业务方传入 requestFn。

埋点字段说明 (Data Dictionary)

SDK 会自动采集以下信息，并将其传递给您配置的 requestFn。

| 字段 (Field) | 类型 | 必填 | 说明 (Description) | 示例值 | 获取方式 | | :--- | :--- | :--- | :--- | :--- | :--- | | event_name | string | Y | 事件类型标识。page_view=进入页面; page_stay_end=离开页面 | page_view | SDK 自动生成 | | page_url | string | Y | 当前页面的完整 URL 地址 | https://site.com/news/123 | window.location.href | | page_path | string | N | URL 的路径部分，用于聚合分析 | /news/123 | window.location.pathname | | page_title | string | N | 页面标题。优先取传入值，否则取文档标题 | 震惊！某男子竟然... | detail.title || document.title | | page_type | string | Y | 页面/业务类型，目前固定为详情页 | news_detail | SDK 固定值 | | page_id | string | Y | 业务对象 ID (如文章ID、商品ID) | 10086 | 参数传入 id | | referrer | string | N | 来源页面 URL (上一跳地址) | https://google.com | document.referrer | | source | string | Y | 流量来源渠道。优先级：UTM参数 > Referrer判断 > Direct | search, social, direct | SDK 算法自动推导 | | device_type | string | N | 设备类型，区分移动端/桌面端 | mobile, desktop | UserAgent 正则匹配 | | os | string | N | 操作系统名称 | iOS, Android, Windows | UserAgent 正则匹配 | | browser | string | N | 浏览器名称 | Chrome, Safari | UserAgent 正则匹配 | | screen_width | number | N | 屏幕物理宽度 (px) | 390 | window.screen.width | | stay_duration | number | N | 页面停留时长 (秒)。仅 page_stay_end 有该值 | 150 | SDK 内部计时 | | end_reason | string | N | 会话结束原因。jump=跳转; close=关闭; background=切后台 | close | SDK 监听事件判断 | | is_effective | number | N | 是否有效阅读。1=有效(>15s或深滚动), 2=无效 | 1 | SDK 行为判断 |

安装

npm install blog-tracking-sdk
# 或
yarn add blog-tracking-sdk

快速上手

1. 全局初始化 (必须)

在项目入口文件（如 main.ts, App.tsx）中初始化单例。

import { BlogTracking } from 'blog-tracking-sdk';
import axios from 'axios';

// 初始化 SDK，传入发送请求的函数
BlogTracking.getInstance(async (payload) => {
  // 这里可以使用 axios, fetch, 或者 navigator.sendBeacon
  // payload 包含 event_name, page_url 等所有埋点数据
  
  if (payload.event_name === 'page_stay_end' && payload.end_reason === 'close') {
    // 页面关闭时建议使用 sendBeacon
    const blob = new Blob([JSON.stringify(payload)], { type: 'application/json' });
    navigator.sendBeacon('/api/pv/event/save', blob);
  } else {
    return axios.post('/api/pv/event/save', payload);
  }
});

2. React 项目使用

在新闻详情页组件中使用。

import { useNewsTracking } from 'blog-tracking-sdk/react';

const NewsDetail = ({ detail }) => {
  // 传入埋点详情对象
  // SDK 会自动处理 start/stop/scroll/visibility 逻辑
  useNewsTracking({
    id: detail.id,
    title: detail.title,
  });

  return (
    <div>
      <h1>{detail.title}</h1>
      {/* ... */}
    </div>
  );
};

3. Vue 项目使用

在 Setup 中使用，支持响应式 Ref。

<script setup lang="ts">
import { toRefs } from 'vue';
import { useNewsTracking } from 'blog-tracking-sdk/vue';

const props = defineProps<{ detail: any }>();
const { detail } = toRefs(props);

// 传入 Ref，当 detail 变化时会自动重启新的会话
useNewsTracking(detail);
</script>

NPM 发布指南

如果您拥有本包的源码并希望发布新版本：

1. 登录 NPM (仅需一次)

   npm login
   # 确保源是 https://registry.npmjs.org/

2. 构建

   npm run build

3. 更新版本

   npm version patch # 0.0.1 -> 0.0.2
   # npm version minor # 0.1.0
   # npm version major # 1.0.0

4. 发布

   npm publish --access public