Event definitions & triggers

An event definition turns interactions into named conversion events without touching your site's code. Definitions are created in the dashboard (or by AI suggestion), served to the tag via /v1/config, and matched client-side - so a definition you save now starts firing on visitors' next page load.

Anatomy

Field	Meaning
`name`	snake_case identifier, unique per site (`hero_cta_clicked`). Normalized automatically: lowercased, spaces → `_`, other characters stripped
`trigger`	`click`, `submit`, `visible` or `pageview`
`selector`	CSS selector - required for every trigger except `pageview`
`url_pattern`	Pathname filter with `*` wildcards; empty matches every page
`text_contains`	Case-insensitive substring filter on the element's text
`value_selector`	CSS selector of the element showing the amount (`.order-total`); parsed as money at fire time and sent as `value` unless the event already has one
`field_selectors`	`{ email, phone, first_name, last_name, city, state, zip, country }` → CSS selectors of the inputs holding them; read live at fire time and hashed server-side as match keys. Pick them by clicking with the browser extension
`properties`	Extra properties merged into every fired event
`conversion_event`	Optional conversion type (`purchase`, `add_to_cart`, `lead`, …). Empty = analytics-only; set = forwarded to Meta CAPI, TikTok and GA4 with browser/server deduplication
`destinations`	Per-event routing flags (`{facebook, tiktok, ga4}`). An absent key means send; an explicit `false` turns that platform off for this one event — browser pixel and server-side both, so a disabled side never gets half a deduplicated pair
`enabled`	Disabled definitions stay saved but are not served to the tag

Recommended conversions by business category

Conversion pickers in the dashboard and the browser extension list the events recommended for your site's business category first (set in site settings - E-commerce & Retail, Entertainment & Media, Education, Real Estate, Technology, Financial Services, Automotive, Travel, or Other). A real-estate site sees lead / schedule / submit_application up top; a store sees the purchase funnel. The category orders suggestions only - every site can map any conversion type.

Triggers

click - a delegated, capture-phase listener; matches via target.closest(selector), so clicks on child elements (an icon inside a button) still count.
submit - same mechanics on form submission.
visible - an IntersectionObserver at 50% visibility; fires once per element per page load (useful for "saw the reviews section" style events).
pageview - fires on each pathname change matching url_pattern (initial load, back/forward, and SPA navigations).

Per-platform mapping (Meta CAPI / GA4 / TikTok tabs)

Dashboard → Events has one mapping tab per ad platform. Each tab lists that platform's standard events in its own vocabulary (AddToCart, begin_checkout, PlaceAnOrder, …), which of your tracked events feeds each one, and a per-row toggle that switches that platform on or off for that one event. Configure mapping opens a modal that assigns discovered elements to each standard event in bulk.

The same platform choice exists in the browser extension's Mapping target selector: map an event "for Meta CAPI" and the definition is created routing to Meta only — the other platforms switch on when you map the event from their own tab or extension mode. The default target ("All platforms") keeps the classic behavior: one mapping, every connected destination.

The extension's target selector also lists your saved funnels: pick one and map each step to real elements/pages. A step mapping writes a definition named after the step's own event (with its conversion attached when it has one), so the funnel chain built in Dashboard → Funnels is fed verbatim.

URL patterns

Empty → matches everything.
No * → exact pathname match (/pricing also matches /pricing/).
With * → each * matches any characters: /products/*, */checkout.
Patterns match the pathname only - query strings are ignored.

Fired event shape

Matched events flow through the exact same pipeline as code-level signals.track() calls - enrichment, rollups and destination fan-out included. They carry marker properties: $remote_event: true, $definition_id, plus $el_text / $el_href and any data-signals-* properties found on the element.