Study Configuration | LaBrowser Docs for Behavioral Studies

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.

Allowed Domains

The domain whitelist controls which websites participants can visit during a study. Navigation to a domain not on the list shows a "blocked" page. Subdomains must be listed explicitly — google.com does not match maps.google.com.

allowed_domains string[] | "*"

Default: "*" (all domains)

List of domain patterns participants can visit, or the wildcard "*" to allow any domain. When set to an explicit list, only those domains are reachable. The default allows all domains.

free_web boolean

Default: true

When true, disables domain enforcement entirely. Participants can visit any website. Overrides allowed_domains.

Input Capture Rules

Input capture rules define how LaBrowser detects and records text input from form fields. Each rule matches a specific type of input on a specific service, identified by URL pattern and CSS selector.

input_capture_rules InputCaptureRule[]

Default: []

Array of rules that match form fields for text capture. Each rule identifies a field by its service, URL pattern, and CSS selector, then specifies how submission is detected.

Pre-built rules for Google Search, ChatGPT, and other services are available in the rule catalog. You can use them as-is or customize them for your study. See the Rule Catalog section below.

Rule Fields

name string Required

Unique identifier for this capture rule. Used to reference the rule in events and diagnostics.

description string

Default: ""

Human-readable description of what this rule captures and how it works.

field_role string Required

Role identifier for the input field. Standard roles: search_query, chat_prompt, site_search, generic_input. Custom roles use the custom_* prefix.

service string Required

Service name this rule applies to: google, chatgpt, claude, perplexity, amazon, gemini, custom_tool, or any.

url_pattern string Required

Regular expression to match the page URL where this rule applies.

selector string Required

CSS selector for the input field element.

capture_mode "submit_only"

Default: submit_only

When input text is captured. Currently only submit_only is supported, meaning text is recorded when a submission trigger fires.

submit_triggers object

Object controlling which user actions count as a submission. Each field is a boolean toggle:

submit_triggers.enter_key boolean

Default: true

Capture when the user presses Enter in the field.

submit_triggers.form_submit boolean

Default: true

Capture when the enclosing form fires a submit event.

submit_triggers.button_click boolean

Default: true

Capture when a submit button is clicked (requires submit_button_selector).

submit_triggers.dom_change_heuristic boolean

Default: false

Capture when DOM changes suggest the input was consumed (e.g., the field clears after submission).

submit_button_selector string | null

Default: null

CSS selector for the explicit submit button. Only needed when button_click is enabled as a submit trigger.

Response Capture Rules

Response capture rules define how LaBrowser detects and records AI assistant responses. Each rule targets a specific service and specifies how to extract the response text and detect when generation is complete.

response_capture_rules ResponseCaptureRule[]

Default: []

Array of rules for capturing AI assistant outputs. Each rule identifies a response container by service, URL, and CSS selector, then specifies a completion signal.

Rule Fields

name string Required

Unique identifier for this response capture rule.

description string

Default: ""

Human-readable description of what this rule captures.

service string Required

Which AI service this rule targets.

url_pattern string Required

Regular expression for matching the page URL.

response_selector string Required

CSS selector for the response container element.

response_text_selector string | null

Default: null

Optional inner selector for extracting the text content within the response container. If null, the full container text is captured.

completion_signal ResponseCompletionSignal Required

How to detect that the AI has finished generating a response. See sub-fields below.

extract_last_only boolean

Default: true

Only capture the latest response, avoiding duplicates from earlier messages in the conversation.

max_response_bytes number

Default: 524288 (512KB)

Maximum response size in bytes. Responses exceeding this limit are truncated.

Completion Signal

The completion signal determines how LaBrowser knows an AI response has finished streaming. Three detection methods are available, each suited to different service behaviors.

completion_signal.method "mutation_silence" | "class_removal" | "element_removal" Required

Detection method. mutation_silence waits for DOM mutations to stop for silence_ms. class_removal fires when signal_class is removed from the response element. element_removal fires when the element matching signal_selector is removed from the DOM.

completion_signal.silence_ms number

Default: 2000

Milliseconds of DOM mutation silence before a response is considered complete. Used with the mutation_silence method.

completion_signal.signal_class string | null

Default: null

CSS class whose removal signals completion. Used with the class_removal method.

completion_signal.signal_selector string | null

Default: null

CSS selector for an element whose removal signals completion. Used with the element_removal method.

Experiment Pane

The experiment pane is an optional side panel displayed alongside the browser. Use it to show study instructions, surveys, or custom web content to participants while they browse.

experiment_pane.enabled boolean

Default: false

Whether the experiment pane is visible during sessions.

experiment_pane.mode "markdown" | "url" Required

Content type for the pane. Use markdown for static instructions or url to embed an external page.

experiment_pane.markdown string | null

Default: null

Markdown content to display in the pane. Used when mode is markdown.

experiment_pane.url string | null

Default: null

URL to embed in the pane. Used when mode is url.

experiment_pane.params ExperimentPaneParams

