Главная Обзор Помощь
Вход
alien
/
alien_cloud
12
0
Ответвить 0
Файлы Задачи 0 Запросы на слияние 0 Вики
Ветка: sit-lutong-dev
Ветки Метки
alien_cloud
/
alien-store
/
doc
/
前端埋点接入指南.md

前端埋点接入指南.md 9.0 KB
Постоянная ссылка История Исходник

前端埋点接入指南

请前端统一使用 /analytics/front 接口，不要再调用旧接口 POST /track/event。

一、推荐接口

接口 说明
POST /analytics/front/report 主入口，传 scene 即可
POST /analytics/front/batch 批量上报（最多50条）
POST /analytics/front/heartbeat 在线心跳（统计在线时长）
POST /analytics/front/user/register 用户注册埋点
POST /analytics/front/user/login 用户登录埋点
POST /analytics/front/user/logout 用户登出埋点
POST /analytics/front/ai-chat/end AI对话结束埋点
POST /analytics/front/content/publish 内容发布埋点
POST /analytics/front/content/interact 内容互动埋点（评论/点赞/收藏）
POST /analytics/front/merchant/view 商家浏览埋点
POST /analytics/front/ai-request AI 请求耗时上报
GET /analytics/front/scenes 获取全部 scene 列表

明细同步（业务侧主动推送完整字段）：

接口 说明
POST /analytics/detail/user 用户明细
POST /analytics/detail/merchant 商户明细
POST /analytics/detail/content 内容明细
POST /analytics/detail/ai-chat AI 对话明细

二、快速开始

1. 复制 SDK

将 alien-store/doc/analytics-front-sdk.js 复制到前端项目 utils/analytics.js。

2. 初始化（App.vue onLaunch）

import Analytics from '@/utils/analytics.js';

Analytics.init({
  baseUrl: 'https://your-api.com',
  getToken: () => uni.getStorageSync('token'),
  channel: 'app_store',
});

Analytics.onLaunch();
Analytics.startHeartbeat(60000);

3. 用户注册 / 登录 / 登出

// 注册成功
Analytics.userRegister({
  userId: 10001,
  userPhone: '13800138000',
  registerTime: '2026-06-15 10:00:00',
  channel: 'app_store',
  city: '北京',
});

// 登录成功
Analytics.userLogin({
  userId: 10001,
  city: '北京',
  deviceName: 'iPhone 15',
});

// 登出
Analytics.userLogout({
  userId: 10001,
  city: '北京',
  deviceName: 'iPhone 15',
  onlineDurationMin: 30,
});

4. AI 对话结束

Analytics.aiChatEnd({
  chatId: 'chat-uuid-001',
  userId: 10001,
  startTime: '2026-06-15 14:00:00',
  messageCount: 12,
  aiResponseDurationMs: 8500,
});

5. 内容发布

Analytics.contentPublish({
  contentId: 90001,
  contentType: 1,   // 1动态 2打卡 3二手商品
  authorType: 1,    // 1用户 2商家
  authorId: 10001,
  publishTime: '2026-06-15 16:00:00',
});

6. 内容互动（评论 / 点赞 / 收藏）

// 点赞 +1
Analytics.contentInteract({
  contentId: 90001,
  contentType: 1,
  increment: 1,
  userId: 10001,
});

// 取消点赞 -1
Analytics.contentInteract({
  contentId: 90001,
  contentType: 1,
  increment: -1,
  userId: 10001,
});

// 兼容旧写法（默认 increment=1）
Analytics.onContentInteract(90001, 1, { userId: 10001 });

7. 商家浏览

// 进入商家页：PV+1，当日首次访问 UV+1
Analytics.merchantView({
  merchantId: 20001,
  shopType: 1,   // 1美食 2休闲娱乐 3生活服务
  visitPv: 1,
  visitUv: 1,
  userId: 10001,
});

// 兼容旧写法（需传 shopType、visitPv、visitUv）
Analytics.onMerchantView(20001, {
  shopType: 1,
  visitPv: 1,
  visitUv: 1,
  userId: 10001,
});

8. 业务页面埋点示例

// 访问商户页
Analytics.onMerchantView(merchantId, {
  shopType: 1,
  visitPv: 1,
  visitUv: 1,
});

// 内容互动（contentType: 1动态 2打卡 3二手商品）
Analytics.onContentInteract(contentId, 1);

// 支付成功
Analytics.report('PAY_SUCCESS', { amount: 99.00, targetId: orderId });

// AI 请求耗时
Analytics.aiRequest({
  apiName: 'chat.completion',
  apiUrl: '/api/ai/chat',
  responseDurationMs: 1200,
  isTimeout: 0,
});

三、事件表独立字段说明

analytics_event 表每个业务值对应独立列，不使用 JSON 扩展字段：

字段 说明
userId / merchantId / targetId 用户、商户、目标对象
contentType 1动态 2打卡 3二手商品
amount / durationMs 金额、时长
deviceType / channel / city 设备、渠道、城市

四、scene 场景对照表

