跳到主要内容

埋点契约、漏斗、留存与诊断

适用:一般 2D 游戏的数据分析与观测,示例 TypeScript,客户端目标 Cocos Creator 3.8.8。资料核查:2026-11-17。事件命名与口径为课程设计,不假定已接入特定平台 SDK;实际数据处理要求须另核当前项目政策。

先写决策,再决定采什么​

“全部行为都上报”会增加成本、隐私负担和解释难度。先写想做的决策,例如“玩家是否在首关操作教学流失”“第二关失败来自难度还是卡顿”“广告完成后奖励是否到账”。每个问题对应必要事件和维度,再设计上报。没有明确用途的逐帧坐标与完整触摸轨迹,不应因为容易采集就默认保留。

行为分析、稳定性观测与经济账本各有目的。客户端 level_end 适合解释体验,但永久奖励与真实支付以服务端可信记录为准;异常日志帮助定位,不应直接当作用户行为总量。它们通过局标识或操作标识关联,保留各自来源。否则一次回调重复就可能同时抬高通关率、收入和奖励数。

事件契约要定义触发边界​

给每个事件写触发条件、只发生一次的范围、字段单位、可选条件、来源与版本。level_start 是开始加载还是玩家获得控制?level_end 是模型判定结束还是结算动画完成?选择不同会改变漏斗和时长。建议把加载开始、可玩和局结束分开,避免一个含混事件在不同版本改变含义。

type LevelEnded = {
eventId: string;
eventVersion: 1;
name: 'level_ended';
build: string;
ruleVersion: string;
runId: string;
levelId: string;
result: 'win' | 'lose' | 'abandon';
activeDurationMs: number;
occurredAt: number;
};

这里 activeDurationMs 只统计约定的活跃游玩时间,后台与暂停如何处理要写进口径。occurredAt 来自客户端时钟,服务端另存 receivedAt;不能把两者差值简单当作准确网络延迟。runId 是每次开局的关联键,eventId 标识一次事件,重试保留同一值。字段结构在运行时验证,未知版本拒绝或进入兼容处理,而不是污染正式表。

上报至少一次,分析去重​

移动端可能离线、切后台或被结束,上报既可能丢失,也可能重复。客户端队列设置容量、批次、重试预算和过期策略,不得无限积压占内存;重要业务结果由服务端账本补足。采集端重试复用 eventId,接收端按约定唯一键去重,保留失败计数。不要为省事每帧发请求,也不要把全部队列留到退出才发送。

本地持久化队列只保存必要字段,并按数据政策管理留存。上报失败不能阻断玩家继续游戏;诊断采样也不能影响奖励事务。格式错误与网络失败分别计数,持续错误的事件应隔离并告警,避免重试风暴。日志里的错误样本做脱敏,不能打印整个用户会话负载。

漏斗必须统一分母与关联范围​

例如“启动 → 大厅可交互 → 首局可玩 → 首局结束 → 再次开局”,每一步按同一会话或同一新用户群关联。不能用当天全部启动人数作分母、全部关卡次数作分子。玩家反复重试一关,次数转化与人数转化会不同,报告应分别命名。加载失败与主动离开也要尽量区分,否则会把技术问题归因于玩法无聊。

首局定义同样重要:账号第一次、设备第一次还是某版本第一次?游客转登录与跨设备会影响身份合并。只在有明确依据与合规范围内合并身份,不能把设备标识当作永远稳定的人。报表说明测试账号、内部流量、机器人与迟到数据如何处理,口径变化保留版本,不悄悄改历史指标。

留存关注群组,不是两个日活相除​

次日留存可以定义为某时区自然日首次活跃的一组玩家,在下一自然日再次活跃的比例;也可定义滚动时间窗,但不能混用。分母是该新用户群组,分子是其中返回者。节假日、渠道与设备结构会影响比较,新增大量低质量流量也会改变总体结果。先按群组和版本分层,再解释变化。

数据会迟到,最近一天的留存可能尚未成熟。报告标明计算截止与时区,预先定义补算窗口。样本少时变化很大,不能凭几个人的升降下结论。持续观察与定性反馈结合,才能判断第二关难度、教程长度或奖励设计是否需要改;单一指标上涨不自动等于体验改善。

性能与业务指标共同解释问题​

当通关率下降,关联构建、规则版本、设备档位与稳定性摘要,先排除某些机型卡顿或加载失败。性能指标用有限维度聚合,runId 和原始用户标识不适合作为监控指标标签,以免基数爆炸;需要逐局定位时放入受控事件或日志系统。错误率的分母也要明确,是启动次数、请求次数还是活跃会话。

广告请求、可展示、开始、完成观察、奖励确认与到账分开统计;收入以可信记录为准。支付创建订单、确认、发货和退款分开,不把客户端 success 直接相加当真实收入。监控能发现不一致,账本负责解释资产事实,两者不能互相替代。

用小样本对账验证管道​

准备几局结果已知的数据:一局胜利、一局失败、一局放弃,其中一条结束事件重复发送,另一条离线后迟到。手工计算次数、人数与时长,再核对接收、去重、聚合和报表各层。若测试只验证接口返回成功,就可能漏掉字段被丢弃、单位错误或分组被误合并。

事件新增与改名需要迁移策略。旧包仍会发送旧版本,报表要么兼容转换,要么明确分开显示;不能在改名当天把历史指标突然归零。为重要指标保留口径版本与变更说明,让运营讨论变化时能够区分产品变化和统计变化。

交给 AI 的任务与验收​

可复制任务:“围绕首局流失、第二关难度与奖励未到账设计最小事件集。每个事件列触发边界、字段单位、版本、去重范围、来源和留存用途。实现有界队列与重复 eventId 去重,定义漏斗与次日留存分母、时区和迟到窗口,不采集无用途个人资料。”

验收同一局不会重复计结束;断网重试不放大人数;暂停时间符合约定;测试流量可剔除;最近未成熟群组有标识;客户端收入与服务端账本不会混为一表结论。用已知小样本手工算出结果再比报表,比只看仪表盘曲线更可靠。

官方来源​

  • OpenTelemetry Metrics、Logs与Traces:不同观测信号的职责。
  • 微信官方 API 类型仓库:平台接口形态参考;本文事件不是微信官方事件字典,核对提交 42c427aa8c3961b7a4f8ea5bd6112c2bcf058177。
  • 本节漏斗、留存和字段为明确口径的教学设计;实际 SDK 支持、同意机制与平台数据要求需另行核验。