Back to Details

assessing-heatmaps

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Assessing heatmaps

评估热图

A heatmap answers "where do people interact with this page?" — clicks, rage clicks, mouse movement, and how far down they scroll. The data is pure geometry: 
pointer_relative_x
(0..1 across the viewport), 
pointer_y
(absolute pixels down the page), and a count per spot. It does not know what was clicked. Turning "lots of clicks at (0.5, 220)" into "lots of clicks on the Pricing nav link" is the whole job, and it comes from cross-referencing autocapture on the same URL.
热图用于解答“人们与页面的哪些区域互动？”——包括点击、狂点、鼠标移动以及滚动深度。这些数据是纯粹的几何信息：
pointer_relative_x
（视口横向占比0..1）、
pointer_y
（页面纵向绝对像素值），以及每个点位的交互次数。热图无法识别点击的对象是什么。将“(0.5, 220)位置有大量点击”转化为“定价导航链接有大量点击”正是核心工作，这需要通过关联同一URL的自动捕获（autocapture）数据来实现。

Core principle: coordinates + meaning

核心原则：坐标 + 含义

You can't see the page — there is no screenshot in your context. A good assessment fuses two sources and leans on autocapture to supply the layout/identity you can't see:
  1. Heatmap data — where interactions land and how far people scroll (
    heatmaps-list
    ).
  2. Autocapture — what element sits under the hot spots, by element text / selector on the same page. This is what turns coordinates into meaning; without it you only have dots.
When the user wants to see the heatmap, create a saved heatmap (Step 4) — that renders the page with the data overlaid for them to open in PostHog. You reason from the data; they look at the picture.
你无法看到页面——上下文里没有截图。一份优质的评估需要融合两类数据源，并借助自动捕获数据来补充你无法看到的页面布局/元素身份：
  1. 热图数据——互动发生的位置以及用户滚动的深度（
    heatmaps-list
    ）。
  2. 自动捕获数据——通过同一页面上的元素文本/选择器，确定热门点位下方对应的元素。这是将坐标转化为实际含义的关键；没有它，你只能看到一堆点位。
当用户想要查看热图时，创建一个保存的热图（步骤4）——这会渲染出叠加了数据的页面，供用户在PostHog中打开查看。你基于数据进行分析；用户则查看可视化图片。

The flow

操作流程

Step 1: Pin the page and window

步骤1：锁定页面和窗口

You need an exact 
url_exact
(one page) or a 
url_pattern
(regex, to aggregate across query strings). Confirm the URL with the user if ambiguous. Default to the last 7 days; widen to 30 if volume is low. Heatmap data is retained for 90 days.
你需要精确的
url_exact
（单个页面）或
url_pattern
（正则表达式，用于聚合不同查询字符串的页面）。若URL不明确，请与用户确认。默认取最近7天的数据；若数据量较低，可扩大至30天。热图数据的保留期限为90天。

Step 2: Pull the data

步骤2：获取数据

Call 
heatmaps-list
once per signal you care about (or query the 
heatmaps
table directly via SQL — see the querying-posthog-data skill, 
models-heatmaps
):
  • type: "click"
    — the primary "what draws attention" map.
  • type: "rageclick"
    — repeated frustrated clicks. The single strongest "something is broken or misleading" signal. Any meaningful rageclick cluster deserves a callout.
  • type: "scrolldepth"
    — how far people get. Use it to find the fold and spot CTAs that sit below where most people ever scroll.
Use 
aggregation: "unique_visitors"
when you care about how many people (not how many clicks); 
total_count
exaggerates a few heavy clickers.
针对你关注的每个信号调用一次
heatmaps-list
（或直接通过SQL查询
heatmaps
表——参考querying-posthog-data技能，
models-heatmaps
）：
  • type: "click"
    ——核心的“哪些内容吸引注意力”热图。
  • type: "rageclick"
    ——重复的受挫点击。这是“某个功能损坏或存在误导”的最强信号。任何有意义的狂点集群都值得重点指出。
  • type: "scrolldepth"
    ——用户滚动的深度。用于找到折叠线（fold），以及定位那些位于大多数用户滚动范围之外的CTA按钮。