Default: {}

Parameters controlling what context is passed to the embedded URL. See sub-fields below.

Pane Parameters

When using URL mode, these parameters control what session context is appended as query parameters to the embedded URL. This allows external survey tools to receive participant context.

params.pass_participant_id boolean

Default: true

Append the participant ID as a query parameter to the URL.

params.pass_session_id boolean

Default: true

Append the session ID as a query parameter to the URL.

params.pass_participant_fields boolean

Default: false

Append all participant custom fields as query parameters.

params.extra_params Record<string, string>

Default: {}

Additional static key-value pairs to append as query parameters.

Session Settings

start_url string | null

Default: null

The URL loaded when a participant starts their session. This is the first page they see after entering their start code. When null, no start URL is set.

start_url_params string[]

Default: []

List of URL parameter names to capture from the start URL and store as session metadata.

max_session_length_seconds number | null

Default: null (no limit)

Maximum session duration in seconds. When the limit is reached, the session ends automatically. When null, sessions have no time limit.

allow_rejoin boolean

Default: false

Whether participants can rejoin using the same start code after their session ends. When false, each start code can only be used once.

Recruitment

Recruitment settings control how external participant identifiers (from platforms like Prolific or MTurk) are captured and stored alongside session data.

recruitment.participant_id_param string | null

Default: null

URL parameter name for the external participant ID. For Prolific, this is typically PROLIFIC_PID.

recruitment.platform_study_id_param string | null

Default: null

URL parameter name for the external study ID from the recruitment platform.

recruitment.capture_params string[]

Default: []

Additional URL parameters to capture and store from the join URL.

Join URL parameters

Recruitment parameters are captured from the join URL, not from within LaBrowser. Make sure your recruitment platform link includes the correct parameters.

Privacy & Artifacts

anonymize_emails boolean

Default: true

Replace email addresses in captured text with deterministic anonymized tokens. The same email always maps to the same token within a session, preserving referential identity. Different sessions generate different tokens to prevent cross-session tracking.

consent_text string | null

Default: null

Consent text shown to participants before they begin their session. Participants must acknowledge this text to proceed.

show_recording_indicator boolean

Default: true

Show a visible recording indicator in the browser UI so participants know their activity is being captured.

Screenshot Config

Controls automatic screenshot capture during sessions.

screenshot_config.enabled boolean

Default: false

Enable automatic screenshot capture.

screenshot_config.on_events CaptureTriggerEvent[]

Default: []

List of event types that trigger a screenshot. Valid values: NAVIGATE, PAGE_LOADED, INPUT_SUBMIT, AI_RESPONSE, CLICK, TAB_SWITCHED.

screenshot_config.on_idle_ms number | null

Default: null

Take a screenshot after this many milliseconds of user inactivity. Minimum 2000ms. When null, idle screenshots are disabled.

screenshot_config.interval_seconds number | null

Default: null

Take periodic screenshots at this interval in seconds. Minimum 5 seconds. When null, interval screenshots are disabled.

screenshot_config.jpeg_quality number

Default: 80

JPEG compression quality for screenshots, from 1 (lowest) to 100 (highest).

DOM Snapshot Config

Controls automatic DOM snapshot capture during sessions.

dom_snapshot_config.enabled boolean

Default: false

Enable automatic DOM snapshot capture.

dom_snapshot_config.on_events CaptureTriggerEvent[]

Default: []

List of event types that trigger a DOM snapshot. Valid values: NAVIGATE, PAGE_LOADED, INPUT_SUBMIT, AI_RESPONSE, CLICK, TAB_SWITCHED.

dom_snapshot_config.on_idle_ms number | null

Default: null

Take a DOM snapshot after this many milliseconds of user inactivity. Minimum 2000ms. When null, idle snapshots are disabled.

dom_snapshot_config.interval_seconds number | null

Default: null

Take periodic DOM snapshots at this interval in seconds. Minimum 5 seconds. When null, interval snapshots are disabled.

dom_snapshot_config.compress boolean

Default: true

Compress DOM snapshots to reduce storage size.

enabled_parsers string[]

Default: []

List of parser IDs to run on completed sessions. Parsers extract structured data from raw events (e.g., Google search sessions, ChatGPT conversations).

Rule Catalog

LaBrowser ships with pre-built capture rules for common services. These can be added to a study directly from the console UI, or used as templates for custom rules.

The catalog includes 6 pre-built rules: 3 input capture rules and 3 response capture rules.

Input Capture Rules

Capture All Inputs (default) — catches text from all standard input fields on every page. Acts as a safety net for sites without a specific rule.
Google Search — captures search queries submitted to Google via the search box.
ChatGPT Prompt — captures prompts sent to ChatGPT via the message input.

Response Capture Rules

ChatGPT Response — captures AI responses from ChatGPT using mutation silence detection (2s).
Claude Response — captures AI responses from Claude.ai using mutation silence detection (3s).
Gemini Response — captures AI responses from Google Gemini by detecting removal of the progress bar element.