127 lines
3.6 KiB
Markdown
127 lines
3.6 KiB
Markdown
# 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 初始化阶段调用：
|
||
|
||
```dart
|
||
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,
|
||
),
|
||
);
|
||
|
||
// 注册生命周期监听（推荐）
|
||
Analytics.bindLifecycleObserver();
|
||
}
|
||
```
|
||
|
||
上报事件：
|
||
|
||
```dart
|
||
await Analytics.track(
|
||
'PAGE_VIEW',
|
||
eventParams: const <String, dynamic>{'page': 'home'},
|
||
customTags: const <String, dynamic>{'tenantId': 't1'},
|
||
);
|
||
```
|
||
|
||
手动触发发送：
|
||
|
||
```dart
|
||
await Analytics.flush(force: true);
|
||
```
|
||
|
||
## 关键配置项（AnalyticsConfig）
|
||
|
||
除了文档中的 Phase 1 配置项，还新增了以下能力配置：
|
||
- `useIsolateStorage`: 是否使用 Isolate 进行存储操作（默认 `true`，强烈建议在 Flutter 环境开启）
|
||
- `allowInsecureHttp`：是否允许使用 HTTP（默认 `false`，仅用于开发/测试环境）
|
||
- `enableMetrics`：是否启用 SDK 自监控指标（默认 `true`）
|
||
- `metricsReportInterval`：指标上报周期（默认 10 分钟）
|
||
- `blockOnValidationError`：Debug 下遇到校验 error 是否阻断发送（默认 `false`）
|
||
|
||
所有配置项详见：`lib/src/config/analytics_config.dart`
|
||
|
||
## 调试与运维能力
|
||
|
||
调试 API：
|
||
|
||
```dart
|
||
final count = await Analytics.cachedEventCount();
|
||
final recent = await Analytics.cachedRecentEvents(limit: 20);
|
||
await Analytics.refreshConfig(force: true);
|
||
await Analytics.reportMetricsNow();
|
||
```
|
||
|
||
## 拦截器（Phase 3）
|
||
|
||
```dart
|
||
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：
|
||
|
||
```bash
|
||
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`
|