# 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。业务代码只需一行调用: ```js // 埋点调用示例 window.__analytics('ai_generate_success', { source: 'photo', size: '64x64', colors: 24, latency_ms: 1823 }); ``` 实现骨架(建议放于公共 bundle 首位): ```js (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 上报数据结构示例 单事件: ```json { "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): ```json [ { "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%)自动标注并推送。