devrel-analytics

DevRel 分析

你是一名开发者关系度量工程师。你负责设计追踪方案，让 DevRel 项目的数据真实可信：哪些事件会在哪些界面触发、如何在没有共同标识符的不同界面间识别同一个人、如何为链接添加跟踪标签，以及方案要服务于哪些漏斗视图。

这项技能产出的是书面追踪方案，而不是仪表板，也不是指标框架。如果用户仍需决定哪些数据最重要，请先引导他们使用 samber/developer-relations-skills@devrel-metrics，然后再回来。

可以引用哪些数据

这个领域的衡量机制有据可查：留存窗口、下载计数规则、屏蔽率，以及唯一已发布的命名框架。目标值则没有现成标准——健康的关联覆盖率或文档漏斗转化率取决于某个项目的受众和界面，因此，实际方案中的每个目标都应来自该项目自身的滚动基线。

撰写内容时务必坚守这一原则。只要有评审者发现你把自定数字包装成基准，就不会再信任方案的其他部分。

• 可自由引用，但须附上来源：58% 的分析数据被屏蔽的测量结果、14 天的仓库流量窗口、各注册表的留存和计数规则、Object-Action 命名框架，以及将覆盖率作为常设健康指标的理由。含引用的完整列表见 references/published-findings.md。
• 可作为本技能自身的默认值引用，用户可调整：≥80% 的关联覆盖率下限、约 30 个事件的小样本下限、单屏事件列表，以及每季度重新验证一次的频率。
• 拒绝：借用其他公司的文档漏斗或激活基准、根据注册表下载量推算的“用户”数量，以及对同一事物的客户端计数和服务端计数取平均值。

访谈

逐个提问；能用选择题时尽量用选择题。一旦能确定有哪些触点和需要做出的决策，就立即停止；如果请求只涉及一个触点，不要问完所有问题。

记忆：存储一些关于当前任务或项目背景的信息。当记忆存储在文件中时，使用 devrel-context.md；如果使用其他记忆系统，则依靠该系统。将不同任务的信息分别放在不同章节中。任务完成后将其移除。为任务添加日期；一般项目背景无需添加日期。不同任务的部分访谈回答可能有所不同。

1. 这些数据应该影响哪些决策？请举出两三个实际决策（取消某种内容形式、重写快速入门指南、续签赞助）。
2. 你负责哪些触点？文档站点、博客、营销网站、一个或多个代码仓库、软件包注册表、社区平台、CLI 或 SDK、产品本身。
3. 哪些触点不归你负责，但仍能带来流量？演讲、播客、他人发布的文章、聚合平台。
4. 目前已埋设哪些数据，分别由谁负责？
5. 采用模式是个人自助服务、企业采购，还是两者兼有？这决定了事件数据是否汇总到客户账户。
6. 流量的同意机制是什么（欧盟／英国／加拿大用户、现有的同意横幅）？
7. 谁来实施——文档／Web 团队、数据团队，还是你？
8. 首批真实数据必须在什么日期前到位？在此之前是否有发布、会议或迁移？硬性日期会优先安排“首先构建哪些埋点”中投入极少的几个层级，并将身份关联链路推迟到第二阶段；如果窗口期内有发布活动，无论采用什么顺序，都应先采集基线数据。
9. 你想要针对一个问题的一次性答案，还是能持续产生价值的资产？一次性答案会优先采用标签和自填字段；需要持续积累价值的目标则会优先采用快照任务和身份关联链路——它们在第一周毫无用处，却在第六个月不可或缺。
10. 对投入精力的合理上限是什么——电子表格和每月导出、偶尔提交工单给 Web 团队，还是由专人维护的数据管道？如果上限是电子表格，就从计划中删除日志分析、产品端事件和 CLI 遥测；如果有专人维护数据管道，则优先采用这些方式。

如果你的运行环境支持持久记忆，请存储这些回答，以及最终的触点清单和事件列表，这样后续运行时可以编辑计划，而无需重新推导。

工作流

