217 lines
5.1 KiB
Markdown
217 lines
5.1 KiB
Markdown
# 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 行
|
||
|
||
```diff
|
||
- queryParameters: <String, dynamic>{'system_code': config.systemCode},
|
||
+ queryParameters: <String, dynamic>{'systemCode': config.systemCode},
|
||
```
|
||
|
||
---
|
||
|
||
### 2.2 更新 Example App 配置
|
||
|
||
#### [MODIFY] `example/lib/main.dart`
|
||
|
||
**修改位置**: 第 10-17 行
|
||
|
||
```diff
|
||
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 行（更新说明文字）
|
||
|
||
```diff
|
||
- const Text(
|
||
- '说明：Demo 使用 example.com 作为占位地址，'
|
||
- '实际联调时请替换为真实 HTTPS 域名。',
|
||
- ),
|
||
+ const Text(
|
||
+ '说明：已对接 SDK-TEST-FLUTTER 系统，'
|
||
+ '点击 Track 按钮记录事件，点击 Flush 上报。',
|
||
+ ),
|
||
```
|
||
|
||
---
|
||
|
||
### 2.3 添加生命周期监听（可选优化）
|
||
|
||
#### [MODIFY] `example/lib/main.dart`
|
||
|
||
**修改位置**: 第 18 行之后添加
|
||
|
||
```dart
|
||
// 绑定生命周期监听，后台时自动 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
|
||
|
||
```bash
|
||
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 事件上报
|
||
|
||
```http
|
||
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 获取配置
|
||
|
||
```http
|
||
GET /api/ExternalEventlogs/GetSystemAllDimInfo?systemCode=SDK-TEST-FLUTTER
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"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 按照以上方案执行修改。**
|