PERLER LAB 数据分析与事件埋点规范(ANALYTICS.md)
版本: 1.0 | 关联: LAUNCH.md(§5 运营指标)· PRD.md
说明: 本规范定义全站事件埋点、转化漏斗、上报方式与关键指标看板,所有目标值对齐 LAUNCH.md §5.1/§5.2/§5.3。
1. 数据口径与用户标识
| 字段 |
类型 |
说明 |
device_id |
string (uuid) |
存于 localStorage._pl_device_id,首次访问生成,永久复用。权益与回访均按此维度统计(与兑换权益的本地存储机制一致) |
session_id |
string (uuid) |
存于 sessionStorage._pl_session_id,一次会话一个,关闭标签页即失效 |
page |
"/" | "/chibi" |
事件发生时所在页面 |
ts |
number (ms) |
事件时间戳(Date.now()) |
去重规则:漏斗与转化率类指标按 device_id 去重,且同一 session_id 内同一环节只计首次命中,避免重复点击抬高转化率。
2. 事件总表(38 个事件)
命名约定:全小写 snake_case;每行含 事件名 / 触发时机 / 参数(全部标注类型)/ 页面。
2.1 访问 / 页面浏览(5 个)
| 事件名 |
触发时机 |
参数 |
页面 |
session_start |
页面首次加载(会话开始) |
referrer: string(来源页), landing_page: "/"|"/chibi", utm_source: string? |
/ /chibi |
page_view |
每次页面浏览(SPA 路由切换同样触发) |
page: "/"|"/chibi", referrer: string |
/ /chibi |
home_view |
首页完成渲染 |
- |
/ |
chibi_view |
/chibi 专区完成渲染 |
- |
/chibi |
first_visit |
无 device_id 记录时首次访问 |
landing_page: "/"|"/chibi", referrer: string |
/ /chibi |
2.2 图片上传(5 个)
| 事件名 |
触发时机 |
参数 |
页面 |
upload_start |
用户点击/选择文件 |
file_type: "jpg"|"png"|"webp", file_size_bytes: number |
/ |
upload_success |
图片读取并校验通过 |
file_type: string, file_size_bytes: number, width_px: number, height_px: number, aspect_ratio: number(宽/高,保留 2 位) |
/ |
upload_fail |
读取/解析失败 |
file_type: string, file_size_bytes: number, error_code: "read_error"|"parse_error"|"corrupt" |
/ |
upload_size_exceed |
文件超过 12MB 被拦截 |
file_size_bytes: number, limit_mb: 12 |
/ |
upload_type_invalid |
文件格式不受支持 |
file_type: string, allowed: ["jpg","png","webp"] |
/ |
2.3 参数调整(4 个)
| 事件名 |
触发时机 |
参数 |
页面 |
param_change |
任意参数变更(通用兜底) |
param: "size"|"colors"|"bg_removal"|"style", value: string|number|boolean, prev_value |
/ /chibi |
param_size_change |
图纸尺寸变更 |
size: "32x32"|"48x48"|"64x64" |
/ |
param_color_change |
色数变更 |
colors: 12|24|36 |
/ |
param_bg_removal_toggle |
背景去除开关切换 |
value: boolean |
/ /chibi |
2.4 重新生成(1 个)
| 事件名 |
触发时机 |
参数 |
页面 |
regenerate_click |
点击"重新生成"按钮 |
trigger: "auto"|"manual", size: string, colors: number |
/ |
2.5 兑换码(5 个)
| 事件名 |
触发时机 |
参数 |
页面 |
redeem_modal_open |
打开兑换弹窗 |
entry: "download_lock"|"nav"|"banner"|"limit_hit" |
/ |
redeem_submit |
提交兑换码(调用 /api/codes/redeem) |
code_length: number, code_prefix: string(脱敏,仅取前 4 位) |
/ |
redeem_success |
兑换成功(redeem 返回成功) |
balance_added: number, total_balance: number, channel: "personal"|"agent" |
/ |
redeem_fail |
兑换失败 |
error_code: "invalid"|"used"|"expired"|"rate_limited", channel: "personal"|"agent" |
/ |
redeem_balance_checked |
用户查看剩余次数 |
balance: number |
/ |
2.6 订单 / 支付(5 个)
| 事件名 |
触发时机 |
参数 |
页面 |
order_create |
创建订单(调用 /api/orders) |
order_id: string, package: "experience"|"standard"|"pro", price_yuan: 4.9|12.9|29.9, times: 3|10|30 |
/ |
order_pay_method_select |
选择支付方式 |
order_id: string, method: "wechat"|"alipay"|"mock" |
/ |
order_pay_success |
支付成功 |
order_id: string, package: string, price_yuan: number, method: string, pay_amount: number |
/ |
order_pay_fail |
支付失败 |
order_id: string, error_code: string, method: string |
/ |
order_pay_cancel |
用户取消支付 |
order_id: string, duration_ms: number(从创建到取消) |
/ |
2.7 下载(3 个)
| 事件名 |
触发时机 |
参数 |
页面 |
download_click |
点击下载图纸 |
work_id: string, size: string, colors: number, is_chibi: boolean |
/ /chibi |
download_success |
下载完成(触发 /api/codes/consume 扣次成功) |
work_id: string, size: string, colors: number, consume_used: boolean |
/ /chibi |
download_fail |
下载失败 |
work_id: string, error_code: "blob_error"|"browser_blocked"|"consume_fail" |
/ /chibi |
2.8 AI 生成(6 个)
| 事件名 |
触发时机 |
参数 |
页面 |
ai_generate_start |
开始 AI 生成(调用 /api/chibi/generate) |
source: "photo"|"chibi", size: string, colors: number, style: string?(仅 chibi 源) |
/ /chibi |
ai_generate_success |
生成成功 |
source: string, size: string, colors: number, latency_ms: number, cost_yuan: number |
/ /chibi |
ai_generate_fail |
生成失败 |
source: string, error_code: "model_error"|"timeout"|"rate_limit", latency_ms: number |
/ /chibi |
ai_generate_retry |
用户点击重试生成 |
source: string, retry_count: number, prev_error_code: string |
/ /chibi |
generation_limit_hit |
剩余次数不足被拦截 |
balance: number, required: 1 |
/ |
chibi_convert_click |
将 AI 结果转为正式图纸 |
size: string, colors: number |
/chibi |
2.9 代理合作(2 个)
| 事件名 |
触发时机 |
参数 |
页面 |
agent_modal_open |
打开代理合作弹窗 |
entry: "footer"|"banner"|"faq" |
/ |
agent_consult_click |
点击"咨询/领取价目表" |
contact_channel: "wechat"|"qq", package_interest: "entry"|"standard"|"core" |
/ |
2.10 分享 / 增长(2 个)
| 事件名 |
触发时机 |
参数 |
页面 |
share_click |
点击分享 / 晒图纸 |
channel: "xiaohongshu"|"douyin"|"wechat"|"copy_link", work_id: string |
/ |
refer_link_click |
通过代理推广链接进入 |
agent_id: string, page: "/"|"/chibi" |
/ /chibi |
3. 转化漏斗定义
对齐 LAUNCH.md §5.1:访问 → 上传图片 → 生成预览 → 兑换解锁 → 下载完成(100% / 45% / 25% / 8% / 6%)。
| 步骤 |
名称 |
事件口径(去重) |
计算 |
目标 |
| 1 |
访问 |
page_view(当日去重 device_id 数) |
分母 = 100% |
- |
| 2 |
上传 |
upload_success(同一 session 首次) |
上传转化率 = 步骤2 / 步骤1 |
≥45% |
| 3 |
生成 |
ai_generate_success(同一 session 首次) |
生成转化率 = 步骤3 / 步骤1 |
≥25% |
| 4 |
兑换 |
redeem_success(同一 session 首次) |
兑换率 = 步骤4 / 步骤1 |
≥8%(付费转化,对齐 §5.2 目标 5%) |
| 5 |
下载 |
download_success(同一 session 首次) |
下载完成率 = 步骤5 / 步骤4 |
≥75% |
漏斗细分口径:
- 上传→生成转化率 = 步骤3 / 步骤2,用于衡量生成功能本身的流失(含次数不足拦截
generation_limit_hit)。
- 兑换→下载转化率 = 步骤5 / 步骤4,异常时应排查
download_fail 与浏览器下载拦截。
- 分渠道查看(小红书 / 抖音 / 代理链接 / 直接访问):以
session_start.referrer 与 utm_source、refer_link_click.agent_id 为维度拆分,T+7 复盘按渠道对齐。
4. 埋点实现建议
4.1 前端事件采集(window.__analytics 全局函数)
采用轻量全局函数方案,不引入第三方 SDK。业务代码只需一行调用:
实现骨架(建议放于公共 bundle 首位):
4.2 上报方式
| 项 |
方案 |
说明 |
| 上报通道 |
navigator.sendBeacon |
页面关闭不丢包,优先使用;不支持时降级 fetch(..., { keepalive: true }) |
| 聚合 |
本地 localStorage 队列批量上报 |
满 10 条立即上报;pagehide / visibilitychange(hidden) 兜底刷新 |
| 接口 |
POST /api/analytics/collect |
后端仅落库,返回 204,不参与业务逻辑;失败静默不重试(防阻塞主流程) |
| 采样 |
全量采集 |
MVP 规模小,全量采集便于调试;日事件量超过 20 万再引入采样 |
4.3 上报数据结构示例
单事件:
批量上报(sendBeacon body):
4.4 埋点与后端接口对照
| 事件 |
关联接口 |
触发说明 |
redeem_success / redeem_fail |
/api/codes/redeem |
按接口返回结果上报,channel 取返回值 |
download_success / download_fail |
/api/codes/consume |
consume_used=true 表示本次首次下载扣次 |
order_create / order_pay_success |
/api/orders |
支付回调确认成功后再上报 order_pay_success,金额以订单为准 |
ai_generate_start / ai_generate_success / ai_generate_fail |
/api/chibi/generate |
开始即上报 start,结束按结果上报成功/失败,cost_yuan 由后端返回或按模型单价估算 |
5. 关键指标看板(每日 10 指标)
数据源:事件表聚合 + 订单表。所有比率按「去重用户数」计算,统计窗口为自然日(UTC+8)。首月目标值引用 LAUNCH.md §5.1/§5.2。
| # |
指标 |
计算公式 |
首月目标 |
| 1 |
日活 UV |
COUNT(DISTINCT device_id)(当日有任意事件) |
300 |
| 2 |
新增用户 |
COUNT(first_visit)(当日) |
观察值,随渠道投入变化 |
| 3 |
上传转化率 |
COUNT(DISTINCT upload_success.device_id) / COUNT(DISTINCT page_view.device_id) |
≥45% |
| 4 |
生成转化率 |
COUNT(DISTINCT ai_generate_success.device_id) / COUNT(DISTINCT page_view.device_id) |
≥25% |
| 5 |
兑换率(付费转化) |
COUNT(DISTINCT redeem_success.device_id) / COUNT(DISTINCT page_view.device_id) |
≥8%(首月按 5% 起步) |
| 6 |
下载完成率 |
COUNT(DISTINCT download_success.device_id) / COUNT(DISTINCT redeem_success.device_id) |
≥75% |
| 7 |
AI 生成失败率 |
COUNT(ai_generate_fail) / (COUNT(ai_generate_success) + COUNT(ai_generate_fail)) |
≤5%(超线告警,§5.3) |
| 8 |
次日回访率 |
COUNT(昨日UV ∩ 今日UV) / COUNT(昨日UV) |
≥15% |
| 9 |
日均营收(GMV) |
SUM(order_pay_success.pay_amount)(当日) |
首月约 ¥1,900/月 |
| 10 |
客单价 |
SUM(order_pay_success.pay_amount) / COUNT(DISTINCT order_pay_success.device_id) |
¥12.9(以常用包为主) |
辅助指标(非每日必看,周度复盘):
- AI 生成成本 =
SUM(ai_generate_success.cost_yuan) / COUNT(ai_generate_success),单张目标 ¥0.02–0.05(§5.3)。
- 复购率 = 当月发生过 ≥2 次
redeem_success 的 device_id / 当月兑换用户数,T+7/T+30 复盘用。
- 分渠道转化率 = 各渠道漏斗第 4 步 / 第 1 步,评估投放 ROI 与代理链接效果。
看板展示建议:首页放指标 1/3/4/5/7/9,第二屏放 2/6/8/10 及辅助指标;每日 09:00 生成前一日报告,异常指标(失败率>5%、兑换率低于 4%)自动标注并推送。