LaBrowser / Docs
Examples Console

Site Augmentation

Apply controlled, auditable hide/remove changes to live pages participants visit, scoped by URL pattern, with reusable templates and per-action audit events.

Configuration is usually set up for you

Most LaBrowser studies have their configuration provided as a managed service — you typically won't need to assemble this by hand. This reference documents every option in full, so you can understand what's configured for your study, or self-serve the details if you prefer.

Overview

Site augmentation lets an operator make controlled, declarative changes to the live websites participants visit — specifically, hiding or removing page elements selected by CSS selector and scoped to a URL pattern. It is an intervention tool: where capture rules observe what participants do, augmentation changes what they see, so you can compare conditions (for example, with and without a recommendation shelf) within the same study.

Augmentation is deliberately narrow. The console's own framing is the boundary: operator-only, no arbitrary researcher JavaScript, no remote plugin code. A study config can only describe ordinary hide and remove actions; there is no mechanism to inject scripts, load remote code, or upload custom plugins. This keeps every change reviewable and reproducible.

Augmentation is distinct from capture. It does not record anything on its own — it modifies the page and emits an audit trail of what it changed. To record what participants did, see capture rules.

How It Works

Augmentation runs inside the LaBrowser browser runtime as each page loads. For every enabled plugin whose url_pattern matches the current URL, LaBrowser evaluates each action's selector, finds the matching elements, and applies the action:

  • hide — sets display: none on the matched elements (reversibly).
  • remove — detaches the matched elements from the DOM.

Because modern sites render content dynamically, LaBrowser keeps watching the page with a mutation observer and re-applies matching actions when new content appears. Every mutation is tracked: when the participant navigates away or the page is torn down, hidden elements are restored and removed elements are re-inserted, and a cleaned_up audit event is emitted. Each action can emit a SITE_AUGMENTATION_AUDIT event recording exactly what it matched and did — the evidence that proves what a participant actually saw.

Site Plugins

Augmentation is configured as a list of site plugins. Each plugin scopes a set of actions to a URL pattern. Plugins live under the top-level site_plugins key of the study configuration.

site_plugins SitePlugin[]

Default: []

Array of site plugins for this study. Each plugin targets a URL pattern and carries the actions applied to matching pages. Empty by default — no augmentation runs unless plugins are configured.

Plugin Fields

id string Required
Unique identifier for this plugin. Used as the marker for the elements it augments and surfaced in audit events as plugin_id.
name string

Default: ""

Human-readable name shown in the console and carried into audit events as plugin_name.
description string

Default: ""

Free-text note describing what this plugin does and why. Templates record their origin here (e.g. which built-in template produced the plugin).
url_pattern string Required
Regular expression matched (case-insensitively) against the page URL. The plugin's actions only run on pages whose URL matches. Keep it specific — broad patterns like https://*/* trigger a warning.
enabled boolean

Default: true

Whether this plugin runs. When false, none of its actions are applied, even if individual actions are enabled.
actions SitePluginAction[]

Default: []

The hide/remove actions this plugin applies on matching pages. See Actions below.
triggers SitePluginTrigger[]

Default: []

Advanced, operator-only event extraction triggers. Triggers are preserved by the console but are not edited through the standard augmentation UI, which focuses on hide/remove actions. Most studies leave this empty.

Actions

An action is a single hide-or-remove operation against a CSS selector. Each action carries a human-readable reason (recorded in the audit trail) and bounded limits that keep its blast radius small.

id string Required
Unique identifier for this action within its plugin (1–80 characters). Combined with the plugin ID, it marks augmented elements and appears in audit events as action_id.
action "hide" | "remove" Required
What to do with matched elements. hide sets display: none (restored on cleanup); remove detaches the element from the DOM (re-inserted on cleanup).
selector string Required
CSS selector for the target element(s), 1–500 characters. Scope it to the specific container you want to change — not the whole page. Selectors targeting browser/system plumbing or the page root are rejected; see Safety & Guardrails.
reason string Required
Short human-readable reason for the change, 1–160 characters. Recorded in every audit event so reviewers know the study-design intent behind the mutation.
enabled boolean

