doc_ai_backed/frontend-sdk/API_EXAMPLES.md

数据埋点 API 调用示例

基础信息

• 接口路径: /doc_ai/v1/analytics/track
• 请求方法: POST
• Content-Type: application/json
• 认证: 可选（Bearer Token）

1. 基础埋点事件（最小参数）

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. 完整埋点事件（包含所有字段）

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. 页面浏览事件

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. 任务相关事件

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. 任务完成事件

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. 表单提交事件

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. 文件上传事件

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. 错误追踪事件

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. 使用环境变量（推荐）

# 设置环境变量
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 文件：

{
  "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"
  }
}

然后执行：

curl -X POST http://localhost:8080/doc_ai/v1/analytics/track \
  -H "Content-Type: application/json" \
  -d @event.json

11. 批量埋点接口

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"
        }
      }
    ]
  }'

响应示例

成功响应

{
  "code": 200,
  "message": "success",
  "data": null
}

错误响应

{
  "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 个事件

测试命令（本地开发）

# 最简单的测试
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