3.2 KiB

Raw Blame History

yx_tracking_flutter

企业级 Flutter 埋点 SDK（纯 Dart 实现），对齐后端接口：

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

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

功能特性

统一事件模型，自动补齐公共字段（systemCode、deviceInfo、时间戳等）
本地持久化队列（sqflite），断网可缓存，恢复后补发
批量上报 + 重试退避 + 队列上限裁剪
配置下发（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/api/ExternalEventlogs',
      clientType: 3,
      enableDebug: true,
    ),
  );
}

上报事件：

await Analytics.track(
  'PAGE_VIEW',
  eventParams: const <String, dynamic>{'page': 'home'},
  customTags: const <String, dynamic>{'tenantId': 't1'},
);

手动触发发送：

await Analytics.flush(force: true);

关键配置项（AnalyticsConfig）

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

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

3.2 KiB Raw Blame History Unescape Escape