wangyang
/
yx_tracking_flutter
1
0
Fork 0
Code Pull Requests Actions Releases Activity
yx_tracking_flutter/4.Example App 集成实施方案.md

5.1 KiB
Raw Permalink Blame History

Example App 集成实施方案

Example App Integration Implementation Plan

目标 (Goal): 使 example app 能够完整运行并对接真实后端
执行者 (Executor): Codex
日期 (Date): 2026-01-28
执行记录 (Execution): 已执行（参数名修复、Example 配置更新、生命周期监听接入、HTTP 放行）

一、后端配置信息 | Backend Configuration

项目 值
API 基础地址 http://192.168.2.7:18828
系统标识 SDK-TEST-FLUTTER
系统名称 Flutter SDK测试
认证方式 无需认证
协议 HTTP（生产建议 HTTPS）

二、需要修改的文件 | Files to Modify

2.1 修复参数命名问题

[MODIFY] lib/src/config/config_manager.dart

问题: SDK 使用 system_code，但后端期望 systemCode

修改位置: 第 59 行

- queryParameters: <String, dynamic>{'system_code': config.systemCode},
+ queryParameters: <String, dynamic>{'systemCode': config.systemCode},

2.2 更新 Example App 配置

[MODIFY] example/lib/main.dart

修改位置: 第 10-17 行

  await Analytics.init(
    const AnalyticsConfig(
-     systemCode: 'DEMO_APP',
-     endpointBaseUrl: 'https://example.com',
+     systemCode: 'SDK-TEST-FLUTTER',
+     endpointBaseUrl: 'http://192.168.2.7:18828',
      clientType: 3,
      enableDebug: true,
      batchSize: 5,
      flushInterval: 30,
      allowInsecureHttp: true,
    ),
  );

修改位置: 第 161-164 行（更新说明文字）

- const Text(
-   '说明：Demo 使用 example.com 作为占位地址，'
-   '实际联调时请替换为真实 HTTPS 域名。',
- ),
+ const Text(
+   '说明：已对接 SDK-TEST-FLUTTER 系统，'
+   '点击 Track 按钮记录事件，点击 Flush 上报。',
+ ),

2.3 添加生命周期监听（可选优化）

[MODIFY] example/lib/main.dart

修改位置: 第 18 行之后添加

  // 绑定生命周期监听，后台时自动 flush
  Analytics.bindLifecycleObserver();

---

### 2.4 放行 HTTP（开发/测试环境）

#### [MODIFY] `lib/src/config/analytics_config.dart`

**说明**: 为联调环境允许 HTTP，新增 `allowInsecureHttp` 配置项。

```diff
 const AnalyticsConfig({
   ...
   this.allowInsecureHttp = false,
 });

 // validate()
 if (scheme == 'http' && allowInsecureHttp) {
   // 允许开发/测试环境使用 HTTP
 }


---

## 三、验证步骤 | Verification Steps

### 3.1 运行测试

```bash
cd /Volumes/Workspace/SourceCode/yuanxuan/yx_tracking_flutter
flutter test

3.2 运行 Example App

cd /Volumes/Workspace/SourceCode/yuanxuan/yx_tracking_flutter/example
flutter run -d macos  # 或 chrome / android / ios

3.3 功能验证清单

  • 启动 App 无报错
  • 点击 "Track Demo Event"，缓存数量 +1
  • 点击 "Flush Now"，事件成功上报（HTTP 200）
  • 点击 "Refresh Config"，从后端拉取配置成功
  • 在管理后台查看上报的事件数据

四、API 接口参考 | API Reference

4.1 事件上报

POST /api/ExternalEventlogs/AddEventListLog
Content-Type: application/json

[
  {
    "system_code": "SDK-TEST-FLUTTER",
    "eventType": "DEMO_BUTTON_CLICK",
    "userInfo": null,
    "clientType": 3,
    "clientTimestamp": 1706000000000,
    "timestamp": "2026-01-28T12:00:00.000Z",
    "deviceInfo": {
      "os": "macOS 14.0",
      "model": "MacBook Pro",
      "screenResolution": "1920x1080"
    },
    "eventParams": {
      "Page": "demo",
      "Url": "https://example.com/demo",
      "ButtonId": "demo_btn_01"
    },
    "customTags": {"tenantId": "t1", "feature": "demo"}
  }
]

4.2 获取配置

GET /api/ExternalEventlogs/GetSystemAllDimInfo?systemCode=SDK-TEST-FLUTTER

响应示例:

{
  "systemInfo": {
    "system_code": "SDK-TEST-FLUTTER",
    "system_name": "Flutter SDK测试"
  },
  "systemEventTypes": [
    {"event_code": "DEMO_BUTTON_CLICK", "event_name": "Demo按钮点击"}
  ],
  "systemCustonTas": [
    {"tag_name": "tenantId", "tag_type": "string"}
  ]
}

五、数据模型对齐 | Data Model Alignment

后端字段 (EventlogAddDto) SDK 字段 (Event) 状态
system_code systemCode ✅
eventType eventType ✅
userInfo userInfo ✅
clientType (1=Android, 2=iOS, 3=Flutter) clientType ✅ 使用 3
clientTimestamp (int64 毫秒) clientTimestamp ✅
timestamp (ISO8601) timestamp ✅
deviceInfo deviceInfo ✅
eventParams eventParams ✅
customTags customTags ✅

六、注意事项 | Notes

  1. 网络环境: 确保开发机器可访问 192.168.2.7:18828
  2. 事件类型: 如需校验事件类型，需在管理后台配置 DEMO_BUTTON_CLICK
  3. 自定义标签: 如需校验标签，需在管理后台配置 tenantId、feature
  4. HTTP 仅限联调: 生产环境请务必使用 HTTPS，并关闭 allowInsecureHttp

请 Codex 按照以上方案执行修改。