Files
perler-lab/docs/ANALYTICS.md
T
Sisyphus (主代理) 02762400fb chore: 项目基线提交 - 拼豆图纸生成器 V1.0 核心代码
- 前端: React+Vite 首页/AI专区, 算法库(MARD色板/量化/背景去除), API对接
- 后端: Express+SQLite, 兑换码/订单/支付/chibi生成, 风控+云端同步
- CI/CD: GitHub Actions + Docker + nginx 配置
- 文档: PRD/DESIGN/LAUNCH/ROADMAP/E2E/竞品对照等 15 份
- 工程: 任务看板(taskboard) + 健康巡检(agent-health) + Git流程(gitflow)
2026-08-13 21:40:27 +08:00

14 KiB
Raw Blame History

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。业务代码只需一行调用:

// 埋点调用示例
window.__analytics('ai_generate_success', { source: 'photo', size: '64x64', colors: 24, latency_ms: 1823 });

实现骨架(建议放于公共 bundle 首位):

(function () {
  var DKEY = '_pl_device_id', SKEY = '_pl_session_id', QUEUE = '_pl_queue';
  function uuid() {
    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
      var r = Math.random() * 16 | 0;
      return (c === 'x' ? r : (r & 0x3 | 0x8)).toString(16);
    });
  }
  function get(key, gen) {
    var v = localStorage.getItem(key);
    if (!v) { v = gen(); localStorage.setItem(key, v); }
    return v;
  }
  var deviceId = get(DKEY, uuid);
  var sessionId = sessionStorage.getItem(SKEY) || (sessionStorage.setItem(SKEY, uuid()), sessionStorage.getItem(SKEY));

  function flush() {
    var batch = [];
    try { batch = JSON.parse(localStorage.getItem(QUEUE) || '[]'); localStorage.removeItem(QUEUE); } catch (e) {}
    if (!batch.length) return;
    var body = new Blob([JSON.stringify(batch)], { type: 'application/json' });
    // 优先 sendBeacon,降级 fetch keepalive
    if (navigator.sendBeacon) { navigator.sendBeacon('/api/analytics/collect', body); return; }
    fetch('/api/analytics/collect', { method: 'POST', body: body, keepalive: true, headers: { 'Content-Type': 'application/json' } }).catch(function () {});
  }

  window.__analytics = function (event, properties) {
    properties = properties || {};
    var payload = {
      event: event,
      ts: Date.now(),
      device_id: deviceId,
      session_id: sessionId,
      page: location.pathname,
      properties: properties
    };
    var queue = [];
    try { queue = JSON.parse(localStorage.getItem(QUEUE) || '[]'); } catch (e) {}
    queue.push(payload);
    localStorage.setItem(QUEUE, JSON.stringify(queue));
    if (queue.length >= 10) flush();
    document.addEventListener('visibilitychange', function () {
      if (document.visibilityState === 'hidden') flush();
    });
    window.addEventListener('pagehide', flush);
  };
})();

4.2 上报方式

项 方案 说明
上报通道 navigator.sendBeacon 页面关闭不丢包,优先使用;不支持时降级 fetch(..., { keepalive: true })
聚合 本地 localStorage 队列批量上报 满 10 条立即上报;pagehide / visibilitychange(hidden) 兜底刷新
接口 POST /api/analytics/collect 后端仅落库,返回 204,不参与业务逻辑;失败静默不重试(防阻塞主流程)
采样 全量采集 MVP 规模小,全量采集便于调试;日事件量超过 20 万再引入采样

4.3 上报数据结构示例

单事件:

{
  "event": "ai_generate_success",
  "ts": 1755090000000,
  "device_id": "9f1c3a2e-7b84-4d2e-9f1c-3a2e7b844d2e",
  "session_id": "b3d2f5a1-6c9e-4f30-b3d2-f5a16c9e4f30",
  "page": "/",
  "properties": {
    "source": "photo",
    "size": "64x64",
    "colors": 24,
    "latency_ms": 1823,
    "cost_yuan": 0.03
  }
}

批量上报(sendBeacon body):

[
  { "event": "page_view", "ts": 1755089999000, "device_id": "9f1c...", "session_id": "b3d2...", "page": "/", "properties": { "referrer": "https://www.xiaohongshu.com" } },
  { "event": "upload_start", "ts": 1755090001000, "device_id": "9f1c...", "session_id": "b3d2...", "page": "/", "properties": { "file_type": "png", "file_size_bytes": 2097152 } }
]

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%)自动标注并推送。