assessing-heatmaps

评估热图

热图回答的是“人们会在此页面的哪里进行交互？”——点击、愤怒点击、鼠标移动，以及他们向下滚动了多远。数据纯粹是几何信息：pointer_relative_x（在视口宽度范围内为 0..1）、pointer_y（页面向下的绝对像素位置），以及每个位置的计数。**它不知道人们点击了什么。**把“(0.5, 220) 处有很多点击”转化为“Pricing 导航链接有很多点击”，就是整个任务，而这需要交叉参照同一 URL 上的自动捕获数据。

核心原则：坐标 + 含义

你看不到页面——你的上下文中没有截图。好的评估需要融合两种数据来源，并依靠自动捕获数据提供你看不到的布局和元素身份信息：

1. 热图数据——交互落在哪里，以及人们滚动了多远（heatmaps-list）。
2. 自动捕获——热点下方是什么元素，可通过同一页面上的元素文本或选择器来判断。这能将坐标转化为含义；没有它，你手里只有点。

当用户想要_查看_热图时，创建已保存的热图（步骤 4）——它会将数据叠加渲染到页面上，供用户在 PostHog 中打开。你根据数据进行分析；他们查看图像。

流程

步骤 1：确定页面和时间范围

你需要精确的 url_exact（单个页面）或 url_pattern（正则表达式，用于聚合不同查询字符串）。如果 URL 不明确，请向用户确认。默认使用最近 7 天；如果数据量较少，则扩大到 30 天。热图数据保留 90 天。

步骤 2：提取数据

对你关心的每种信号调用一次 heatmaps-list（或通过 SQL 直接查询 heatmaps 表——参见 querying-posthog-data 技能中的 models-heatmaps）：

• type: "click"——主要的“什么吸引了注意力”热图。
• type: "rageclick"——用户因受挫而反复点击。**这是“有东西损坏或具有误导性”这一信号中最有力的一种。**任何明显的愤怒点击聚集都值得指出。
• type: "scrolldepth"——用户能滚动到多深。用它来确定首屏位置，并找出位于大多数用户滚动不到的位置下方的 CTA。

如果你关心有多少人（而非点击次数），请使用 aggregation: "unique_visitors"；total_count 会夸大少数高频点击用户的影响。

点击结果按热点程度从高到低返回，数量上限为 limit（默认值为 500）。繁忙页面可能有数千个不同的坐标，因此默认页面数据加上 fold 摘要几乎总是足够的——分析关注的就是最热点的位置。不要请求全部数据：只有在确实需要更多数据时才提高 limit 或通过 offset 分页，并检查 has_more 以确认列表是否被截断。scrolldepth 会忽略 limit，始终返回所有区间。

步骤 2b：首屏以上——读取 fold 摘要

对于点击类型，heatmaps-list 会在 results 旁返回一个 fold 对象：

• pct_below_fold——落在用户初始视口下方的非固定元素交互所占比例（用户必须滚动才能看到这些元素）。这是最有价值的发现之一：用户主动点击、但位于首屏以下的内容，是优先考虑上移的对象。
• below_fold_count / total_count——百分比背后的原始计数（固定定位元素会被排除，因为它们始终显示在屏幕上）。
• median_viewport_height——典型的首屏位置（以 CSS 像素计），可用于提出建议。

请具体说明，例如：“对大多数访客来说，首屏约在 600px 处，但 35% 的点击发生在首屏以下，因此用户会先滚动再交互——这部分内容可以考虑移到首屏。”使用 viewport_width_min/viewport_width_max 按设备划分数据（桌面设备和移动设备的首屏差异很大），并分别读取各区间的 fold，不要混合统计。

需要查看分布，而不是单个百分比（例如，按首屏下方的距离对点击进行分桶）？请改用 SQL 查询原始 heatmaps 表；其中的 y 和 viewport_height 使用相同的缩放单位——参见 querying-posthog-data 技能中的 models-heatmaps。

步骤 3：识别热点元素（自动捕获数据交叉验证）

对于每个显著的聚类，找出其中实际包含的内容。在同一个 URL 上查询自动捕获数据——可通过 exploring-autocapture-events 技能，也可直接查询：

