@wginit/uni-stat-sdk（uni-app 埋点 SDK）

支持 PV、UV（按天去重）、页面停留时长、自定义事件、失败离线缓存与重试、可选批量上报。

• 运行环境: uni-app（小程序、H5、App）
• 依赖: 无第三方依赖

新版（推荐）特性与用法概览

• 无侵入自动埋点：通过适配器拦截导航与 App 显隐，无需改动页面生命周期
• 核心无框架语法：核心库不包含任何 uni 语法，通过适配器适配到 uni/H5
• 轻量: 仅 5kb 大小

安装（npm）

npm i @wginit/uni-stat-sdk

uni-app 适配器（无侵入自动埋点）

// main.js 或 App.vue onLaunch 中
import {
    createUniAdapter,
    enableAutoPageTracking,
} from "@wginit/uni-stat-sdk/adapter/uni";

const { core } = createUniAdapter(
    "https://your.api.example.com/track",
    "your-app-id",
    config // 非必传
);
// 启用无侵入自动埋点（自动 PV、页面停留时长）
enableAutoPageTracking(core);

// 也可手动上报：
// core.trackEvent('buy_click', { skuId: '1001' });

config 的完整参数为

{
        appVersion: "1.0.0",
        debug: true,
        // 批量与离线重试（可选）
        batchMode: true,
        batchMax: 20,
        batchIntervalSec: 15,
        retryIntervalSec: 20,
        maxOffline: 200,
        // 初始用户与透传
        userId: "user-123",
        headers: { "X-Tenant-Id": "t_1" },
        extraContext: { channel: "mini_program" },
    }

H5（浏览器）环境使用

import { createBrowserEnv, AnalyticsCore } from "@wginit/uni-stat-sdk";

const { core } = createBrowserEnv(
    "https://your.api.example.com/track",
    "your-app-id"
);
core.trackPV(location.pathname);
core.trackEvent("buy_click", { skuId: "1001" });

1. 安装与引入

TypeScript/H5（ESM）：

import { createBrowserEnv, AnalyticsCore } from "@wginit/uni-stat-sdk";

uni-app 适配器（ESM/CJS）：

// ESM
import {
    createUniAdapter,
    enableAutoPageTracking,
} from "@wginit/uni-stat-sdk/adapter/uni";

// CJS
// const { createUniAdapter, enableAutoPageTracking } = require("@wginit/uni-stat-sdk/adapter/uni");

CDN（UMD，仅核心，不含 uni 适配器）：

<script src="https://unpkg.com/@wginit/uni-stat-sdk/dist/index.min.umd.js"></script>
<script>
    const { AnalyticsCore, createBrowserEnv } = window.UniStat;
    const { core } = createBrowserEnv("https://your.api.example.com/track");
    core.trackPV(location.pathname);
    core.trackEvent("buy_click", { skuId: "1001" });
    // UMD 仅提供核心；uni 适配器请走打包引入
</script>

2. 自动埋点（推荐）

新版推荐通过适配器的 enableAutoPageTracking(core) 实现无侵入自动埋点（拦截 navigateTo/redirectTo/reLaunch/switchTab/navigateBack 与 App 显隐），无需修改页面导出对象。

3. 手动埋点 API

• PV：

// 对于 uni 适配器：使用 core
core.trackPV("/pages/home/home", { from: "banner" });

• UV（按自然日去重）：

core.trackDailyUV();

• 页面时长：

// onShow
core.pageStart("/pages/home/home", { queryKey: "value" });
// onHide 或 onUnload
core.pageEnd();

• 自定义事件：

core.trackEvent("buy_click", { skuId: "1001", price: 99 });

• 批量上报控制：

// batchMode=true 时 SDK 会自动定时或按批量阈值上报
// 也可手动强制触发：
core.flush(true);

4. 上报数据格式

POST 到 reportUrl

• 请求头：

  • content-type: application/json
  • X-App-Id: <appId>

• 请求体：

{
    "events": [
        {
            "appId": "your-app-id",
            "appVersion": "1.0.0",
            "uid": "3f9f...",
            "userId": "user-123",
            "timestamp": "2024-01-01T10:00:00.000Z",
            "system": {},
            "eventType": "pv",
            "data": { "pagePath": "/pages/home/home" }
        }
    ]
}

各类事件 data：

• pv: { pagePath: string, ...extra }
• uv: { date: string }
• stay: { pagePath: string, durationMs: number }
• event: { eventName: string, properties?: Record<string, any> }

5. 失败重试与离线缓存

• 请求失败会缓存到本地（默认最多 200 条，可通过 maxOffline 配置）
• 周期性读取缓存尝试重放（retryIntervalSec）
• 批量模式下，队列会按 batchMax 或 batchIntervalSec 触发上报

6. 常见问题

• 路径获取：默认取 getCurrentPages() 最后一项的 route/$page.fullPath，可在 pageStart() 手动传入 pagePath 覆盖。
• 用户 ID：仅在显式调用 setUserId() 后携带 userId；匿名 uid 始终存在。
• 调试：debug: true 时打印日志，但不拦截上报。