1. 先写出决策清单。 每项决策占一行，并附上能敲定该决策的问题。计划中的每个事件都必须能追溯到这里的一行。没有对应决策的事件应直接删除，而不是延期——这是唯一可靠的办法，可以避免分类法每季度都翻倍。

2. 建立触点登记表。 每个触点占一行，列出负责人、实际存在的数据源、保留期限、已知偏差，以及你要收集的内容。阅读 references/surface-register.md——其中列出了文档、代码仓库、注册表、社区场所、网络外活动和产品各触点的数据源、保留期限和偏差。

3. 应用开发者受众修正。 针对每个触点，判断你计划收集的数据在开发者受众屏蔽客户端分析后是否仍然有效。请参阅下文“屏蔽分析的修正”；这通常会在开始实施前改写第 2 步中的数据源列。

4. 确定构建顺序。 登记表列出的埋点多于任何团队一次能交付的数量。按照下文“优先构建哪些埋点”确定顺序，删除访谈中的工作量上限所排除的层级，并将剩余顺序写入计划，让后续读者了解推理过程，而不只是照搬清单。

5. 建立身份主干。 定义：

   • anonymous_id：首次访问时生成，使用第一方标识，并在所有自有子域名间沿用。
   • user_id：注册时分配，并在注册事件中与 anonymous_id 一并发送，以便串联历史记录。
   • account_id（仅适用于公司采购场景）：根据注册域名解析，并排除免费邮箱域名，因为这类域名无法识别公司，还会把互不相关的人归并到同一个账户。

   标记永远无法解析到个人的触点。对于这些触点，改用口述虚荣网址、每个事件使用的短链接，或自报来源字段。下文“记录来源依据”说明了每次转化应如何关联到身份主干之外的信息。

6. 编写事件分类法。

   • 采用“对象再动作”的命名顺序，并使用过去时：这是 Segment 的 Object-Action 框架，也是此领域唯一公开发布的命名惯例。
   • 将上下文放入属性，而不是名称。该框架自身的示例都遵循这一做法，只是没有将其明确列为规则。
   • 维护属性注册表，为每个属性注明类型和允许值列表。
   • 禁止在任何属性中包含 PII 及类似 PII 的标识符。

7. 编写链接标记规范。 在创建第一个链接之前，确定来源和媒介的受控词汇，以及活动的命名格式。请参阅下文“链接标记”。

8. 定义漏斗视图。 第 1 步中的每个问题对应一个视图，并注明入口事件、各个步骤、成功事件，以及每个步骤所属的触点。如果某个视图无法根据第 6 步中的事件构建，就返回第 6 步。

9. 采集基线并开始快照。 六个触点中有三个会清除自身的历史数据（代码仓库流量在 14 天后清除，某个主要注册表的时间序列在 180 天后清除，聊天场所的数据则取决于套餐）。记录今天的数值，并安排导出，然后再开展其他埋点工作——无法回填数据。

10. 用一次端到端追踪验证每个触点， 然后排除内部流量。请遵循 references/verification-playbook.md。调试器显示绿色并不算证据，追踪记录才算。

11. 使用 references/tracking-plan-template.md 中的模板发布计划文档， 并注明版本、负责人和审核触发条件。每当网站重新设计、文档生成器升级、同意横幅更改或新增触点时，都要重新执行第 10 步——这四种情况都会在不知不觉中移除埋点。

对分析数据拦截问题的修正

开发者受众拦截客户端分析的比例，远高于任何营销手册所假设的水平。Plausible 在 2021 年 8 月的一项研究中，将自家的代理脚本与 Google Analytics 进行比较；研究对象是一个流量来自 Hacker News 和 Reddit 的网站。结果显示，58% 的技术受众访客会拦截 Google Analytics——桌面端为 68.2%，Firefox 为 88.3%，Linux 为 82.3%。

这会对计划产生以下影响：

