Skip to main content
auto_capture controls what your SDK collects automatically (clicks, inputs, text, etc.) and how sensitive data is masked or excluded.

​
Quick start

window.userpilotSettings = {
  token: APP_TOKEN,
  auto_capture: {
    enabled: true,
    excluded_elements: [".no-track", "[data-up-ignore='true']"],
    masked_elements: ["[data-up-mask]"],
    excluded_attributes: ["data-secret", "data-internal"]
  }
}
If you don’t want to override a field, simply omit it. Using undefined in JavaScript is equivalent to “not set”.

​
Options

KeyTypeDefaultDescriptionExample
enabledbooleantrue*Master switch for automatic capture. When false, no auto capture runs (manual tracking still works).true
excluded_elementsstring[] (CSS selectors)[]Do not track events originating from elements matching any selector. Useful for admin areas, iframes, or components you don’t want logged.[".no-track", "#private-area"]
masked_elementsstring[] (CSS selectors)[]Mask text/values from these elements before sending (replaced with ***). Ideal for passwords, emails, phone numbers, or custom fields.[".pii"]
excluded_attributesstring[] (attribute names)[]Strip these attributes from outgoing payloads across all elements (e.g., internal IDs, secrets).["data-secret","data-internal"]
* Defaults shown assume your project’s global defaults enable auto capture and text collection. If your SDK’s default differs, omit the field or set it explicitly.

​
Selector tips

  • Prefer scoped attributes for stability over brittle class names:
    • Exclude: [data-up-ignore="true"]
    • Mask: [data-up-mask]
  • To exclude an entire component tree, target the container: #billing-widget, .chatbot-shell
  • To mask all inputs except a whitelist, combine selectors: input:not([data-up-allow])

​
Examples

​
Disable auto capture entirely

auto_capture: {
  enabled: false
}

​
Exclude a component and mask specific fields

auto_capture: {
  excluded_elements: ["#admin-panel", ".react-datepicker"],
  masked_elements: ["input[name='email']", "textarea", "[data-up-mask]"]
}

​
Strip sensitive attributes globally

auto_capture: {
  excluded_attributes: ["data-secret", "data-token", "data-session"]
}

​
Best practices

  • Attribute contracts: Use data-up-* attributes in your app code so rules survive refactors and CSS changes.
  • Review regularly: Audit excluded_elements and masked_elements during major UI releases.

​
Type definition (optional)

type AutoCaptureConfig = {
  enabled?: boolean;
  excluded_elements?: string[];   // CSS selectors
  masked_elements?: string[];     // CSS selectors
  excluded_attributes?: string[]; // attribute names (no selector syntax)
};

​
Troubleshooting

  • “My rule doesn’t apply” – Verify the selector matches the actual rendered DOM, not framework component names.
  • “PII still appears” – Add both a mask rule for the element and an exclude attribute rule if PII is in attributes.
  • Performance – Prefer fewer, broader selectors (e.g., container IDs) over many granular ones.
⌘I