exploring-autocapture-events

探索自动捕获事件

如果用户选择启用，posthog-js 会自动将点击、表单提交和页面变化捕获为 $autocapture 事件。 每个事件都会在 elements_chain 列中记录被点击的 DOM 元素及其祖先元素。

$autocapture 被有意排除在 posthog:read-data-schema 分类体系之外， 因为它只有与自动捕获专用筛选条件（选择器、标签、文本、href）结合使用时才有用。 本技能弥补了这一缺口。

物化列

events 表提供常用元素字段的快速访问方式，无需解析完整的链字符串。

列	类型	描述
elements_chain	String	以分号分隔的完整元素链（参见格式参考）
elements_chain_href	String	链中的最后一个 href 值
elements_chain_texts	Array(String)	所有元素的文本值
elements_chain_ids	Array(String)	所有 id 属性值
elements_chain_elements	Array(String)	有用的标签名称：a、button、input、select、textarea、label

尽可能在探索查询中使用物化列——它们无需通过正则表达式解析。

标准自动捕获属性

来自 posthog-js 的每个 $autocapture 事件都会附带一组固定属性。 不要查询架构来“查找”它们——它们就是以下这些：

属性	示例	说明
$event_type	click、submit、change	交互类型
$el_text	Sign up、Submit	被点击元素的文本
$current_url	https://app.example.com/pricing	交互发生的页面
$elements_chain	以分号分隔的链	通过上方的 elements_chain* 物化列解析

标准事件属性（$browser、$os、$device_type 等）也会存在。

工作流

1. 确认自动捕获数据存在

开始其他操作前，先运行计数查询。 如果计数为零，自动捕获可能已停用。通常有两种情况：

• 项目设置——团队可以在 PostHog 项目设置中设置 autocapture_opt_out
• SDK 配置——posthog-js 的 init() 调用可以传入 autocapture: false

如果没有找到数据，请告知用户，以便他们检查这两项设置。

SELECT count() as cnt
FROM events
WHERE event = '$autocapture'
  AND timestamp > now() - INTERVAL 7 DAY

2. 探索用户正在与哪些内容交互

先使用物化列进行广泛探索。 目标是在缩小范围之前，了解用户点击的内容。

有用的探索方式：

• 点击次数最多的标签名称（通过 elements_chain_elements）
• 点击次数最多的文本值（通过 elements_chain_texts）
• 点击次数最多的 href（通过 elements_chain_href）
• 特定页面的原始 elements_chain 值（通过 properties.$current_url 筛选）

所有模式请参阅示例查询。

3. 查找候选选择器

用户确定关注的交互后，找到能够识别该交互的 CSS 选择器。

选择器属性的优先级（从高到低）：

1. data-attr 或其他 data-* 属性 — 特异性最高，在不同部署之间保持稳定，是开发者有意设置的锚点。 使用 match(elements_chain, 'data-attr=') 或 extractAll 搜索。
2. 元素 ID（attr_id）— 同样非常稳定，可通过 elements_chain_ids 查询。
3. 标签 + 类组合 — 稳定性中等，但 CSS 重构可能会更改类名。
4. 文本内容 — 稳定性较差（文案修改、i18n 都会导致变化），但有时是唯一选择。
5. 仅标签名 — 单独使用范围过宽，可用作限定条件。

找到 data-attr 值后，构造类似 [data-attr="value"] 或 button[data-attr="value"] 的选择器。

4. 检查选择器的唯一性

只有当选择器匹配的是目标交互，而不是无关事件时，它才有用。

使用 elements_chain =~ 和选择器的正则表达式模式检查唯一性。 然后抽样查看匹配的事件，检查选择器实际捕获的内容。 将匹配数量与自动捕获总量进行比较，了解选择器的筛选效果。

好的选择器只匹配一个逻辑交互。 如果它匹配了太多不同元素，请在下一步进一步细化。

5. 添加筛选条件进行细化

如果单独使用选择器仍不够唯一，可叠加其他筛选条件：

• 文本筛选 — 使用 elements_chain_texts 按元素文本内容匹配
• URL 筛选 — 使用 properties.$current_url 限定到特定页面
• Href 筛选 — 使用 elements_chain_href 按链接目标匹配

每次细化后都重新检查唯一性。 只添加必要的筛选条件 — 筛选条件越少，对细微 DOM 变更的适应性越强。

6. 在洞察查询中筛选自动捕获事件

用户需要漏斗、趋势或其他洞察时，筛选器的结构与 HogQL 不同。 FunnelsQuery / TrendsQuery 中的每个步骤都是一个 EventsNode（或 ActionsNode），其中包含 event: "$autocapture" 和 properties 数组。

有两种不同的属性 type 值需要注意 — 二者不可互换：