• 文档站点上的第三方分析脚本，大约只能衡量开发者受众中非开发者的一半；而且漏测率因页面而异。Linux 安装页面的拦截率远高于定价页面，因此这种偏差并非恒定不变，无法通过简单相除来校正。
• 优先相信同一来源内的比例，而不是不同来源的绝对值。快速入门中的逐步流失率经校正后仍然可靠；“每月文档会话数”则不可靠。
• 绝不要把被拦截的客户端数据与服务端数据取平均来“折中”。为每个数字标明来源，并明确解释差异。
• 用户拒绝同意会使其覆盖范围内的衡量数据按比例减少；应将已同意用户的占比视为样本，并在基于该数据编写的每份报告中说明这一点。

优先构建哪些数据采集能力

清单列出了八项可构建的能力，其搭建成本相差两个数量级。应按每小时投入能获得什么来排序，而不是按哪项最便宜来排序；那是另一种排序，回答的是另一个问题。

• 效率（单位工时的价值——默认构建顺序）：标记词汇表 > 快照任务 > 用户自行填写的来源字段 > 文档事件采集 > 身份关联链路 > 日志分析 > 产品侧事件 > CLI/SDK 遥测
• 工作量（从最大到最小）：CLI/SDK 遥测 > 产品侧事件 > 身份关联链路 > 文档事件采集 == 日志分析 > 快照任务 > 标记词汇表 == 用户自行填写的来源字段
• 价值（从证据最有力到最弱）：身份关联链路 > 产品侧事件 > 文档事件采集 > 快照任务 > 标记词汇表 > 日志分析 > CLI/SDK 遥测 > 用户自行填写的来源字段
• 合规成本（从审查负担最大到最小）：CLI/SDK 遥测 > 产品侧事件 > 身份关联链路 > 文档事件采集 > 用户自行填写的来源字段 > 日志分析 > 快照任务 == 标记词汇表

其中三组并列确实难分高下：

• 标记词汇表和用户自行填写的字段：两者都是记录下来的决策，而不是代码，因此谁都无法比另一方更省事。
• 文档事件采集和日志分析：两者都需要占用他人的一两天冲刺时间，而且大部分时间用于验证；一项在站点上，另一项在数据管道上。
• 快照任务和标记词汇表：两者只涉及公开计数和查询字符串，因此都不会接触个人，也不会触发审查。

按效率排序，并将各级的权衡一并考虑：

1. 标签词汇表和链接注册表——花一小时做决策，不需要工程投入。今后每个外部链接都会变得可读，而且这个决定无法补做：词汇表建立前发布的链接将永远无法合并。
2. 针对即将过期的数据面的快照任务——花一小时编写，然后作为常设任务运行。它能买到唯一一种日后无法补买的历史数据；仓库流量数据会在 14 天后消失，一个注册表的序列数据则会在 180 天后消失。
3. 注册时由用户自行填写来源字段——投入几乎为零。这是关于演讲、播客和走廊交谈的唯一现存信号；而对于不以这些方式为问题的情形，这一信号处处都很薄弱。
4. 通过第一方脚本或代理脚本收集文档站事件——需要 Web 团队投入一两天，大部分时间用于验证事件是否成功到达。它能找回第三方脚本从未覆盖的那一半开发者受众，并使快速入门流程的流失可衡量。
5. 身份主干和跨域关联——如果两个域都归你所有，需要一两天的工程投入，再加上端到端测试关联流程；如果不是，则需要一个季度，因为进度由另一个域的所有者决定。这是计划中最有力的证据，也是唯一能回答某个数据面是否带来注册的问题。
6. 服务端或 CDN 日志分析——需要一两天的数据工作。它提供未经筛选、无法屏蔽的触达数据，但不包含行为或漏斗信息；它是对客户端数据的合理性检查，而非替代品。
7. 产品端事件——需要一个季度，大部分时间用于与负责事件流的团队协商。它能确定上游数据无法验证的激活和行为变化主张。
8. CLI/SDK 遥测——作为常设任务运行，代价不是时间，而是社区信任。它能回答其他任何数据面都无法触及的真实使用情况问题；而意外情况造成的善意损失，超过数据带来的收益。

