xb_analytics_plus

xb_analytics_plus 是一个面向 XBScaffold 生态的跨平台埋点库。
它提供统一事件模型、异步队列、批量落盘、多 Sink 扇出、导出能力和内置调试页。

1. 设计目标

独立包，可单独发布到 pub.dev。
不改业务代码结构，快速接入。
写入链路尽量非阻塞，降低对 UI 的影响。
同时支持多输出通道（调试、内存、本地持久化、业务自定义上传）。
内置脱敏与采样能力，降低数据风险与体积。

2. 平台支持与持久化策略

Android、iOS、Windows、macOS、Linux：使用 path_provider + 文件（JSONL）持久化。
Web：使用 localStorage 持久化（通过条件导入隔离实现）。

说明：path_provider 官方不支持 Web，所以 Web 端不会走 path_provider。

3. 安装

dependencies:
  xb_analytics_plus: ^0.1.1

如果是当前仓库多包本地联调：

dependencies:
  xb_analytics_plus:
    path: ../xb_analytics_plus

4. 快速开始

import 'package:xb_analytics_plus/xb_analytics_plus.dart';

Future<void> main() async {
  await initXBTrack(
    XBTrackConfig(
      appVersion: '1.0.0+1',
      enableConsoleSink: true,
      enableMemorySink: true,
      enableLocalStoreSink: true,
      flushBatchSize: 20,
      flushInterval: const Duration(seconds: 1),
      commonParamsProvider: () => {
        'tenantId': '1001',
        'abGroup': 'A',
      },
      onShareRequested: (content) async {
        // 由业务自己接入分享/复制/上传工单能力
      },
    ),
  );

  xbSetTrackUser('user_001');
  xbSetTrackPage('HomePage');

  xbTrack('home_open');
  xbTrack('order_submit_click', params: {'orderId': 'A100'});
}

5. 核心数据流

collect -> sanitize -> sample -> queue -> flush(batch) -> sinks

xbTrack() 只负责进入内存队列。
达到批次阈值或定时器触发时批量 flush。
同一批事件并行分发到已注册的 sinks。

6. 对外接口总览（函数级）

6.1 初始化与生命周期

接口	作用	参数	返回
`initXBTrack(XBTrackConfig config)`	初始化埋点系统，注册 sinks/store，启动 flush 定时器	`config` 配置对象	`Future<void>`
`closeXBTrack({bool flushBeforeClose = true})`	关闭埋点系统，释放资源	`flushBeforeClose` 关闭前是否先 flush	`Future<void>`
`xbFlushTrack()`	手动立即 flush 队列	无	`Future<void>`

6.2 事件上报

接口	作用	参数	返回
`xbTrack(String event, {Map<String,dynamic>? params, String? pageName, Map<String,dynamic>? commonParams})`	上报业务事件主入口	`event` 事件名，`params` 事件参数，`pageName` 页面名，`commonParams` 本次附加公共参数	`void`
`xbTrackError(Object error, StackTrace? stackTrace, {String event = 'app_error', Map<String,dynamic>? extra})`	上报异常事件	`error`、`stackTrace`、`event` 自定义错误事件名、`extra` 附加字段	`Future<void>`

6.3 上下文控制

接口	作用	参数	返回
`xbSetTrackUser(String userId)`	设置当前用户 ID（后续事件自动带上）	`userId`	`void`
`xbClearTrackUser()`	清空当前用户 ID	无	`void`
`xbSetTrackPage(String? pageName)`	设置当前页面上下文	`pageName`	`void`
`xbSetTrackCommonParamsProvider(XBTrackCommonParamsProvider? provider)`	设置动态公共参数 provider	`provider` 回调，可返回租户、门店、AB 等上下文	`void`

6.4 本地读取与导出

