rsclick-log-sdk-web

用于 rs-click-log MVP 的轻量 Web 埋点 SDK。

目标：

• 在浏览器端生成并持久化 anonymous_id
• 自动维护 30 分钟 session_id
• 调用后端 POST /track/collect 上报事件
• 默认初始化后自动发送 $page_view
• 可选开启全局错误捕获并自动发送 $error
• 支持 SPA 场景下的路由切换自动发送 $page_view
• 登录态识别仅影响后续事件

目录

fronts/sdk-web
├── src
├── examples
├── tests
└── package.json

开发命令

cd fronts/sdk-web
bun test
npx -p typescript tsc --noEmit -p tsconfig.json
bun run build

Vue 示例：

cd fronts/sdk-web/examples/vue
npm install
npm run dev

输出产物

• dist/index.js: ESM 构建产物
• dist/index.global.js: 浏览器全局 bundle，暴露 window.TrackingAnalyticsSDK
• dist/index.d.ts: ESM 入口类型声明

初始化示例

import { init } from "rsclick-log-sdk-web";

await init({
    writeKey: "trk_live_xxx",
    endpoint: "https://your-api.example.com/track/collect",
});

默认行为：

- 初始化完成后自动发送当前页面的 `$page_view`
- 在 SPA 中监听 `history.pushState`、`history.replaceState`、`popstate`、`hashchange`
- 同一 URL 不会重复自动上报
- 默认不会自动捕获全局错误，如需开启请显式设置 `autoErrorCapture: true`

关闭默认 $page_view：

import { init } from "rsclick-log-sdk-web";

await init({
    writeKey: "trk_live_xxx",
    endpoint: "https://your-api.example.com/track/collect",
    autoPageview: false,
});

开启全局错误自动采集：

import { init } from "rsclick-log-sdk-web";

await init({
    writeKey: "trk_live_xxx",
    endpoint: "https://your-api.example.com/track/collect",
    autoErrorCapture: true,
});

开启后 SDK 会在浏览器层监听：

• window.error
• window.unhandledrejection

这套机制对 Vue、React、SolidJS、Next.js 都可用，因为依赖的是浏览器全局事件而不是框架私有 API。 如果你在框架内还使用了 ErrorBoundary、onErrorCaptured 等机制，仍然可以继续手动调用 track("$error") 补充业务上下文。

事件示例

import { track } from "rsclick-log-sdk-web";

await track("click_signup_button", {
    properties: {
        button_name: "立即注册",
        page_section: "hero",
    },
});

手动捕获错误并补充框架上下文：

import { captureError } from "rsclick-log-sdk-web";

try {
    throw new Error("checkout failed");
} catch (error) {
    await captureError(error, {
        source: "manual_try_catch",
        properties: {
            component: "CheckoutPage",
            action: "submit_order",
        },
    });
}

主动发送页面浏览事件：

import { page } from "rsclick-log-sdk-web";

await page({
    properties: {
        from: "manual-refresh",
    },
});

Identify 示例

import { identify, track } from "rsclick-log-sdk-web";

identify("user_123");

await track("submit_signup_form", {
    properties: {
        plan_type: "pro",
    },
});

identify 只影响后续事件，不会回溯历史匿名事件。

浏览器直接接入

<script src="/sdk/index.global.js"></script>
<script>
    TrackingAnalyticsSDK.init({
        writeKey: "trk_live_xxx",
        endpoint: "https://your-api.example.com/track/collect"
    }).then(function () {
        return TrackingAnalyticsSDK.track("landing_cta_click", {
            properties: {
                section: "hero"
            }
        });
    });
</script>

采集字段

SDK 默认上报以下字段：

• anonymous_id
• session_id
• user_id
• page_url
• page_path
• page_title
• referrer
• utm_source
• utm_medium
• utm_campaign
• properties

传输策略：

1. 统一使用 fetch(..., { mode: "cors", credentials: "omit", keepalive: true })
2. SDK 不再依赖 navigator.sendBeacon

当开启 autoErrorCapture 时，$error 事件默认会带上以下属性中的可用字段：

• error_kind：window_error 或 unhandledrejection
• message
• error_name
• filename
• lineno
• colno
• stack

手动调用 captureError() 时，还会额外带上：

• error_kind：固定为 captured_error
• source：手动传入的来源标识，默认值为 manual

框架接入示例

React Error Boundary：

import { captureError } from "rsclick-log-sdk-web";

export const AppErrorFallback = ({ error }: { error: Error }) => {
    void captureError(error, {
        source: "react_error_boundary",
        properties: {
            component: "AppErrorFallback",
        },
    });

    return <div>Something went wrong.</div>;
};

Vue 3 onErrorCaptured：

import { onErrorCaptured } from "vue";
import { captureError } from "rsclick-log-sdk-web";

onErrorCaptured((error, instance, info) => {
    void captureError(error, {
        source: "vue_on_error_captured",
        properties: {
            component: instance?.type?.name ?? null,
            info,
        },
    });

    return false;
});

SolidJS ErrorBoundary：

import { ErrorBoundary } from "solid-js";
import { captureError } from "rsclick-log-sdk-web";

<ErrorBoundary
    fallback={(error) => {
        void captureError(error, {
            source: "solid_error_boundary",
        });

        return <div>Something went wrong.</div>;
    }}
>
    <App />
</ErrorBoundary>;

Next.js app/error.tsx：

"use client";

import { useEffect } from "react";
import { captureError } from "rsclick-log-sdk-web";

export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
    useEffect(() => {
        void captureError(error, {
            source: "next_app_error",
            properties: {
                digest: error.digest ?? null,
            },
        });
    }, [error]);

    return <html><body>Something went wrong.</body></html>;
}

发布说明

当前 npm 包名为 rsclick-log-sdk-web。如果要发布到 npm，按下面步骤操作：

1. 进入 SDK 目录并执行发布前检查。

cd fronts/sdk-web
bun test
bun run build
npx -p typescript tsc --noEmit -p tsconfig.json
npm pack --dry-run

2. 登录 npm 并发布：

npm login
npm publish --access public

如果本机 ~/.npmrc 残留旧 token，优先清理后再登录，否则 npm publish 可能不会使用当前登录态。

当前包通过 files 字段控制发布内容，默认只会带上：

• dist
• README.md

如果只想内部使用，不需要发布到 npm，可以直接分发构建产物：

• dist/index.js
• dist/index.global.js
• dist/index.d.ts