scene 含义 主要参数
APP_LAUNCH App 启动 channel, city
APP_REGISTER 用户注册 -
USER_HEARTBEAT 在线心跳 durationMs
MERCHANT_VIEW 访问商户 merchantId
MERCHANT_VERIFY 商户核销 merchantId, amount
CONTENT_PUBLISH 发布内容 targetId, contentType
CONTENT_INTERACT 内容互动 targetId, contentType
PAY_SUCCESS 支付成功 targetId, amount
AI_CHAT_START AI 对话开始 -
REPORT_SUBMIT 提交举报 targetId
AUDIT_SUBMIT 提交审核 targetId, contentType

完整列表调用：GET /analytics/front/scenes

五、请求示例

统一上报

POST /analytics/front/report
Authorization: Bearer {token}
Content-Type: application/json

{
  "scene": "MERCHANT_VIEW",
  "eventId": "a1b2c3d4e5f6",
  "merchantId": 1001,
  "city": "北京",
  "channel": "ios"
}

userId 可不传，服务端从 JWT 自动解析。

在线心跳

POST /analytics/front/heartbeat

{
  "durationMs": 60000
}

用户注册

POST /analytics/front/user/register

{
  "userId": 10001,
  "userPhone": "13800138000",
  "registerTime": "2026-06-15 10:00:00",
  "channel": "app_store",
  "city": "北京"
}

用户登录

POST /analytics/front/user/login

{
  "userId": 10001,
  "lastActiveTime": "2026-06-15 14:30:00",
  "city": "北京",
  "deviceName": "iPhone 15"
}

用户登出

POST /analytics/front/user/logout

{
  "userId": 10001,
  "lastActiveTime": "2026-06-15 15:00:00",
  "city": "北京",
  "deviceName": "iPhone 15",
  "onlineDurationMin": 30
}

AI 对话结束

POST /analytics/front/ai-chat/end

{
  "chatId": "chat-uuid-001",
  "userId": 10001,
  "startTime": "2026-06-15 14:00:00",
  "messageCount": 12,
  "aiResponseDurationMs": 8500
}

内容发布

POST /analytics/front/content/publish

{
  "contentId": 90001,
  "contentType": 1,
  "authorType": 1,
  "authorId": 10001,
  "publishTime": "2026-06-15 16:00:00"
}

内容互动

POST /analytics/front/content/interact

{
  "contentId": 90001,
  "contentType": 1,
  "increment": 1,
  "userId": 10001
}

increment 由前端决定增减幅度：评论/点赞/收藏传正数，取消操作传负数。会实时累加到 analytics_content_stat.interaction_count。

商家浏览

POST /analytics/front/merchant/view

{
  "merchantId": 20001,
  "shopType": 1,
  "visitUv": 1,
  "visitPv": 1,
  "userId": 10001
}

visitUv、visitPv 为当日增量：通常 PV 传 1；UV 在当日首次访问该商家时传 1，否则传 0。

商户明细同步（可选）

POST /analytics/detail/merchant

{
  "merchantId": 20001,
  "shopType": 1,
  "visitUv": 100,
  "visitPv": 500,
  "settleStatus": 1
}

明细同步接口中 visitUv/visitPv 为覆盖写入；浏览埋点 /merchant/view 为累加写入，请勿混用语义。

用户名称、商家名称、作者名称等展示字段不入库、不上报，查询明细时由服务端按 ID 回填。

AI 请求明细

POST /analytics/front/ai-request

{
  "apiName": "chat.completion",
  "apiUrl": "/api/ai/chat",
  "responseDurationMs": 1200,
  "isTimeout": 0
}

六、幂等与防重复

  • 每条上报建议传 eventId（前端 UUID）
  • 相同 eventId 重复提交会被服务端忽略，不会重复计数

七、管理端统计

建表脚本：alien-entity/src/main/resources/db/migration/analytics_tables.sql

埋点只写明细，看板数据由 alien-job 模块 XXL-JOB 定时任务或手动接口触发汇总：

XXL-JOB Handler Cron 建议 说明
analyticsCalculateTodayHourly 0 0 * * * ? 每小时汇总当日
analyticsCalculateYesterdayDaily 0 0 2 * * ? 每天凌晨2点汇总前日
analyticsCalculateRetention 0 0 3 * * ? 每天凌晨3点计算留存

手动触发：

POST /analytics/stat/calculate
{ "statDate": "2026-06-15", "scope": "ALL" }

查询看板：

GET /analytics/stat/daily?statDate=2026-06-15

八、代码目录（与旧埋点完全隔离）

alien-store/src/main/java/shop/alien/store/
├── controller/analytics/
│   ├── AnalyticsFrontController   # 前端上报 /analytics/front/*
│   ├── AnalyticsDetailController  # 明细上报 /analytics/detail/*
│   ├── AnalyticsStatController    # 统计查询 /analytics/stat/*
│   └── AnalyticsJobController     # 定时任务回调 /analytics/job/*
├── service/analytics/
└── util/analytics/

alien-job/src/main/java/shop/alien/job/store/
└── AnalyticsStatisticsJob         # XXL-JOB 调度入口