exploring-autocapture-events

autocapture イベントを調べる

ユーザーがオプトインすると、posthog-js はクリック、フォーム送信、ページ遷移を $autocapture イベントとして自動的にキャプチャします。 各イベントでは、クリックされた DOM 要素とその祖先要素が elements_chain カラムに記録されます。

$autocapture は、autocapture 固有のフィルター（セレクター、タグ、テキスト、href）でのみ役立つため、posthog:read-data-schema の分類から意図的に除外されています。 このスキルはその不足を補います。

マテリアライズドカラム

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

可能な場合は、探索クエリにマテリアライズドカラムを使用してください。正規表現による解析を避けられます。

autocapture の標準プロパティ

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. autocapture データが存在することを確認する

ほかの作業を始める前に、件数をクエリします。 件数が 0 の場合、autocapture が無効になっている可能性があります。次の 2 つの理由が考えられます。

• プロジェクト設定 — チームが 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 の各ステップは、event: "$autocapture" と properties 配列を持つ EventsNode（または ActionsNode）です。

2 種類の異なるプロパティ 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"
        }
      ]
    }
  ]
}

間違えやすい点が 2 つあります。

• 単一のセレクターに一致させる場合でも、value は配列です
• セレクター文字列には [data-attr="..."] のラッパーが含まれます。これは CSS セレクターであり、属性値だけではありません

判断基準：インタラクションを複数回参照する場合は、既存のアクションを参照するアクション（ActionsNode。Step 8 を参照）を優先します。1 回限りのインサイトにはインラインの type: "element" / type: "event" フィルターを使います。イベントをまたいだ結合やカスタム集計には生の HogQL（Step 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 では要素はキャプチャされません。