接口	作用	参数	返回
`xbReadTrackLocalLatest({int limit = 100, int offset = 0})`	分页读取本地最新事件	`limit` 每页条数，`offset` 偏移量	`Future<List<XBTrackEvent>>`
`xbExportTrackAsJson({int? limit})`	导出 JSON（可限制最近 N 条）	`limit` 可空	`Future<String>`
`xbExportTrackAsText({int? limit})`	导出逐行文本（JSONL 风格）	`limit` 可空	`Future<String>`
`xbShareTrackExport({int? limit})`	触发分享回调（由 `onShareRequested` 执行）	`limit` 可空	`Future<void>`
`xbClearTrackLocal()`	清空本地缓存（内存 + store）	无	`Future<void>`

6.5 自动事件 Helper（供框架接线）

接口	作用	事件名
`xbTrackPageView(String pageName, {Map<String,dynamic>? params})`	页面曝光	`page_view`
`xbTrackPageHide(String pageName, {Map<String,dynamic>? params})`	页面被覆盖/隐藏	`page_hide`
`xbTrackPageLeave(String pageName, {required int durationMs, Map<String,dynamic>? params})`	页面离开（含时长）	`page_leave`
`xbTrackAppForeground({Map<String,dynamic>? params})`	进入前台	`app_foreground`
`xbTrackAppBackground({Map<String,dynamic>? params})`	进入后台	`app_background`
`xbTrackTap(String trackId, {Map<String,dynamic>? params})`	通用点击事件	`tap`

7. 核心类型与接口（类级）

7.1 `XBTrackEvent`

统一事件对象，关键字段：

eventId：事件唯一 ID。
event：事件名。
eventTimeMs：毫秒时间戳。
sessionId：会话 ID。
userId：用户 ID（可空）。
pageName：页面名（可空）。
appVersion：应用版本（可空）。
platform：平台标识。
schemaVersion：埋点协议版本。
params：业务参数。
commonParams：公共参数。

7.2 `XBTrackSink`

自定义输出通道接口：

abstract class XBTrackSink {
  Future<void> onEvent(XBTrackEvent event);
  Future<void> onEvents(List<XBTrackEvent> events);
  Future<void> close();
}

适用场景：

自定义 HTTP 上报。
写数据库。
转发到日志系统。

7.3 `XBTrackStore`

本地持久化接口：

abstract class XBTrackStore {
  Future<void> appendMany(List<XBTrackEvent> events);
  Future<List<XBTrackEvent>> readLatest({int limit = 100, int offset = 0});
  Future<List<XBTrackEvent>> readAll();
  Future<int> count();
  Future<int> approximateBytes();
  Future<void> clear();
  Future<void> close();
}

7.4 `XBTrackExporter`

导出接口：

abstract class XBTrackExporter {
  Future<String> exportAsJson({int? limit});
  Future<String> exportAsText({int? limit});
}

8. `XBTrackConfig` 配置项详解

字段	默认值	说明
`enabled`	`true`	总开关，`false` 时不采集
`flushBatchSize`	`20`	队列满多少条触发一次 flush
`flushInterval`	`1s`	定时 flush 间隔
`maxPendingQueueSize`	`5000`	内存队列最大长度
`maxEventBytes`	`8KB`	单条事件最大字节，超限丢弃
`sampleRate`	`1.0`	采样率，范围 `(0,1]`
`memoryMaxEvents`	`1000`	内存 sink 最大缓存条数
`ioMaxBytes`	`20MB`	非 Web 本地存储上限
`webMaxBytes`	`3MB`	Web 本地存储上限
`schemaVersion`	`'1.0.0'`	埋点协议版本号
`appVersion`	`null`	应用版本，写入事件
`platform`	`null`	平台名，空时自动识别
`enableConsoleSink`	`false`	是否启用控制台 sink
`enableMemorySink`	`true`	是否启用内存 sink
`enableLocalStoreSink`	`true`	是否启用本地 store sink
`commonParamsProvider`	`null`	全局公共参数回调
`sanitizer`	`null`	自定义值清洗器
`onShareRequested`	`null`	分享请求回调
`sinks`	`[]`	业务附加 sinks
`store`	`null`	自定义 store 实现
`sensitiveKeys`	内置敏感词集合	命中后自动掩码
`sensitiveValueMask`	`'***'`	脱敏替换值
`dropEventsWhenQueueFull`	`true`	队列满时丢弃新事件
`debugPrintDropReason`	`false`	调试输出丢弃原因
`storeNamespace`	`'xb_track'`	本地存储命名空间