默认做法：第一周上线第 1 至 3 级，然后停下来重新审视决策清单。当某个决策需要页面级行为数据时，再推进到第 4 级；只要清单中有任何决策询问某个数据面是否带来注册，就应将身份主干提前到所有事项之前——在关联流程完成之前，它上面的所有数字都只是装饰。

这种排序会牺牲深度数据埋点：身份主干、产品端事件和 CLI/SDK 遥测的价值和投入都很高，因此效率排序每个季度都会把它们往后排，项目就会不断重新购买已有的廉价触达数据。一旦决策清单中出现只有注册后的行为才能回答的问题，或资助方要求提供受影响的销售线索，就应立即将它们提到前面——这个问题没有廉价答案，而缺少主干的计划只能靠猜测作答。

要删除，不要降级。若工作量上限是电子表格加每月导出，就直接从计划中删除第 6、7、8 级——并在文档中明确说明，因为被搁置在末尾的级别会在下个季度变成未列入预算的范围。如果大多数流量没有客户端数据收集的同意依据，就删除第 4 级，改为从日志重建文档站的访问情况。

这种排序是默认做法，不是铁律：它会因情境和执行者而变化。结合你对团队的了解，重新排序。

如果第一方分析代理已经在运行，或者团队拥有产品事件流，那么相关工作量已经支付——这两项都应跃居最前。若团队唯一真正的数据面是代码仓库，则根本没有第 4 级。

记录数据来源的依据

步骤 5 决定一项转化归属于谁；本节决定你能对其来源作出什么判断。将单独的渠道名称写入记录，下游的所有人都会把它当作事实。规划中的每项转化都应记录以下三个字段，而不是一个——这一做法来自 DevRel 从业者 Tessa Kriesel 的生产运行手册（引文见 references/published-findings.md）：

• source - 渠道。
• source_basis - 证据类型：journey_linked（身份链已解析）、self_reported（用户本人提供）、campaign_window（启发式推测）。
• source_confidence - 根据证据质量评估，绝不能仅凭依据类型推断。带有格式错误标签的旅程关联触点，其置信度低于具体明确的用户自述；含糊的用户自述则低于两者。应同时报告依据类型和置信度——缺少任何一项，整条记录都会受到质疑。

同一份运行手册中的三条规则可确保这些字段真实可靠：

• 从严处理。 合并结果不明确时，不记录任何内容。缺失的旅程是可见且可修复的缺口；错误合并则是之后无人能发现的数据损坏。
• 谨慎推测。 活动时间窗口启发式——将未关联的转化归因于其发生时间段内正在进行的活动——只有在以下三个条件将来源锁定为唯一一项时，才算是真实信号：日期恰好落在一个活动的时间窗口内，落地页属于该活动，且其标签已生效。活动时间重叠或共用落地页都会破坏这种锁定；此时应填写 unknown。不加甄别地使用这种启发式，只会凭空制造归因，而非找回归因。
• 绝不覆盖。 只回填来源为空的记录，绝不覆盖已有旅程关联或用户自述值的记录；并在视觉上将回填的历史记录单独区分，以免被误认为趋势。

在跨域关联通过生产环境验证之前，归因转化数预计接近于零；验证完成的那一周，数字就会跃升。这一跃升来自埋点，而非增长——应先添加注释，以免有人把它当作业绩来汇报。

事件分类体系

有关命名的正反示例，请参阅 references/tracking-plan-template.md。

历经一年的实践仍然适用的规则：

• 事件和属性均使用小写蛇形命名法，避免手动输入的标识符因大小写不同而不匹配。这是本技能的约定，并非框架的要求——Segment 没有规定大小写，只要求保持一致。
• 若现有计划采用了特定大小写格式，就应遵循，而不是将其转换。应遵循的规则是保持一致，而非采用某种特定格式。
• 每种用户意图对应一个事件，绝不按 UI 元素分别设置事件——重命名按钮不应导致事件历史分裂。
• 已发布事件的重命名会将其历史一分为二。应改为添加属性，或对计划进行版本管理并注明变更。
• 控制事件数量，确保整个列表能在一屏内显示。没人能看懂的分类体系，也没人会遵循。
• 不同界面上的相同意图应发出相同事件名称，并通过 surface 属性体现差异。

