onerway-analytics 1.0.2 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # onerway-analytics
 
-客户端埋点 SDK，支持双发：自建数据服务 + Google Analytics 4。
+客户端埋点 SDK，支持双发：自建数据服务 + Google Tag Manager（GTM）。
 
 ## 安装
 
@@ -14,6 +14,7 @@ npm install onerway-analytics
 
 ```html
 <script src="./dist/bundle/index.js"></script>
+<!-- 全局变量：window.OnrwayAnalytics -->
 ```
 
 ---
@@ -24,66 +25,58 @@ npm install onerway-analytics
 import { createAnalytics } from 'onerway-analytics';
 
 const analytics = createAnalytics({
-  appKey: 'your-app-key',            // 应用标识
-  serverUrl: 'https://your-server.com/collect', // 数据接收端点
-  env: 'prod',                       // 环境: beta | test | uat | prod
-  debug: true,                       // 开启控制台日志
+  appKey:    'your-app-key',
+  serverUrl: 'https://your-server.com/collect',
+  env:       'prod',
+  debug:     true,
 });
 ```
 
 ### 上报模式
 
-SDK 支持三种上报模式，按需选择。
-
-#### 双发（自建 + GA）
-
-同时发送到自建服务和 Google Analytics 4：
+#### 双发（自建服务 + GTM）
 
 ```ts
 const analytics = createAnalytics({
-  appKey: 'your-app-key',
+  appKey:    'your-app-key',
   serverUrl: 'https://your-server.com/collect',
-  env: 'prod',
-  ga: {
-    measurementId: 'G-XXXXXXXXXX',
-    enabled: true,
-    sendPageView: false,
-    debugMode: true,
+  env:       'prod',
+  gtm: {
+    containerId: 'GTM-XXXXXXX',
+    enabled:     true,
   },
 });
 ```
 
 #### 只发自建服务
 
-不配置 `ga`，或设置 `ga.enabled: false`：
+不配置 `gtm`，或设置 `gtm.enabled: false`：
 
 ```ts
 const analytics = createAnalytics({
-  appKey: 'your-app-key',
+  appKey:    'your-app-key',
   serverUrl: 'https://your-server.com/collect',
-  env: 'prod',
-  debug: true,
+  env:       'prod',
 });
 ```
 
-#### 只发 GA
+#### 只发 GTM
 
-设置 `disableServer: true`，`serverUrl` 可留空。page_view、自动埋点、错误监控、性能指标均只走 GA：
+设置 `disableServer: true`，`serverUrl` 可留空，所有事件只推入 dataLayer：
 
 ```ts
 const analytics = createAnalytics({
-  appKey: 'your-app-key',
-  serverUrl: '',
+  appKey:        'your-app-key',
+  serverUrl:     '',
   disableServer: true,
-  ga: {
-    measurementId: 'G-XXXXXXXXXX',
-    enabled: true,
-    debugMode: true,
+  gtm: {
+    containerId: 'GTM-XXXXXXX',
+    enabled:     true,
   },
 });
 ```
 
-> `disableServer` 开启后 `analytics.flush()` 和自动缓冲机制均不生效。
+> `disableServer: true` 时，`analytics.flush()` 和重试机制均不生效。
 
 ---
 
@@ -93,68 +86,58 @@ const analytics = createAnalytics({
 
 ```ts
 // 普通事件（进入缓冲区，定时批量发送）
-analytics.track('purchase', { product_id: '123', amount: 99.9 });
+analytics.track('button_click', { target_id: 'buy_btn', scene: 'product' });
 
-// 关键事件（立即发送，不等待缓冲区）
+// 关键事件（立即发送，不等缓冲区）
 analytics.track('payment_success', { order_id: '456' }, { keyEvent: true });
 ```
 
 ### 用户标识
 
 ```ts
-// 设置用户 ID（同步到 GA 的 user_id）
-analytics.identify('user-123', { vip: true, level: 'gold' });
+// 设置用户 ID 与属性
+analytics.identify('user-123', { plan: 'pro', email: 'user@example.com' });
 
 // 获取用户信息
-analytics.getUserProfile();
-// { userId: 'user-123', anonymousId: 'uuid...', attributes: { vip: true } }
+const profile = analytics.getUserProfile();
+// { userId: 'user-123', anonymousId: 'uuid...', attributes: { plan: 'pro' } }
+
+// 重置用户身份
+analytics.reset();
 ```
 
-### GA 编程式控制
+### GTM 编程式控制
 
 ```ts
-// 直发 GA 事件（不走 SDK 服务端）
-analytics.ga.track('login', { method: 'email' });
+// 直接推送自定义数据到 dataLayer
+analytics.gtm.push({ event: 'custom_event', key: 'value' });
 
-// 设置 GA 用户属性
-analytics.ga.setUserProperties({ plan: 'premium' });
+// 推送带事件名的数据
+analytics.gtm.track('checkout_start', { step: 1 });
 
-// GDPR 同意模式
-analytics.ga.consent('default', {
-  analytics_storage: 'denied',
-  ad_storage: 'denied',
-});
-analytics.ga.consent('update', {
-  analytics_storage: 'granted',
-});
+// 设置用户 ID
+analytics.gtm.setUserId('user-123');
 
-// GA4 配置
-analytics.ga.config({ page_title: '首页' });
+// 设置用户属性
+analytics.gtm.setUserProperties({ plan: 'pro' });
 ```
 
 ### 其他方法
 
 ```ts
-// 立即刷新缓冲区
-analytics.flush();
-
-// 重置用户身份
-analytics.reset();
-
-// 获取会话 ID / 客户端 ID
-analytics.getSessionId();
-analytics.getClientId();
-
-// 设置客户端类型 / 商户语言
-analytics.setClientType('MINI_PROGRAM');
-analytics.setMerchantLanguage('zh');
+analytics.flush();                        // 立即刷新缓冲区
+analytics.getSessionId();                 // 获取当前 session ID
+analytics.getClientId();                  // 获取匿名客户端 ID
+analytics.setClientType('MINI_PROGRAM'); // 设置客户端类型
+analytics.setMerchantLanguage('zh');     // 设置商户语言
+analytics.destroy();                      // 销毁实例，移除事件监听（SPA 路由切换时使用）
 ```
 
 ---
 
 ## 自动埋点
 
-默认开启，通过 `data-track-*` 属性声明式埋点：
+默认开启，通过 `data-track-*` 属性声明式配置：
 
 ```html
 <!-- 自定义事件名 -->
@@ -169,23 +152,48 @@ analytics.setMerchantLanguage('zh');
 <!-- 任意 data-track-* 前缀自动成为属性键 -->
 <a data-track-name="share"
    data-track-platform="wechat"
-   data-track-position="top">
-  分享
-</a>
+   data-track-position="top">分享</a>
 
 <!-- 忽略该元素 -->
 <div data-track-ignore>不追踪</div>
 ```
 
-限定自动埋点范围：
+限定追踪范围：
 
 ```ts
 createAnalytics({
-  serverUrl: '...',
-  autoTrackSelector: '#app', // 只在 #app 内追踪点击
+  serverUrl:          '...',
+  autoTrackSelector:  '#app', // 只追踪 #app 内的点击
+});
+```
+
+关闭自动埋点：
+
+```ts
+createAnalytics({ serverUrl: '...', autoTrack: false });
+```
+
+---
+
+## 采样控制
+
+通过 `sampleRate` 控制上报比例，降低高流量场景的服务器压力。决策在每次页面加载时独立进行——命中采样的会话全量上报，未命中的会话全部丢弃（包括 GTM）。
+
+```ts
+// 只上报约 10% 的页面会话
+const analytics = createAnalytics({
+  appKey:     'your-app-key',
+  serverUrl:  'https://your-server.com/collect',
+  sampleRate: 0.1,
 });
 ```
 
+- `sampleRate: 1`（默认）— 全量上报
+- `sampleRate: 0` — 全部丢弃，可用于临时关闭上报
+- `sampleRate: 0.1` — 约 10% 的页面会话上报，每次刷新重新决策
+
+> 采样决策作用于整个会话：同一次页面加载内，所有 `track()` 要么全部上报，要么全部丢弃，不会出现部分事件缺失的碎片数据。
+
 ---
 
 ## 配置项
@@ -193,24 +201,100 @@ createAnalytics({
 | 配置 | 类型 | 默认值 | 说明 |
 |---|---|---|---|
 | `appKey` | `string` | — | 应用标识 |
-| `serverUrl` | `string` | — | 数据接收端点 |
-| `apiKey` | `string` | — | API Key（不填则根据 `env` 自动解析） |
+| `serverUrl` | `string` | — | 数据接收端点（`disableServer: true` 时可留空） |
+| `apiKey` | `string` | — | API Key（不填则按 `env` 自动解析） |
 | `env` | `string` | — | 环境：`beta` \| `test` \| `uat` \| `prod` |
-| `debug` | `boolean` | `false` | 控制台日志 |
+| `debug` | `boolean` | `false` | 开启控制台日志 |
 | `autoTrack` | `boolean` | `true` | 自动点击追踪 |
+| `autoTrackPageView` | `boolean` | `true` | 初始化时自动发送 `page_view`；设为 `false` 可手动控制 |
 | `autoTrackSelector` | `string` | — | 自动埋点的 CSS 选择器范围 |
-| `bufferFlushInterval` | `number` | `5000` | 缓冲区刷新间隔(ms) |
-| `bufferMaxSize` | `number` | `25` | 缓冲区满即刷新 |
-| `maxRetryCount` | `number` | `3` | 发送失败最大重试次数 |
-| `sessionTimeout` | `number` | `1800000` | 会话过期时间(ms)，默认30分钟 |
-| `system` | `string` | — | 系统标识 |
-| `domain` | `string` | — | 域名标识 |
-| `performance` | `object` | `{ enabled: true }` | Core Web Vitals 采集配置 |
-| `ga.enabled` | `boolean` | — | GA 双发开关 |
-| `ga.measurementId` | `string` | — | GA4 测量 ID（G- 开头） |
-| `ga.sendPageView` | `boolean` | `false` | 是否由 gtag 自动发送 page_view |
-| `ga.debugMode` | `boolean` | `false` | GA 调试模式 |
-| `disableServer` | `boolean` | `false` | 关闭自建服务上报，只发 GA |
+| `sampleRate` | `number` | `1` | 采样率 `0~1`；每次页面加载独立掷骰，`0.1` 表示约 10% 的页面会话上报，`0` 全不报，`1` 全量报 |
+| `system` | `string` | — | 系统标识，写入每条事件 |
+| `domain` | `string` | — | 业务域标识，写入每条事件 |
+| `keyEvents` | `string[]` | — | 关键事件名单，命中的事件立即发送 |
+| `bufferFlushInterval` | `number` | `5000` | 缓冲区定时刷新间隔（ms） |
+| `bufferMaxSize` | `number` | `25` | 缓冲区达到此数量立即刷新 |
+| `maxRetryCount` | `number` | `3` | 发送失败最大重试次数（指数退避） |
+| `sessionTimeout` | `number` | `1800000` | 会话超时（ms），默认 30 分钟 |
+| `performance.enabled` | `boolean` | `true` | Core Web Vitals 采集开关 |
+| `gtm.enabled` | `boolean` | — | GTM 双发开关 |
+| `gtm.containerId` | `string` | — | GTM 容器 ID（`GTM-XXXXXXX` 格式） |
+| `gtm.dataLayerName` | `string` | `'dataLayer'` | 自定义 dataLayer 变量名 |
+| `disableServer` | `boolean` | `false` | 关闭自建服务上报，只推 GTM |
+
+---
+
+## 上报数据结构
+
+### 自建服务（批量 POST）
+
+```json
+{
+  "client_id":       "uuid",
+  "user_id":         "user-123",
+  "session_id":      "uuid",
+  "user_properties": { "plan": "pro" },
+  "context": {
+    "sdk_version": "1.0.0",
+    "app_key":     "your-app-key",
+    "browser":     { "name": "Chrome", "version": "135" },
+    "operating_system": { "name": "Windows", "version": "10" },
+    "device_type": "desktop",
+    "country":     "CN",
+    "language":    "zh-CN",
+    "timezone":    "Asia/Shanghai"
+  },
+  "marketing": {
+    "utm_source":   "google",
+    "utm_medium":   "cpc",
+    "utm_campaign": "spring_sale",
+    "landing_page": "https://example.com/?utm_source=google",
+    "referrer_url": "https://google.com"
+  },
+  "events": [
+    {
+      "event_id":          "uuid",
+      "event_name":        "button_click",
+      "timestamp":         1700000000000,
+      "key_event":         false,
+      "batch_event_index": 0,
+      "batch_ordering_id": "1700000000000-1",
+      "batch_page_id":     "abc-xyz",
+      "event_properties": {
+        "system":      "web",
+        "domain":      "payment",
+        "scene":       "product",
+        "action":      "click",
+        "target_type": "button",
+        "target_id":   "buy_btn",
+        "page_url":    "https://example.com/product"
+      }
+    }
+  ]
+}
+```
+
+### GTM dataLayer
+
+每个 `track()` 调用推入一条：
+
+```json
+{
+  "event":      "button_click",
+  "action":     "click",
+  "target_id":  "buy_btn",
+  "session_id": "uuid",
+  "page_url":   "https://example.com/product",
+  "referrer":   ""
+}
+```
+
+`identify()` 推入：
+
+```json
+{ "userId": "user-123" }
+{ "plan": "pro", "email": "user@example.com" }
+```
 
 ---
 
@@ -218,20 +302,36 @@ createAnalytics({
 
 | 采集项 | 说明 |
 |---|---|
-| 点击事件 | 自动埋点 + 手动 `analytics.track()` |
-| 页面浏览 | 初始化时自动发送 `page_view` |
-| JS 错误 | 全局 `window.error` / `unhandledrejection` |
-| Core Web Vitals | LCP / FCP / CLS / INP / TTFB |
-| 设备上下文 | 浏览器、OS、屏幕、语言、时区等 |
-| 营销归因 | UTM 参数、落地页、来源 URL |
+| 点击事件 | 自动埋点（`data-track-*`）+ 手动 `analytics.track()` |
+| 页面浏览 | 初始化时自动发送 `page_view`（可通过 `autoTrackPageView: false` 关闭） |
+| JS 错误 | 全局 `window.error` / `unhandledrejection` 自动捕获 |
+| Core Web Vitals | LCP / FCP / CLS / INP / TTFB（`web_vital` 事件） |
+| 设备上下文 | 浏览器、OS、屏幕分辨率、语言、时区、设备类型 |
+| 营销归因 | UTM 参数持久化、落地页、来源 URL（SPA 路由切换后仍保留） |
 
 ---
 
-## 双发机制
+## 可靠性机制
 
-每个 `analytics.track()` 调用同时发送到两处：
+- **缓冲区 + 批量发送**：事件先入缓冲区，满 `bufferMaxSize` 或到 `bufferFlushInterval` 后批量发送
+- **指数退避重试**：发送失败最多重试 `maxRetryCount` 次，间隔 1s / 2s / 4s…
+- **本地持久化**：超出重试次数的事件写入 localStorage，下次页面加载时自动恢复补发（24 小时内有效）
+- **页面关闭兜底**：`beforeunload` / `pagehide` 时用 `sendBeacon` 发送缓冲区剩余事件
+- **采样控制**：`sampleRate` 在客户端决定是否上报，降低高流量场景的服务器压力
 
-1. **自建服务** — 事件进入缓冲区，定时批量 POST 到 `serverUrl`
-2. **GA4** — 即时调用 `gtag('event', ...)`，附带 session_id、页面信息、UTM 参数
+---
+
+## SPA 使用建议
+
+路由切换时销毁旧实例，重建新实例以正确发送新页面的 `page_view`：
 
-GA 初始化失败会自动降级，不影响自建服务上报。
+```ts
+// 路由离开时
+analytics.destroy();
+
+// 路由进入时
+analytics = createAnalytics({ ... });
+// 或手动控制
+analytics = createAnalytics({ ..., autoTrackPageView: false });
+analytics.track('page_view', { page_url: location.href });
+```