@stringzhao/analytics-sdk
v0.1.2
Published
轻量数据统计接入封装，用于 stringzhao 名下 Vercel 应用的统一分析接入。后端委托官方 `@umami/node`（自托管 Umami），浏览器端自研 `<Analytics/>` script 注入 + `track()` 事件上报。
Readme
@stringzhao/analytics-sdk
轻量数据统计接入封装，用于 stringzhao 名下 Vercel 应用的统一分析接入。后端委托官方 @umami/node（自托管 Umami），浏览器端自研 <Analytics/> script 注入 + track() 事件上报。
安装
npm install @stringzhao/analytics-sdk
# peer: next >= 15, react >= 19配置环境变量
浏览器端（暴露到客户端）：
NEXT_PUBLIC_UMAMI_HOST=https://umami.example.com
NEXT_PUBLIC_UMAMI_WEBSITE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx服务端（不暴露到客户端，用于服务端事件上报）：
UMAMI_HOST=https://umami.example.com/api/send
UMAMI_WEBSITE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
UMAMI_HOST指向 Umami 的/api/send端点（由@umami/node的hostUrl约定）。NEXT_PUBLIC_UMAMI_HOST指向 Umami 根域名（脚本注入用${host}/script.js）。
浏览器接入
// app/layout.tsx
import { Analytics } from "@stringzhao/analytics-sdk";
export default function RootLayout({ children }) {
return (
<html>
<body>
{children}
<Analytics /> {/* 读 NEXT_PUBLIC_ env，未配置时渲染 null */}
</body>
</html>
);
}import { track } from "@stringzhao/analytics-sdk";
track("button_click", { label: "signup" }); // SSR 安全：无 window 时 no-op服务端接入（容错，永不阻塞主流程）
import { trackServerEvent } from "@stringzhao/analytics-sdk";
// 任何错误（网络/配置/客户端 reject）都被 catch，Promise 永远 resolve。
await trackServerEvent("login_success", { method: "email" });API
| 导出 | 说明 |
| --- | --- |
| Analytics(props?: { host?, websiteId?, src? }) | React 组件，next/script（strategy afterInteractive）注入 Umami script |
| track(name, props?) | 浏览器端事件，委托 window.umami.track，SSR/未加载时 no-op |
| trackServerEvent(name, props?) | 服务端事件，委托 @umami/node，全错误 catch |
| TrackProps | Record<string, string \| number \| boolean> |
| AnalyticsConfig | { host: string; websiteId: string } |