9. 内置组件

9.1 `XBTrackDebugPage`

作用：可视化查看本地埋点数据，支持搜索、分页、复制 JSON、触发分享、清空缓存。

用法：

Navigator.of(context).push(
  MaterialPageRoute(builder: (_) => const XBTrackDebugPage()),
);

9.2 内置 sinks

XBConsoleSink：输出到控制台。
XBMemorySink：内存环形缓存。
XBLocalStoreSink：写入本地 XBTrackStore。

10. 高级扩展示例

10.1 自定义 Sink（例如上传到你自己的服务）

class MyUploadSink extends XBTrackSink {
  @override
  Future<void> onEvents(List<XBTrackEvent> events) async {
    final payload = events.map((e) => e.toJson()).toList();
    // TODO: 调用你自己的网络层上传 payload
  }
}

await initXBTrack(
  XBTrackConfig(
    sinks: <XBTrackSink>[MyUploadSink()],
  ),
);

10.2 自定义脱敏规则

await initXBTrack(
  XBTrackConfig(
    sanitizer: ({required key, required value}) {
      if (key == 'email' && value is String) {
        return value.replaceAll(RegExp(r'(?<=.).(?=.*@)'), '*');
      }
      return value;
    },
  ),
);

11. 接入建议（与 XBScaffold 配合）

在应用启动时调用 initXBTrack。
登录后调用 xbSetTrackUser，退出登录时调用 xbClearTrackUser。
页面生命周期中接入 xbTrackPageView/pageHide/pageLeave。
App 生命周期中接入 xbTrackAppForeground/background。
关键交互使用 xbTrack 或 xbTrackTap。
线上环境建议开启本地持久化并配置导出回调，便于问题排查。

12. 发布说明

xb_analytics_plus 是独立包，可单独发布。
发布前建议执行：

flutter pub get
flutter analyze
flutter test
flutter pub publish --dry-run

xb_analytics_plus

1. 设计目标

2. 平台支持与持久化策略

3. 安装

4. 快速开始

5. 核心数据流

6. 对外接口总览（函数级）

6.1 初始化与生命周期

6.2 事件上报

6.3 上下文控制

6.4 本地读取与导出

6.5 自动事件 Helper（供框架接线）

7. 核心类型与接口（类级）

7.1 `XBTrackEvent`

7.2 `XBTrackSink`

7.3 `XBTrackStore`

7.4 `XBTrackExporter`

8. `XBTrackConfig` 配置项详解

9. 内置组件

9.1 `XBTrackDebugPage`

9.2 内置 sinks

10. 高级扩展示例

10.1 自定义 Sink（例如上传到你自己的服务）

10.2 自定义脱敏规则

11. 接入建议（与 XBScaffold 配合）

12. 发布说明

Libraries

xb_analytics_plus package

xb_analytics_plus

1. 设计目标

2. 平台支持与持久化策略

3. 安装

4. 快速开始

5. 核心数据流

6. 对外接口总览（函数级）

6.1 初始化与生命周期

6.2 事件上报

6.3 上下文控制

6.4 本地读取与导出

6.5 自动事件 Helper（供框架接线）

7. 核心类型与接口（类级）

7.1 XBTrackEvent

7.2 XBTrackSink

7.3 XBTrackStore

7.4 XBTrackExporter

8. XBTrackConfig 配置项详解

9. 内置组件

9.1 XBTrackDebugPage

9.2 内置 sinks

10. 高级扩展示例

10.1 自定义 Sink（例如上传到你自己的服务）

10.2 自定义脱敏规则

11. 接入建议（与 XBScaffold 配合）

12. 发布说明

Libraries

xb_analytics_plus package

7.1 `XBTrackEvent`

7.2 `XBTrackSink`

7.3 `XBTrackStore`

7.4 `XBTrackExporter`

8. `XBTrackConfig` 配置项详解

9.1 `XBTrackDebugPage`