当你关注的是参与用户数量（而非点击次数）时，使用
aggregation: "unique_visitors"
；
total_count
会夸大少数高频点击用户的影响。

Step 2b: Above the fold — read the 
fold
summary

步骤2b：折叠线以上——解读
fold
摘要

For the click types, 
heatmaps-list
returns a 
fold
object alongside 
results
:
  • pct_below_fold
    — share of non-fixed interactions that landed below the user's initial viewport (they had to scroll to reach them). This is one of the highest-value findings: content people actively click that sits below the fold is a prime candidate to move up.
  • below_fold_count
    / 
    total_count
    — the raw counts behind the percentage (fixed-position elements are excluded, since they're always on screen).
  • median_viewport_height
    — the typical fold line in CSS pixels, to recommend against.
Report it concretely, e.g. "the fold is ~600px for most visitors, yet 35% of clicks land below it, so users scroll before interacting — that content is a candidate for the first screen." Segment by device with 
viewport_width_min
/
viewport_width_max
(desktop and mobile have very different folds) and read 
fold
per band rather than blending them.
Need a distribution rather than a single percentage (e.g. clicks bucketed by how far below the fold)? Drop to SQL on the raw 
heatmaps
table, which has 
y
and 
viewport_height
in the same scaled units — see the querying-posthog-data skill, 
models-heatmaps
.
对于点击类热图，
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
数据，而非混合分析。
若需要分布数据而非单一百分比（例如，按折叠线下方的距离划分点击区间），请直接查询原始
heatmaps
表的SQL，该表中的
y
和
viewport_height
使用相同的缩放单位——参考querying-posthog-data技能，
models-heatmaps
。

Step 3: Name the hot elements (autocapture overlap)

步骤3：标记热门元素（关联自动捕获数据）

For each notable cluster, find what's actually there. Query autocapture on the same URL — either via the 
exploring-autocapture-events
skill or directly:
sql
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
gives the selector/DOM path when you need to disambiguate two elements with the same text. Match autocapture's top elements to the heatmap's hot coordinates: clicks concentrated on something that is not a link or button (plain text, an image, a disabled control) is a classic "users expect this to be clickable" finding.
对于每个值得关注的集群，确定实际对应的元素。查询同一URL的自动捕获数据——可通过
exploring-autocapture-events
技能或直接执行以下SQL：
sql
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路径。将自动捕获数据中的热门元素与热图中的热门坐标进行匹配：点击集中在非链接或非按钮的元素上（纯文本、图片、禁用控件）是典型的“用户认为这个元素可点击”的发现。

Step 4: Give the user a heatmap to look at (optional)

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

You can't see the page, but the user can. When a visual would help them follow your findings, create a saved heatmap so they can open the rendered page with the data overlaid in PostHog:
  1. heatmaps-saved-create
    with the page 
    url
    (type defaults to 
    screenshot
    ). This enqueues a headless render — it is asynchronous. Pass 
    widths
    matching the viewport band you analyzed in Step 2.
  2. Poll 
    heatmaps-saved-get
    (by the returned 
    short_id
    ) until 
    status
    is 
    completed
    , then tell the user it's ready to view in PostHog.
This is for the human's benefit — your own reasoning still comes from the Step 2 data and the Step 3 autocapture identity, not from the picture.
你无法看到页面，但用户可以。当可视化内容有助于用户理解你的分析结果时，创建一个保存的热图，以便用户在PostHog中打开渲染好的叠加数据页面：
  1. 使用页面
    url
    调用
    heatmaps-saved-create
    （类型默认为
    screenshot
    ）。这会触发无头渲染——该过程是异步的。传入与步骤2中分析的视口分段匹配的
    widths
    参数。
  2. 通过返回的
    short_id
    轮询
    heatmaps-saved-get
    ，直到
    status
    变为
    completed
    ，然后告知用户热图已可在PostHog中查看。
这是为了方便用户——你自身的分析仍基于步骤2的数据和步骤3的自动捕获元素身份，而非可视化图片。

Step 5: Drill into hotspots (when you need the "why")

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

For a surprising cluster, 
heatmaps-events
returns the individual sessions behind specific 
points
. Hand the session IDs to the 
investigating-replay
skill to watch what people actually did.
对于意外的集群，
heatmaps-events
会返回特定
points
背后的单个会话信息。将会话ID交给
investigating-replay
技能，查看用户的实际操作过程。

Step 6: Summarize and recommend

步骤6：总结并提出建议

Produce a short, concrete report:
  • What the heatmap shows — top engaged elements, dead zones, scroll reach, and the above/below-the-fold click split (e.g. "viewport is ~600px for most visitors, yet 35% of clicks land below it").
  • Problems, ranked by signal strength — rage-click clusters first, then clicks on non-interactive elements, then important CTAs sitting below the scroll cliff, then ignored primary actions.
  • Recommendations tied to evidence — move/raise a CTA above the fold, make a clicked-but-dead element a real link, cut competing elements near a rage-click cluster, etc. Every recommendation should cite the signal it came from.
生成一份简短、具体的报告：
  • 热图展示的内容——互动最多的元素、无互动区域、滚动范围，以及折叠线上下的点击分布（例如：“大多数访客的视口约为600px，但35%的点击落在折叠线下方”）。
  • 问题——按信号强度排序：首先是狂点集群，然后是点击非交互元素，接着是位于滚动终止点下方的重要CTA，最后是被忽略的主要操作按钮。
  • 基于证据的建议——将CTA移至折叠线以上、将被点击但无交互的元素改为真实链接、移除狂点集群附近的竞争元素等。每条建议都应注明其依据的信号。

Reading the signals

解读信号

SignalLikely meaningTypical recommendation
Rage clicks on an elementBroken, slow, or looks-clickable-but-isn'tFix the handler, add feedback, or make it actually interactive
Many clicks on non-link text/imageUsers expect it to be clickableMake it a link/button, or remove the affordance
Primary CTA gets few clicksBuried, low-contrast, or out-competedRaise it, increase contrast, reduce nearby noise
Scroll cliff before key contentContent/CTA is below where people stopMove it up or add a reason to scroll
High % of clicks below the foldEngaged content sits below the initial viewport — users scroll before interactingMove the most-clicked elements onto the first screen
Hot clicks on nav, cold bodyPage isn't delivering; people bail to navRe-evaluate the page's core content
信号可能的含义典型建议
元素上出现狂点功能损坏、加载缓慢，或看起来可点击但实际不可点击修复处理程序、添加反馈，或使其真正具备交互性
非链接文本/图片上有大量点击用户认为该元素可点击将其改为链接/按钮，或移除可点击的视觉提示
主CTA点击量低位置隐蔽、对比度低，或被其他元素抢占注意力上移位置、提高对比度、减少附近干扰元素
关键内容前出现滚动终止点内容/CTA位于用户停止滚动的位置下方上移内容，或添加吸引用户滚动的理由
折叠线下方的点击占比高用户感兴趣的内容位于初始视口下方——用户在互动前会滚动页面将点击量最高的元素移至首屏
导航栏点击量高，页面主体点击量低页面未满足用户需求，用户转向导航栏重新评估页面的核心内容

Gotchas

注意事项

  • Heatmaps must be opted in (
    Team.heatmaps_opt_in
    ). If 
    heatmaps-list
    returns nothing for a page that clearly gets traffic, capture may be off or the URL is wrong — check both before concluding "no engagement".
  • Coordinates are scaled by a factor of 16 in storage; the API already returns CSS-pixel 
    pointer_y
    and relative x, so use the API/tool values directly rather than the raw table columns.
  • You can't see the screenshot. The saved-heatmap render is for the user to open in PostHog; don't claim to have looked at the page. Ground every layout claim in autocapture identity + coordinates, not vision.
  • Saved-heatmap rendering is async. After 
    heatmaps-saved-create
    , poll 
    heatmaps-saved-get
    until 
    status
    is 
    completed
    before telling the user it's viewable. Only 
    screenshot
    -type heatmaps render an image; 
    iframe
    and 
    recording
    types do not.
  • Mind the viewport. A desktop click map and a mobile one are different pages' worth of behavior — filter with 
    viewport_width_min
    /
    viewport_width_max
    rather than blending them.
  • 热图需要主动启用（
    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
    进行过滤，而非混合分析。