Default: true

Whether this action runs. A disabled action is skipped and emits a skipped audit event with reason action_disabled.
max_matches number

Default: 1

Maximum number of elements this action may affect (1–20). If the selector matches more than this, the action is skipped (reason matched_count_exceeds_limit) rather than applied broadly. Values above 5 trigger a warning.
once_per_page boolean

Default: true

When true, the action applies at most once per page load, even as the page mutates. When false, it re-applies to newly appearing matches throughout the page's lifetime.
audit boolean

Default: true

Whether this action emits SITE_AUGMENTATION_AUDIT events. Keep it on — disabling it removes your evidence of what changed and triggers an operator warning.

Safety & Guardrails

Augmentation is bounded by design. The console validates configuration before save, and the browser runtime independently re-checks every action before applying it — defense in depth, so an unsafe action is refused at runtime even if it slips past the editor.

What augmentation will not do

  • Forbidden targets. Selectors that target script, style, link (stylesheets), iframe, webview, html, body, or head — or use ::pseudo-element syntax — are rejected. Augmentation only touches ordinary content elements, never page plumbing.
  • Broad selectors. Page-wide selectors like *, body, html, head, and :root are flagged as too broad.
  • Broad URL patterns. Patterns like *, https://*/*, and http://*/* are flagged as affecting too many pages.
  • Match limits. max_matches is capped at 1–20, and the runtime enforces a hard ceiling of 50 mutations per page. An action matching more elements than its limit is skipped, not applied broadly.
  • Audit pressure. Turning audit off weakens your review evidence and raises a warning — keep it on.

Templates

Templates are built-in, versioned starting points so you don't have to write selectors from scratch. You pick a template, fill in its variables (URL pattern, selector, reason, match limit), choose how to merge it into the study, and the console materializes ordinary site plugins from it. Each template ships with operator notes and a list of risks, and writes only standard hide/remove actions — no JavaScript, no remote code, no researcher-uploaded plugins.

  • Recommendation shelf suppression (generic) — hides one bounded recommendation shelf on matching pages using a selector you supply. The general-purpose template for suppressing a "you might also like" style module on any retail site.
  • Reference example template — a built-in example-scope template that hides paid-service-style product recommendation shelves on a specific retailer, demonstrating selector patterns (such as attribution-link matching) for a concrete site. It is a worked reference, not a boundary of the system: live DOM varies by locale, device, and A/B test, so production studies should do selector fieldwork before relying on it unchanged.

Apply Modes

When you apply a template, you choose how it merges into the study's existing site plugins:

  • Add as new plugin — appends the resolved plugin. If the ID already exists, a numeric suffix is added.
  • Merge into existing plugin — appends the template's actions into the matching plugin while preserving its triggers.
  • Replace matching actions — replaces only the actions whose IDs match the template's, keeping any manually authored actions.

Audit Events

Every action with audit enabled emits a SITE_AUGMENTATION_AUDIT event for each outcome, stored in the session event database alongside all other captured events. The audit trail is the evidence of exactly what augmentation did on the participant's page: which plugin and action ran, the outcome, how many elements matched, and lightweight fingerprints of the affected elements.

Outcomes are applied (the change took effect), skipped (a guardrail or condition prevented it — e.g. URL not matched, selector too broad, match limit exceeded, or no elements found), failed (an error occurred while applying), and cleaned_up (the change was reverted on navigation/teardown). See the Event Reference for the full payload.

Configuring in the Console

Site augmentation is set up in the Site Augmentation Actions section of the study form. From there you can:

  • Add site plugin — create an empty plugin and fill in its URL pattern and actions by hand.
  • Apply template — start from a built-in template, customize its variables, pick an apply mode, and preview the resolved JSON before applying.
  • Add action — add a hide/remove action to a plugin, with live validation surfacing errors and warnings inline.

The editor counts plugins, actions, and warnings as you go, and a read-only raw config preview shows exactly what will be written to site_plugins. Blocking errors must be resolved before the study can be saved. For where this fits among the other study options, see the Study Configuration reference.