Explorer les événements d'autocapture

Si les utilisateurs acceptent, posthog-js capture automatiquement les clics, les soumissions de formulaires et les changements de page sous forme d'événements $autocapture. Chaque événement enregistre l'élément DOM cliqué et ses ancêtres dans la colonne elements_chain.

$autocapture est intentionnellement exclu de la taxonomie posthog:read-data-schema car il n'est utile qu'avec des filtres spécifiques à l'autocapture (selector, tag, text, href). Ce skill comble cette lacune.

Colonnes matérialisées

La table events fournit un accès rapide aux champs d'éléments courants sans analyser la chaîne complète.

Utilisez les colonnes matérialisées pour les requêtes d'exploration autant que possible — elles évitent l'analyse regex.

Propriétés canoniques d'autocapture

Chaque événement $autocapture de posthog-js inclut un ensemble fixe de propriétés. Ne consultez pas le schéma pour les « rechercher » — ce sont celles-ci :

Les propriétés d'événement standard ($browser, $os, $device_type, etc.) sont également présentes.

Flux de travail

1. Confirmer que les données d'autocapture existent

Lancez une requête de comptage avant toute chose. Si le comptage est zéro, l'autocapture peut être désactivé. Cela se produit de deux façons :

• Paramètres du projet — l'équipe peut définir autocapture_opt_out dans les paramètres du projet PostHog
• Configuration du SDK — l'appel init() de posthog-js peut passer autocapture: false

Informez l'utilisateur si aucune donnée n'est trouvée pour qu'il puisse vérifier les deux paramètres.

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

2. Explorer ce avec quoi les utilisateurs interagissent

Commencez large en utilisant les colonnes matérialisées. L'objectif est de comprendre sur quoi les utilisateurs cliquent avant de réduire.

Explorations utiles :

• Noms de balises les plus cliqués (via elements_chain_elements)
• Valeurs de texte les plus cliquées (via elements_chain_texts)
• Hrefs les plus cliqués (via elements_chain_href)
• Valeurs brutes elements_chain pour une page spécifique (filtrées par properties.$current_url)

Voir exemples de requêtes pour tous les modèles.

3. Trouver les sélecteurs candidats

Une fois que l'utilisateur identifie une interaction qui l'intéresse, trouvez un sélecteur CSS qui l'identifie.

Ordre de priorité pour les attributs de sélecteur (le meilleur d'abord) :

1. *Attributs data-attr ou autres `data-** — spécificité la plus élevée, stable entre les déploiements, ancres destinées aux développeurs. Recherchez avecmatch(elements_chain, 'data-attr=')ouextractAll`.
2. ID d'élément (attr_id) — aussi très stable, interrogeable via elements_chain_ids.
3. Combinaison de balise + classe — modérément stable mais les classes changent avec les refactorisations CSS.
4. Contenu textuel — fragile (change avec les modifications de copie, i18n) mais parfois la seule option.
5. Nom de balise seul — trop large en soi, utile comme qualificatif.

Quand une valeur data-attr est trouvée, construisez un sélecteur comme [data-attr="value"] ou button[data-attr="value"].

4. Évaluer l'unicité du sélecteur

Un sélecteur n'est utile que s'il correspond à l'interaction prévue et non à des événements non liés.

Lancez une vérification d'unicité en utilisant elements_chain =~ avec le modèle regex pour le sélecteur. Ensuite, échantillonnez les événements correspondants pour inspecter ce que le sélecteur capture réellement. Comparez le comptage par rapport au volume total d'autocapture pour comprendre la sélectivité.

Un bon sélecteur correspond à une seule interaction logique. S'il correspond à trop d'éléments distincts, affinez-le à l'étape suivante.

5. Affiner avec des filtres supplémentaires

Si le sélecteur seul n'est pas assez unique, superposez des filtres supplémentaires :

• Filtre de texte — correspondance par contenu textuel d'élément en utilisant elements_chain_texts
• Filtre d'URL — restriction à une page spécifique en utilisant properties.$current_url
• Filtre de href — correspondance par cible de lien en utilisant elements_chain_href

Relancez la vérification d'unicité après chaque affinement. N'incluez que les filtres nécessaires — moins de filtres signifie plus de résilience aux petits changements du DOM.

6. Filtrer l'autocapture dans une requête d'insight

Quand l'utilisateur veut un funnel, une tendance ou un autre insight, la forme du filtre diffère de HogQL. Chaque étape dans un FunnelsQuery / TrendsQuery est un EventsNode (ou ActionsNode) avec event: "$autocapture" et un tableau properties.

Deux valeurs distinctes de type de propriété importent — elles ne sont pas interchangeables :

• type: "element" — clés : selector, tag_name, text, href. Mis en correspondance avec la elements_chain analysée. Le support d'opérateur est divisé :
  • selector et tag_name supportent uniquement exact et is_not — tout le reste lève NotImplementedError dans le compilateur de requête (posthog/hogql/property.py).
  • text et href acceptent l'ensemble complet d'opérateurs de chaîne (exact, is_not, icontains, not_icontains, regex, not_regex, is_set, is_not_set).
• type: "event" — clés : l'une quelconque des propriétés canoniques d'autocapture ($event_type, $el_text, $current_url) ou tout autre élément de l'événement. Opérateurs de propriété d'événement standard (exact, icontains, regex, etc.).

Exemple de funnel du clic d'un bouton au clic d'un autre :

{
  "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"
        }
      ]
    }
  ]
}

Deux choses faciles à mal faire :

• value est un tableau même quand il correspond à un seul sélecteur
• La chaîne de sélecteur inclut le wrapper [data-attr="..."] — c'est un sélecteur CSS, pas une valeur d'attribut brute

Règle de décision : préférez une action (ActionsNode référençant une action existante — voir étape 8) quand l'interaction sera référencée plus d'une fois ; utilisez les filtres type: "element" / type: "event" inline quand c'est un insight ponctuel ; HogQL brut (étape 7) quand vous joignez des événements ou faites des agrégations personnalisées.

7. Utiliser dans les requêtes ad-hoc

Le sélecteur découvert peut être utilisé directement dans HogQL sans créer une action.

Tendances — comptage des clics correspondants au fil du temps :

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

Funnel — conversion pageview en clic :

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
)

Pour une analyse récurrente, préférez créer une action (étape suivante) ou utiliser posthog:query-trends / posthog:query-funnel avec l'action.

8. Créer une action

Les actions sont la version durable des requêtes de sélecteur ad-hoc. Une fois que les critères identifient uniquement l'interaction, créez une action en utilisant posthog:action-create.

Construisez l'étape avec seulement les filtres nécessaires pour l'unicité :

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

Champs d'étape disponibles pour $autocapture :

• selector — sélecteur CSS (ex. button[data-attr='checkout'])
• tag_name — nom de balise HTML (ex. button, a, input)
• text / text_matching — texte d'élément (exact, contains, ou regex)
• href / href_matching — href de lien (exact, contains, ou regex)
• url / url_matching — URL de page (exact, contains, ou regex)

Après création, vérifiez avec matchesAction() :

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

Conseils

• Définissez toujours des filtres de timestamp — $autocapture est un volume élevé
• Utilisez LIMIT généreusement lors de l'échantillonnage de elements_chain — les chaînes peuvent être longues
• L'opérateur elements_chain =~ met en correspondance les sélecteurs CSS sous forme de regex en interne ; préférez les colonnes matérialisées quand possible pour les performances
• Ce flux de travail s'applique uniquement à posthog-js — les autres SDK ne capturent pas les éléments