• type: "element" — 键包括：selector、tag_name、text、href。针对解析后的 elements_chain 进行匹配。运算符支持有所区别：
  • selector 和 tag_name 仅支持 exact 和 is_not — 使用任何其他运算符都会被查询引擎拒绝，并导致查询报错。
  • text 和 href 支持完整的字符串运算符集（exact、is_not、icontains、not_icontains、regex、not_regex、is_set、is_not_set）。
• type: "event" — 键可以是任何规范的自动捕获属性（$event_type、$el_text、$current_url），也可以是事件上的其他任意属性。支持标准事件属性运算符（exact、icontains、regex 等）。

从点击一个按钮到点击另一个按钮的漏斗示例：

{
  "kind": "FunnelsQuery",
  "series": [
    {
      "kind": "EventsNode",
      "event": "$autocapture",
      "properties": [
        {
          "type": "element",
          "key": "selector",
          "value": ["[data-attr=\"autocapture-series-save-as-action-banner-shown\"]"],
          "operator": "exact"
        }
      ]
    },
    {
      "kind": "EventsNode",
      "event": "$autocapture",
      "properties": [
        {
          "type": "element",
          "key": "selector",
          "value": ["[data-attr=\"autocapture-save-as-action\"]"],
          "operator": "exact"
        }
      ]
    }
  ]
}

以下两点很容易弄错：

• 即使只匹配一个选择器，value 也必须是一个数组
• 选择器字符串包含 [data-attr="..."] 包装 — 它是 CSS 选择器，不是裸属性值

决策规则：如果该交互会被引用多次，优先使用操作（ActionsNode 引用现有操作 — 参见第 8 步）；如果是一次性洞察，则内联使用 type: "element" / type: "event" 筛选器；如果需要跨事件联接或执行自定义聚合，则使用原始 HogQL（第 7 步）。

7. 用于临时查询

发现的选择器可直接用于 HogQL，无需创建操作。

趋势 — 按时间统计匹配的点击：

SELECT
  toStartOfDay(timestamp) as day,
  count() as clicks
FROM events
WHERE event = '$autocapture'
  AND timestamp > now() - INTERVAL 14 DAY
  AND elements_chain =~ '(^|;)button.*?data-attr="checkout"'
GROUP BY day
ORDER BY day

漏斗 — 页面浏览到点击的转化：

SELECT
  person_id,
  first_pageview,
  first_click_after
FROM (
  SELECT
    p.person_id,
    p.pageview_time as first_pageview,
    min(c.click_time) as first_click_after
  FROM (
    SELECT person_id, min(timestamp) as pageview_time
    FROM events
    WHERE event = '$pageview'
      AND timestamp > now() - INTERVAL 14 DAY
      AND properties.$current_url ILIKE '%/pricing%'
    GROUP BY person_id
  ) p
  INNER JOIN (
    SELECT person_id, timestamp as click_time
    FROM events
    WHERE event = '$autocapture'
      AND timestamp > now() - INTERVAL 14 DAY
      AND elements_chain =~ '(^|;)button.*?data-attr="signup"'
  ) c ON p.person_id = c.person_id AND c.click_time > p.pageview_time
  GROUP BY p.person_id, p.pageview_time
)

对于定期分析，建议创建操作（下一步），或使用 posthog:query-trends / posthog:query-funnel 和该操作。

8. 创建操作

操作是临时选择器查询的持久化版本。 当筛选条件能够唯一确定交互时，使用 posthog:action-create 创建操作。

仅使用保证唯一性所需的筛选条件构造步骤：

{
  "name": "Clicked checkout button",
  "steps": [
    {
      "event": "$autocapture",
      "selector": "button[data-attr='checkout']",
      "text": "Complete Purchase",
      "text_matching": "exact",
      "url": "/checkout",
      "url_matching": "contains"
    }
  ]
}

$autocapture 可用的步骤字段：

• selector — CSS 选择器（例如 button[data-attr='checkout']）
• tag_name — HTML 标签名（例如 button、a、input）
• text / text_matching — 元素文本（exact、contains 或 regex）
• href / href_matching — 链接 href（exact、contains 或 regex）
• url / url_matching — 页面 URL（exact、contains 或 regex）

创建后，使用 matchesAction() 验证：

SELECT count() as matching_events
FROM events
WHERE matchesAction('Clicked checkout button')
  AND timestamp > now() - INTERVAL 7 DAY

提示

• 始终设置时间戳筛选条件 — $autocapture 的数据量很大
• 对 elements_chain 采样时，LIMIT 尽量设置得宽松 — 字符串可能很长
• elements_chain =~ 运算符会在内部将 CSS 选择器作为正则表达式匹配； 尽可能使用物化列以提升性能
• 此工作流仅适用于 posthog-js — 其他 SDK 不会捕获元素