> ## Documentation Index > Fetch the complete documentation index at: https://docs.userpilot.com/llms.txt > Use this file to discover all available pages before exploring further. # Auto Capture > Configure auto capture for the Userpilot Capacitor plugin Configure automatic screen and interaction capture for Ionic Capacitor applications using the Userpilot Capacitor plugin. The Userpilot Capacitor plugin can automatically capture screens and interactions in your Ionic app and forward them to the native Userpilot SDKs, enabling analytics and engagement without manual screen and event tracking. Because Ionic renders inside a single native WebView, auto capture runs entirely in the DOM at runtime — there is **no build-time instrumentation** to configure. The engine detects route changes and interactions and bridges them to the native SDK, so the resulting events are indistinguishable from native auto capture on the backend. *** ## SDK Configuration Auto capture is **off by default**. Auto capture behavior is configured through the `config` options passed to `Userpilot.initialize`. ```ts theme={null} import { Userpilot } from '@userpilot/capacitor'; await Userpilot.initialize({ token: '', config: { logging: true, enableScreenAutoCapture: true, enableInteractionAutoCapture: true, enableInteractionTextCapture: true, enableInteractionAccessibilityLabelCapture: true, enableInteractionValueCapture: false, }, }); ``` | **Option** | **Type** | **Default** | **Description** | | -------------------------------------------- | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `enableScreenAutoCapture` | `boolean` | `false` | Enables automatic screen tracking. Route/page changes are detected via the History API, `popstate`/`hashchange`, and Ionic route events. | | `enableInteractionAutoCapture` | `boolean` | `false` | Enables automatic interaction capture. Clicks and other interactions are captured as events. | | `enableInteractionTextCapture` | `boolean` | `true` | If `false`, user-visible text/labels and text-field metadata are omitted from captured interaction payloads. When enabled, typed input values are never captured verbatim. | | `enableInteractionAccessibilityLabelCapture` | `boolean` | `true` | If `false`, accessibility labels (`aria-label` / `title`) are not captured. | | `enableInteractionValueCapture` | `boolean` | `false` | Enables value payload capture: `is_checked` (checkbox/switch/toggle), selected date/time, slider/range values, and `selected_index`/`selected_value` on selects and menus. List/select selections always include `selected_index`; `selected_value` is only included when this flag is `true`. Per-element overrides have higher priority. | | `maxHierarchyDepth` | `number` | `30` | Maximum number of ancestry nodes included in the hierarchy path. | When either `enableScreenAutoCapture` or `enableInteractionAutoCapture` is enabled, the DOM auto capture engine starts automatically after `initialize`. **Note** Auto Capture automatically tracks screen views and ignores manually sent `screen` events while enabled. If you are migrating from manual screen tracking, please review the migration guide [here](https://docs.userpilot.com/data-events/mobile-screen-tracking/mobile-screen-auto-capture#important). *** ## Screen Capture When `enableScreenAutoCapture` is `true`, the engine reports a screen whenever the route changes. The screen name is `location.pathname + location.search`, sent as-is — including the root path `/` — for example `/post-details?id=10`. Consecutive identical names are de-duplicated. **Manual screens** Manual `screen()` calls are ignored whenever `enableScreenAutoCapture` is configured — manual and automatic screen tracking remain mutually exclusive, including while auto capture is stopped. To send screens manually, leave `enableScreenAutoCapture: false`. *** ## Interaction Capture When `enableInteractionAutoCapture` is `true`, the engine captures the following DOM interactions through a small set of delegated, capture-phase listeners on `document`: | **Interaction type** | **Emitted for** | | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tap` | Buttons, links, `ion-button`, `ion-back-button`, `ion-menu-button` (hamburger), `ion-fab-button`, list items, cards, chips, and elements with `[role="button"]`. | | `tab_selected` | `ion-tab-button`, `[role="tab"]`. | | `text_field_changed` | `input`, `textarea`, `ion-input`, `ion-textarea`, `ion-searchbar`, `contenteditable` (debounced; typed text is never captured — only `has_text` / `text_length`). | | `checkbox_selected`, `radio_button_selected`, `switch_changed` | Checkbox, radio, and switch/toggle changes. | | `slider_changed` | Range/slider changes. | | `selection_change` | Select/dropdown and segment selection. | | `date_picker_changed`, `time_picker_changed` | Date and time input changes. | | `view_presented` | Modal, alert, popover, action-sheet, and dialog presentation. | Each interaction maps to a high-level analytics category (`tap`, `text_change`, `selection_change`, `value_change`, `view_presented`) — that is the event name that reaches your analytics backend. ### Component Value Gating By default, user-input values are stripped from event payloads — `is_checked`, selected dates and times, slider/range values, and dropdown selections do not leave the device. To include them, pass `enableInteractionValueCapture: true` in `config`. Position fields such as `selected_index` are always captured because they don't reveal user input; `selected_value` is only included when value capture is enabled. Per-element overrides have higher priority. *** ## Privacy Controls Global flags govern what is captured: * **Text capture** — `enableInteractionTextCapture` * **Accessibility label capture** — `enableInteractionAccessibilityLabelCapture` * **Value payload capture** — `enableInteractionValueCapture` Disabling text capture removes text-derived properties from the payload. Redaction replaces an existing text/title with `****`; when no text exists, the property is omitted. Redaction is scoped to `target_text` (and the `dialog_title` of a presented surface). It does **not** mask `accessibility_label` or the hierarchy's `attr__desc` — accessibility labels are developer-authored, so they are controlled only by `enableInteractionAccessibilityLabelCapture`. ### Event Metadata Keys Common fields on interaction events: | **Key** | **Meaning** | | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `target_view_class` | Simple component name, e.g. `IonButton` (Ionic components) or the tag name (`button`) for plain HTML elements. | | `target_class` | Package-qualified name, e.g. `@ionic/react.IonButton`. The framework package (`@ionic/react` / `@ionic/vue` / `@ionic/angular`) is detected at runtime; plain HTML elements report their tag name. | | `target_text` | Primary visible label / title for the control (redacted when required). | | `accessibility_label` | Flattened accessibility metadata (only when accessibility-label capture is enabled). | | `target_resource_id` | The target element `id` (Ionic auto-generated ids like `ion-r-0` are filtered out). | | `view_tag` | Element tag metadata. | | `class_name` | Developer-authored element classes (not part of the hierarchy). | | `hierarchy` | Semicolon-separated leaf-to-root path, with the screen name appended. | | `raw_interaction_type` | Low-level interaction name, e.g. `tap`, `checkbox_selected`. | | `is_checked`, `selected_value`, `selected_index`, `values`, `has_text`, `text_length`, `selected_date`, `selected_time` | Interaction-specific source properties. Value properties are gated by `enableInteractionValueCapture`. | ### `UserpilotRedactText` Redaction replaces the captured `target_text` (and the `dialog_title` of a presented surface) with `****`. The interaction event still fires — the element is still identified by type, position, and structure — only the human-readable text is masked. Accessibility labels are not masked by redaction; they are controlled only by `enableInteractionAccessibilityLabelCapture`. The programmatic API accepts either an `Element` or a CSS selector and applies to the element and its subtree: ```ts theme={null} Userpilot.UserpilotRedactText('#credit-card-form'); Userpilot.UserpilotRedactText(document.querySelector('.profile')!); ``` A declarative HTML attribute is also supported: ```html theme={null}
...
``` ### `UserpilotIgnoreInteractions` Ignoring skips **interaction** events whose hit-tested element lies inside the subtree (taps, value changes, text-field updates, etc.). Route-driven **screen** events are **not** suppressed — they come from route detection, not from element hit testing. The host app's own handlers still run — only auto capture ignores those interactions. The programmatic API accepts either an `Element` or a CSS selector and applies to the element and its subtree: ```ts theme={null} Userpilot.UserpilotIgnoreInteractions('.admin-panel'); ``` A declarative HTML attribute is also supported: ```html theme={null}
...
``` *** ## Runtime Controls Auto capture starts automatically from `initialize` (based on config). To stop or resume collection at runtime without re-passing the config — for example a "private mode" — use: ```ts theme={null} // Pause screen + interaction capture. await Userpilot.stopAutoCapture(); // Resume with the same config supplied to initialize. await Userpilot.resumeAutoCapture(); ``` While stopped, no screen or interaction events are recorded regardless of other configuration. Pausing auto capture does not enable manual `screen()` calls: when `enableScreenAutoCapture` is configured, manual and automatic screen tracking remain mutually exclusive, including while auto capture is stopped. [**For any questions or concerns please reach out to support@userpilot.com**](mailto:support@userpilot.com)