Auto Capture

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.

import { Userpilot } from '@userpilot/capacitor';

await Userpilot.initialize({
  token: '<APP_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.

NoteAuto 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.

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 screensManual 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:

Userpilot.UserpilotRedactText('#credit-card-form');
Userpilot.UserpilotRedactText(document.querySelector('.profile')!);

A declarative HTML attribute is also supported:

<div data-userpilot-redact>...</div>

`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:

Userpilot.UserpilotIgnoreInteractions('.admin-panel');

A declarative HTML attribute is also supported:

<div data-userpilot-ignore>...</div>

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:

// 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

Installation

Security

Data sync

Advanced

SDK Configuration

Screen Capture

Interaction Capture

Component Value Gating

Privacy Controls

Event Metadata Keys

`UserpilotRedactText`

`UserpilotIgnoreInteractions`

Runtime Controls

​SDK Configuration

​Screen Capture

​Interaction Capture

​Component Value Gating

​Privacy Controls

​Event Metadata Keys

​UserpilotRedactText

​UserpilotIgnoreInteractions

​Runtime Controls

SDK Configuration

Screen Capture

Interaction Capture

Component Value Gating

Privacy Controls

Event Metadata Keys

`UserpilotRedactText`

`UserpilotIgnoreInteractions`

Runtime Controls