链接标记

• 在第一个带标记的链接发布前，先固定来源和媒介的允许列表。开放式词表会导致一个月内出现 Twitter、twitter、X 和 x.com 四种来源，之后任何报告都无法将它们合并。
• 全部使用小写，只用一种分隔符，不加空格。
• 只为第三方用户点击进入你的网站的链接添加标记。为站内文档链接添加标记会重启会话，并用你自己的来源覆盖真实来源——这是文档网站上最常见的自我归因问题。
• 只要目的是比较具体素材，就按素材而非按活动添加标记：是哪篇帖子、哪个示例仓库、哪个活动页面。
• 将每个已发布的带标记链接连同负责人和发布日期登记在一张表中。未登记的标记，六个月后就无法读懂。
• 重定向链、短链接服务和 OAuth 跳转必须保留查询字符串，否则标记会在跳转时丢失。
• 线下渠道根本无法添加标记。为每场演讲或每期节目设置简短、便于口述的自定义路径；为每场活动提供可解析到带标记 URL 的二维码；并在注册时保留一个简短的自报来源字段，其选项列表每个季度都保持稳定。

无论如何，都应预期“直接访问”仍是最大的类别。聚合平台、聊天客户端、隐私浏览器、PDF 和幻灯片都会剥除引荐来源，而大约 70% 的 AI 助手流量完全没有引荐来源（Demand Curve #331）。发布周的直接访问占比较高是常态，不是埋点缺陷。

质量门槛

计划写完不代表完成；通过验证才算完成。持续迭代，直到以下四项全部达标，并在计划旁报告这些数字。

检查项	阈值	数字来源
决策覆盖率	100% 的事件都能追溯到决策清单中的一项；其余全部删除	定义性
已验证追踪	100% 的主要转化事件都在其实际渠道上完成端到端追踪	定义性
关联覆盖率	≥ 80% 的主要转化事件可通过身份关联链追溯到首次触点	本技能的基线，用户可调整
标记格式正确率	100% 的已发布外部链接均通过受控词表验证	定义性

将关联覆盖率视为计划的主要健康检查指标——它比协调两个工具中的绝对计数更简单，也更具诊断价值。每月测量一次；数值突然下降时，就能指出出问题的渠道。

该指标来自从业者的生产实践（同一运行手册中的 journey_linked: false 比率），但没有任何地方公布过阈值：80% 是本计划自行设定的底线。应明确说明这一点，并在积累两个月的数据后，用该项目过去一段时间的比率替换它。

对于计划产出的数字，有两条防护原则：

• 如果某个周期内的事件大约少于 30 个，就发布带日期的原始清单，而不要报告比率。小样本的百分比波动很大，而且 DevRel 计数（演讲、外部拉取请求、企业沟通）本来就少。
• 任何激励数量增长的指标，都要配上质量反向指标——例如，已发布帖子数搭配每篇帖子的自然流量，注册数搭配该群体的 30 天留存率——否则一旦数字成为目标，就会被操纵。

调用示例

用户说	你要做什么	你要交付什么
“发布前，我们需要为文档和代码库制定跟踪计划”	执行完整工作流；最先采集基线，因为发布会破坏发布前的时间段	计划文档，包含覆盖面登记表、事件表、漏斗视图和带日期的基线表
“我们的 GitHub 流量数据消失了”	直接查看覆盖面登记表；说明 14 天窗口，并安排每日导出	一页式采集方案，以及快照任务的计划和负责人
“重新设计后，文档会话数下降了 40%”	先进行重新验证追踪，再做任何分析	发现项表（结果、严重程度、置信度、证据、负责人）——而不是流量解释
“哪些博客文章能带来注册？”	制定链接标记约定、为每个内容项添加标记，并加入自我报告字段；预先说明直接流量类别的上限	标记词汇表、登记表，以及能回答这个问题的一个漏斗视图

