yx_tracking_flutter

企业级 Flutter 埋点 SDK（Flutter 运行环境使用，非纯 Dart 运行时），对齐后端接口：

• GET /api/ExternalEventlogs/GetSystemAllDimInfo
• POST /api/ExternalEventlogs/AddEventListLog
• POST /api/ExternalEventlogs/AddEventLog（可选降级）

当前已覆盖 Phase 1 / Phase 2 / Phase 3 的核心能力：初始化、持久化队列、批量上报、配置下发、校验、策略控制、拦截器与 SDK 自监控指标。

功能特性

• 统一事件模型，自动补齐公共字段（systemCode、deviceInfo、时间戳等）
• 本地持久化队列（sqflite），默认运行在独立 Isolate 中，避免阻塞 UI（需 Flutter 环境）
• 应用生命周期监听（进入后台/销毁时自动 flush）
• 批量上报 + 重试退避 + 队列上限裁剪
• 配置下发（GetSystemAllDimInfo）与本地缓存
• 事件校验（Debug 详细日志，Release 自动标记 _sdk_*）
• 动态策略（全局开关、事件级开关、采样率）
• 拦截器机制（beforeSend / afterSend，异常隔离）
• SDK 自监控指标（发送成功/失败/重试/丢弃、队列长度、平均延迟）

快速开始

在你的 App 初始化阶段调用：

import 'package:yx_tracking_flutter/yx_tracking_flutter.dart';

Future<void> bootstrapAnalytics() async {
  await Analytics.init(
    const AnalyticsConfig(
      systemCode: 'OA_APP',
      endpointBaseUrl: 'https://your-host',
      clientType: 3,
      enableDebug: true,
    ),
  );
  
  // 注册生命周期监听（推荐）
  Analytics.bindLifecycleObserver();
}

上报事件：

await Analytics.track(
  'PAGE_VIEW',
  eventParams: const <String, dynamic>{
    'Page': 'home',
    'Url': 'https://example.com/home',
    'ButtonId': 'page_view',
  },
  customTags: const <String, dynamic>{'tenantId': 't1'},
);

手动触发发送：

await Analytics.flush(force: true);

关键配置项（AnalyticsConfig）

除了文档中的 Phase 1 配置项，还新增了以下能力配置：

• endpointBaseUrl：仅填写基础 host（如 https://your-host），SDK 会自动拼接 /api/ExternalEventlogs/* 路径
• useIsolateStorage: 是否使用 Isolate 进行存储操作（默认 true，强烈建议在 Flutter 环境开启）
• allowInsecureHttp：是否允许使用 HTTP（默认 false，仅用于开发/测试环境）
• enableMetrics：是否启用 SDK 自监控指标（默认 true）
• metricsReportInterval：指标上报周期（默认 10 分钟）
• blockOnValidationError：Debug 下遇到校验 error 是否阻断发送（默认 false）

所有配置项详见：lib/src/config/analytics_config.dart

调试与运维能力

调试 API：

final count = await Analytics.cachedEventCount();
final recent = await Analytics.cachedRecentEvents(limit: 20);
await Analytics.refreshConfig(force: true);
await Analytics.reportMetricsNow();

拦截器（Phase 3）

class TenantInterceptor extends AnalyticsInterceptor {
  @override
  Future<Event?> beforeSend(Event event) async {
    final tags = Map<String, dynamic>.from(event.customTags ?? const {});
    tags['tenantId'] = 't1';
    return event.copyWith(customTags: tags);
  }
}

void setupInterceptors() {
  Analytics.addInterceptor(TenantInterceptor());
}

SDK 内置 CommonTagsInterceptor，会自动追加：

• _sdk_version
• _platform

运行示例 Demo

仓库已包含最小调试 Demo：

cd example
flutter run

Demo 提供：缓存条数、最近事件摘要、Track Demo Event、Flush Now、Refresh Config。

测试与校验

已通过以下本地校验：

• 根目录：flutter analyze / flutter test
• example：flutter analyze / flutter test

参考文档

• 设计方案：2.Flutter 埋点 SDK 设计方案（独立 Dart 实现）.md
• 实施清单：3.Flutter todo list.md