feat: decode user_id
This commit is contained in:
liuyuanchuang
@@ -37,6 +37,14 @@ func (h *AnalyticsHandler) TrackEvent(c *gin.Context) {
|
||||
return
|
||||
}
|
||||
|
||||
userID, err := common.GetUserIDFromContext(c)
|
||||
if err != nil {
|
||||
log.Error(c.Request.Context(), "get user id failed", "error", err)
|
||||
c.JSON(http.StatusOK, common.ErrorResponse(c, common.CodeUnauthorized, "unauthorized"))
|
||||
return
|
||||
}
|
||||
req.UserID = userID
|
||||
|
||||
if err := h.analyticsService.TrackEvent(c.Request.Context(), &req); err != nil {
|
||||
log.Error(c.Request.Context(), "track event failed", "error", err)
|
||||
c.JSON(http.StatusOK, common.ErrorResponse(c, common.CodeSystemError, "failed to track event"))
|
||||
|
||||
284
frontend-sdk/API_EXAMPLES.md
Normal file
284
frontend-sdk/API_EXAMPLES.md
Normal file
@@ -0,0 +1,284 @@
|
||||
# 数据埋点 API 调用示例
|
||||
|
||||
## 基础信息
|
||||
|
||||
- **接口路径**: `/doc_ai/v1/analytics/track`
|
||||
- **请求方法**: `POST`
|
||||
- **Content-Type**: `application/json`
|
||||
- **认证**: 可选（Bearer Token）
|
||||
|
||||
## 1. 基础埋点事件（最小参数）
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"user_id": 12345,
|
||||
"event_name": "button_click"
|
||||
}'
|
||||
```
|
||||
|
||||
## 2. 完整埋点事件（包含所有字段）
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||||
-d '{
|
||||
"user_id": 12345,
|
||||
"event_name": "formula_recognition_start",
|
||||
"properties": {
|
||||
"file_name": "math_formula.png",
|
||||
"file_size": 102400,
|
||||
"file_type": "image/png",
|
||||
"upload_method": "drag_drop"
|
||||
},
|
||||
"device_info": {
|
||||
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
|
||||
"screen_width": 1920,
|
||||
"screen_height": 1080,
|
||||
"language": "zh-CN",
|
||||
"timezone": "Asia/Shanghai",
|
||||
"platform": "MacIntel"
|
||||
},
|
||||
"meta_data": {
|
||||
"task_id": "task_123456",
|
||||
"timestamp": 1706342400000
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## 3. 页面浏览事件
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"user_id": 12345,
|
||||
"event_name": "page_view",
|
||||
"properties": {
|
||||
"page_url": "https://example.com/home",
|
||||
"page_title": "首页",
|
||||
"page_name": "home",
|
||||
"referrer": "https://example.com/login"
|
||||
},
|
||||
"device_info": {
|
||||
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
|
||||
"screen_width": 1920,
|
||||
"screen_height": 1080
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## 4. 任务相关事件
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||||
-d '{
|
||||
"user_id": 12345,
|
||||
"event_name": "task_create",
|
||||
"properties": {
|
||||
"task_type": "formula_recognition",
|
||||
"file_name": "equation.png",
|
||||
"file_size": 204800
|
||||
},
|
||||
"meta_data": {
|
||||
"task_id": "task_789012"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## 5. 任务完成事件
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"user_id": 12345,
|
||||
"event_name": "task_complete",
|
||||
"properties": {
|
||||
"duration_seconds": 5.2,
|
||||
"success": true,
|
||||
"result_type": "latex"
|
||||
},
|
||||
"meta_data": {
|
||||
"task_id": "task_789012"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## 6. 表单提交事件
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"user_id": 12345,
|
||||
"event_name": "form_submit",
|
||||
"properties": {
|
||||
"form_name": "user_registration",
|
||||
"form_fields": ["email", "password", "phone"],
|
||||
"success": true,
|
||||
"validation_errors": 0
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## 7. 文件上传事件
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"user_id": 12345,
|
||||
"event_name": "file_upload",
|
||||
"properties": {
|
||||
"file_name": "document.pdf",
|
||||
"file_size": 5242880,
|
||||
"file_type": "application/pdf",
|
||||
"upload_source": "drag_drop",
|
||||
"upload_duration_ms": 1200
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## 8. 错误追踪事件
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"user_id": 12345,
|
||||
"event_name": "error_occurred",
|
||||
"properties": {
|
||||
"error_type": "network_error",
|
||||
"error_message": "Failed to fetch data",
|
||||
"error_code": "NET_001",
|
||||
"page_url": "https://example.com/tasks",
|
||||
"user_action": "click_submit_button"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## 9. 使用环境变量（推荐）
|
||||
|
||||
```bash
|
||||
# 设置环境变量
|
||||
export API_BASE_URL="http://localhost:8080"
|
||||
export JWT_TOKEN="YOUR_JWT_TOKEN"
|
||||
export USER_ID=12345
|
||||
|
||||
# 调用接口
|
||||
curl -X POST ${API_BASE_URL}/doc_ai/v1/analytics/track \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer ${JWT_TOKEN}" \
|
||||
-d "{
|
||||
\"user_id\": ${USER_ID},
|
||||
\"event_name\": \"button_click\",
|
||||
\"properties\": {
|
||||
\"button_name\": \"submit\",
|
||||
\"button_position\": \"bottom\"
|
||||
}
|
||||
}"
|
||||
```
|
||||
|
||||
## 10. 使用 JSON 文件
|
||||
|
||||
创建 `event.json` 文件：
|
||||
```json
|
||||
{
|
||||
"user_id": 12345,
|
||||
"event_name": "custom_event",
|
||||
"properties": {
|
||||
"action": "click",
|
||||
"element": "button",
|
||||
"value": "submit"
|
||||
},
|
||||
"device_info": {
|
||||
"user_agent": "Mozilla/5.0",
|
||||
"screen_width": 1920,
|
||||
"screen_height": 1080
|
||||
},
|
||||
"meta_data": {
|
||||
"task_id": "task_123"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
然后执行：
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
|
||||
-H "Content-Type: application/json" \
|
||||
-d @event.json
|
||||
```
|
||||
|
||||
## 11. 批量埋点接口
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track/batch \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||||
-d '{
|
||||
"events": [
|
||||
{
|
||||
"user_id": 12345,
|
||||
"event_name": "page_view",
|
||||
"properties": {
|
||||
"page_name": "home"
|
||||
}
|
||||
},
|
||||
{
|
||||
"user_id": 12345,
|
||||
"event_name": "button_click",
|
||||
"properties": {
|
||||
"button_name": "start"
|
||||
}
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
## 响应示例
|
||||
|
||||
### 成功响应
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
```json
|
||||
{
|
||||
"code": 400,
|
||||
"message": "invalid request",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **user_id** 和 **event_name** 是必填字段
|
||||
2. **properties**、**device_info**、**meta_data** 都是可选字段，类型为 JSON 对象
|
||||
3. 如果提供了 Authorization header，token 中的 user_id 会被设置到上下文中，但请求体中的 user_id 仍然需要提供
|
||||
4. 建议在生产环境中始终使用 HTTPS
|
||||
5. 批量接口最多支持 100 个事件
|
||||
|
||||
## 测试命令（本地开发）
|
||||
|
||||
```bash
|
||||
# 最简单的测试
|
||||
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"user_id": 1, "event_name": "test_event"}'
|
||||
|
||||
# 查看响应详情
|
||||
curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"user_id": 1, "event_name": "test_event"}' \
|
||||
-v
|
||||
```
|
||||
@@ -4,7 +4,8 @@ import "time"
|
||||
|
||||
// TrackEventRequest 埋点事件请求
|
||||
type TrackEventRequest struct {
|
||||
UserID int64 `json:"user_id" binding:"required"`
|
||||
TaskNo string `json:"task_no" binding:"required"`
|
||||
UserID int64 `json:"user_id"`
|
||||
EventName string `json:"event_name" binding:"required"`
|
||||
Properties map[string]interface{} `json:"properties"`
|
||||
DeviceInfo map[string]interface{} `json:"device_info"`
|
||||
|
||||
Reference in New Issue
Block a user