AI Element Picker

Most of the work in a traditional tag manager is wiring CSS selectors to event names. The AI Element Picker eliminates that step — you click an element on the customer site and Gemini proposes the selector, event name, and variable definitions.

How It Works

1. From Tag Manager > Preview Mode, open the customer site with the preview cookie set.
2. Click 🎯 Element Picker in the floating overlay.
3. The tracker enters element-picker mode: hovering highlights elements with a Shadow-DOM outline, clicking sends the element's HTML + parent context + DOM path to the admin UI via postMessage.
4. The admin UI calls POST /p/:siteKey/preview/ai-element with the captured payload.
5. The server calls Gemini with three tool declarations:
   • propose_selector(strategy, value) — preferred selector (data-* > id > unique class combo > nth-child fallback)
   • propose_event_name(name, description) — semantic event name like add_to_cart_click
   • propose_variables(name, source, path)[] — variables to extract from the element or its context
6. The proposed selector is post-validated against the captured HTML before being returned — if it doesn't uniquely match the original element, the server retries with a tighter strategy or returns reason: 'selector_ambiguous'.
7. You see the suggestion in the admin UI; clicking Apply creates a Tag + Trigger + the proposed Variables in the active workspace.

Selector Strategy

Gemini is prompted to prefer selectors in this priority order:

1. data-* attributes (most stable across site refactors).
2. id attribute (only if it doesn't look auto-generated — UUIDs, hash-suffixed IDs, and obvious build-tool patterns are rejected).
3. A unique combination of classes (the smallest set that uniquely identifies the element on the page).
4. tag:nth-of-type(N) as a last resort (fragile — the picker explicitly warns when this is what gets used).

The model is also told to look at the surrounding DOM context (5 ancestor levels) so it can suggest selectors that survive sibling reordering.

What Gets Sent to Gemini

Only what's needed to identify the element:

• The element's outerHTML, truncated at 20 KB. Larger elements return 413 element_html_too_large — pick a more specific sub-element.
• The 5 nearest ancestor tags with their classes / ids (no inner text or other children).
• The page's URL and title.

No cookies, localStorage, or other PII leave the customer's browser. The picker runs entirely client-side until the user clicks Apply.

Rate Limiting

The endpoint is wildcard-CORSed because preview cookies authenticate it, but it's still rate-limited:

• 12 calls per IP per minute per siteKey (PICKER_RATE_LIMIT_PER_IP = 12 in snippetRoutes.js).
• Rate-limit window is rolling.

The limit is intentionally low because each call costs ~5K Gemini input tokens (the element + context + tool declarations).

When It Returns No Suggestion

The endpoint returns 422 { reason } when:

reason	Meaning
element_required	The picked element had neither html nor tag — likely a bug in the picker overlay.
selector_ambiguous	Gemini's proposed selector matched multiple elements on the page after post-validation.
low_confidence	Gemini wasn't confident enough to commit — the element is too generic (e.g. raw <div>).
not_actionable	The element looks like layout, not an interactive control.

When you see low_confidence or not_actionable, pick a more specific element (e.g. the <button> inside the wrapper <div>).

Cost & LLM Usage Logging

Every call is logged in the per-tenant llmUsageModel collection with the model name, input tokens, output tokens, and the action that triggered it ('tag-manager-element-picker'). This rolls into the same billing-limits stack as voice / chat agents — see the Billing docs for how the budget is enforced.

The model is configurable via ANALYTICS_AI_MODEL (default gemini-3-flash-preview). Flash is intentionally chosen over Pro because the picker is interactive and latency-sensitive; tag suggestions from the batch path (Event Definitions inbox) use the same model but can afford Pro if you set ANALYTICS_AI_MODEL_BATCH.

Privacy Considerations

The picker is admin-only via the preview cookie, but you should still be aware:

• The captured HTML can include text content from the customer's site. If the site contains PII in the DOM (e.g. an order-confirmation page), that text is sent to Gemini.
• Gemini API calls happen through Google's standard API with the project's own API key. Per Google's terms, prompts and outputs are not used to train Google's models by default for paid API keys.
• If you don't want Gemini to see anything from a particular page, don't pick elements on it — use the standard Tag Manager UI to write the selector by hand.

When Not to Use It

• For very simple selectors (e.g. #signup, [data-test="cart"]), it's faster to type them in the Tag Manager UI directly.
• For elements that don't exist in the initial DOM (lazy-loaded modals, etc.), the picker can't see them until they're rendered. Trigger the lazy load first, then pick.
• For SPA frameworks that generate new class names on every build (CSS-in-JS, Tailwind JIT-stripped), the picker will recommend nth-of-type fallbacks — those are fragile. Ask the site team to add a data-track-id="..." attribute and re-pick.