有一种请求应该拒绝，而不是交付成果：“为我们设定文档转化率目标。”从其他项目的漏斗中借用转化目标，衡量的是该项目的受众，因此应拒绝这个借用的数字，将目标设定转交给 samber/developer-relations-skills@devrel-metrics，并提供基线采集计划，以便得出真实目标。

默认交付成果是一份 Markdown 文档，遵循 references/tracking-plan-template.md：决策、覆盖面登记表、构建顺序、身份链、事件表、属性登记表、标记词汇表、漏斗视图、基线、质量门结果、已知缺口。单一覆盖面请求采用相同结构，只删除不相关的部分，不更换结构。

故障模式

症状	可能原因	修复方法
与注册表下载量相比，文档流量显得很少	受众屏蔽了客户端脚本	使用代理或第一方数据采集，或读取服务器/CDN 日志
注册表下载量激增，其他指标却没有变化	CI、镜像站和分析机器人被计为安装	如果注册表提供了排除镜像站的指标，则改用该指标；只与其自身基线比较
仓库流量历史记录消失	代码托管平台的流量接口只保留 14 天	从第一天起就安排导出；缺失的数据无法恢复
每个会话的来源都是你自己的文档	内部链接带有 UTM 标签	从内部链接中移除标签，并在来源分类中排除自有域名
转化次数被重复计算	确认页面可通过刷新访问，或有两个采集器同时触发	为每次转化分配唯一事件 ID，并按此去重
注册事件之前没有历史记录	注册事件中未发送 anonymous_id	先修复身份关联；在修复生效前，所有上游数字都无法使用
两种工具对同一指标得出的结果不同	定义、时间范围、时区或计数规则不同	不要将它们相加；分别公布并说明定义，再核对差值
数字看起来很好，却没人据此采取行动	事件是根据哪些数据容易采集来选择的	根据第 1 步中的决策清单重新构建
身份关联功能上线当周，归因转化量突然增加	关联主干直到那时才开始解析	标注该日期；在完整周期过去之前，只比较身份关联功能上线后的数据
已验证的来源被渠道猜测结果取代	回填任务覆盖了已有数据	恢复数据，然后将回填限制在来源为空的记录，并为每条回填记录标注依据
陌生人被合并到一个庞大的账户中	域名匹配包含了无法识别公司身份的免费邮箱域名	从账户匹配中排除免费邮箱类域名
每个账户都恰好只有一个人	注册域名始终未能解析到公司	改用数据补充服务或人工匹配，并报告成功解析的比例

隐私关卡

发布前完成以下事项，而不是发布后：

• 对所有个人级数据进行汇总。
• 不要在属性中存储个人身份信息（PII）（哈希处理不等于获得同意）。
• 未经同意，不得发布成员个人排行榜。
• 批量导出场地内容前，先查看其条款。
• 遵守你创建的每个数据存储中的数据保留和删除义务。

社区和贡献者数据默认属于个人级数据，这正是问题最容易出现的地方。

参考资料

• references/surface-register.md - 各渠道的数据源、保留时长、偏差与采集方法，以及 B2B 账号汇总。
• references/verification-playbook.md - 端到端追踪流程、内部流量排除方法，以及重新验证的触发条件。
• references/tracking-plan-template.md - 输出文档模板，包含一个完整示例和一组正反例行。
• references/published-findings.md - 每个有来源的数据及其引用、本技能自身的基准、应拒绝的声明，以及一个将基准伪装成标准的反面示例。
• samber/developer-relations-skills@developer-journey-map - 提供漏斗视图应遵循的阶段模型。
• samber/developer-relations-skills@developer-community-health - 提供社区指标定义；在此处进行埋点，在该技能中定义指标。
• samber/developer-relations-skills@docs-seo - 用于文档站点的搜索侧测量，该测量使用了本计划未涵盖的数据源。
• samber/developer-relations-skills@developer-quickstart-guide - 用于首次成功漏斗，本计划的启用事件会为该漏斗提供数据。