SELECT properties.$el_text AS text, count() AS clicks
FROM events
WHERE event = '$autocapture'
  AND properties.$current_url = 'https://example.com/pricing'
  AND timestamp >= now() - INTERVAL 7 DAY
GROUP BY text
ORDER BY clicks DESC
LIMIT 25

如果有两个元素的文本相同，需要区分它们时，elements_chain 会提供选择器／DOM 路径。 将自动捕获数据中的热门元素与热图上的热点坐标对应起来：集中点击的对象如果不是链接或按钮（普通文本、图片、已禁用控件），这通常说明“用户以为它可以点击”。

步骤 4：向用户提供热图供其查看（可选）

你无法查看页面，但用户可以。当可视化有助于用户理解你的发现时，创建一张已保存的热图，让用户在 PostHog 中打开渲染后的页面并查看叠加的数据：

1. 使用页面 url 调用 heatmaps-saved-create（类型默认为 screenshot）。这会将无头渲染任务加入队列——该操作是异步的。传入与你在步骤 2 中分析的视口范围相匹配的 widths。
2. 轮询 heatmaps-saved-get（使用返回的 short_id），直到 status 为 completed，然后告知用户热图已可在 PostHog 中查看。

这只是为了方便用户——你自己的分析仍应依据步骤 2 中的数据和步骤 3 中自动捕获的元素信息，而不是图片。

步骤 5：深入分析热点（需要了解“原因”时）

对于令人意外的聚类，heatmaps-events 会返回特定 points 背后的各个会话。将会话 ID 交给 investigating-replay 技能，查看用户实际做了什么。

步骤 6：总结并提出建议

生成简短、具体的报告：

• 热图显示的内容——互动最多的元素、无人关注的区域、滚动范围，以及首屏上方／下方的点击分布（例如：“大多数访客的视口高度约为 600px，但 35% 的点击发生在首屏下方。”）。
• 问题，按信号强度排序——先列出愤怒点击聚类，其次是对非交互元素的点击，然后是位于滚动断点下方的重要 CTA，最后是被忽略的主要操作。
• 基于证据的建议——将 CTA 上移至首屏内、将被点击但无响应的元素改为真正的链接、减少愤怒点击聚类附近的干扰元素等。每条建议都应注明其依据的信号。

解读信号

信号	可能含义	常见建议
对某个元素发生愤怒点击	功能损坏、响应缓慢，或看起来可点击但实际不可点击	修复处理程序、添加反馈，或使其真正具备交互功能
大量点击非链接文本／图片	用户以为它可以点击	将其设为链接／按钮，或移除其可点击的视觉暗示
主要 CTA 点击量少	位置隐蔽、对比度低，或被其他元素抢走关注	将其上移、提高对比度、减少附近的干扰
用户在看到关键内容前停止滚动	内容／CTA 位于用户停止浏览的位置下方	将其上移，或提供继续滚动的理由
首屏下方的点击占比较高	用户互动的内容位于初始视口下方——用户会先滚动再互动	将点击量最高的元素移至首屏
导航栏点击多，正文点击少	页面未能满足用户需求；用户转而点击导航栏离开	重新评估页面的核心内容

注意事项

• 必须选择加入热图（Team.heatmaps_opt_in）。如果 heatmaps-list 对明显有流量的页面没有返回结果，可能是未开启采集或 URL 有误——在得出“没有互动”的结论前，请先检查这两项。
• 坐标在存储时会按 16 倍缩放；API 已返回 CSS 像素单位的 pointer_y 和相对 x 值，因此请直接使用 API／工具返回的值，而不要使用原始表格列。
• 你无法查看截图。 保存热图的渲染结果是供用户在 PostHog 中打开的；不要声称自己看过页面。所有关于布局的判断都应以自动采集的身份信息和坐标为依据，而不是视觉观察。
• 保存热图的渲染是异步的。 执行 heatmaps-saved-create 后，请轮询 heatmaps-saved-get，直到 status 为 completed，再告诉用户热图可以查看。只有 screenshot 类型的热图会渲染图像；iframe 和 recording 类型不会。
• 注意视口。 桌面端点击图和移动端点击图反映的是不同页面上的行为——请使用 viewport_width_min／viewport_width_max 进行筛选，不要将两者混在一起。