Auto Capture

Configure automatic screen and interaction capture for Cordova applications using the Userpilot Cordova plugin. The Userpilot Cordova plugin can automatically capture screens and interactions in your Cordova app and forward them to the native Userpilot SDKs, enabling analytics and engagement without manual screen and event tracking. Because Cordova renders inside a WebView, auto capture runs entirely in the DOM at runtime — there is no build-time instrumentation and no per-element wiring. The engine detects route changes and interactions and bridges them to the native SDK, so the resulting events appear alongside native auto capture on the backend.

SDK Configuration

Auto capture is off by default. Auto capture behavior is configured through the options object passed to userpilot.setup.

document.addEventListener('deviceready', function () {
  userpilot.setup(
    '<APP_TOKEN>',
    {
      logging: true,
      enableScreenAutoCapture: true,
      enableInteractionAutoCapture: true,
      enableInteractionTextCapture: true,
      enableInteractionAccessibilityLabelCapture: true,
      enableInteractionValueCapture: false,
    },
    function onSuccess() {},
    function onFail(error) {}
  );
});

Option	Type	Default	Description
`enableScreenAutoCapture`	`boolean`	`false`	Enables automatic screen tracking from route/history changes.
`enableInteractionAutoCapture`	`boolean`	`false`	Enables automatic interaction capture (taps, changes, text input, submits, dialogs).
`enableInteractionTextCapture`	`boolean`	`true`	If `false`, `target_text` is omitted from captured interaction payloads. Typed input values are never captured verbatim regardless of this flag.
`enableInteractionAccessibilityLabelCapture`	`boolean`	`true`	If `false`, accessibility labels (`aria-label` / `title`) are not captured, and `attr__desc` is omitted from hierarchy segments.
`enableInteractionValueCapture`	`boolean`	`false`	Enables value payload capture: `is_checked`, `selected_value`, and selected date/time. Slider `min`/`max` and `selected_index` for selects/lists are always included; `selected_value` only when this flag is `true`.
`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 setup. The configuration is read once from setup; use Runtime Controls to pause or resume afterwards.

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 plugin patches history.pushState / history.replaceState and listens for popstate and hashchange. The screen name is resolved with the following priority:

Hash route (for example #/settings → /settings). File-based Cordova apps keep a constant, noisy pathname, so a meaningful hash route is preferred. This covers hash-based SPA routers.
location.pathname + location.search (for history-routed apps), reported as-is — a bare / is a valid screen name and is kept.

The name always comes from the URL. There is no fallback to document.title or any other substitute. If the URL resolves to an empty string, no screen event is emitted. Consecutive identical names are de-duplicated. Debounced text_change events are flushed before a screen transition is published — on both automatic route changes and manual userpilot.screen(...) calls — so a field edited just before navigating is still attributed to the screen it was typed on.

Manual screensManual userpilot.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 plugin captures DOM interactions through delegated capture-phase listeners on document for click, change, input, and submit, plus a MutationObserver for dialog presentation. Events that originate inside a web component’s shadow DOM are resolved to the real host element. Each interaction is classified into a raw_interaction_type based on the element’s tag, type, and ARIA role:

Interaction type	Emitted for
`tap`	`button`, `a[href]`, `[role="button"]`, `[role="link"]`, `[role="menuitem"]`, `[onclick]` (climbs to the nearest interactive ancestor)
`tab_selected`	`[role="tab"]`
`list_item_selected`	A clickable element that also matches `[role="option"]` or `[role="listitem"]`
`menu_item_selected`	`[role="menuitem"]`, or any clickable element inside a `[role="menu"]` container
`checkbox_selected`	`input[type="checkbox"]` without `[role="switch"]`
`radio_button_selected`	`input[type="radio"]`
`switch_changed`	`[role="switch"]` (including `<input type="checkbox" role="switch">` and `<button role="switch">`)
`slider_changed`	`input[type="range"]`
`spinner_selected`	`select`
`date_picker_changed`	`input[type="date" \| "month" \| "week" \| "datetime-local"]`
`time_picker_changed`	`input[type="time"]`
`text_field_changed`	`input` (text-like types), `textarea`, `[contenteditable]`, `[role="textbox"]` — debounced per field; typed text is never captured
`form_submitted`	`form` submit (submit-control taps are omitted so only this event is sent)
`view_presented`	An element matching `[role="dialog"]` / `[role="alertdialog"]` added to the DOM

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. Rapid duplicate interactions on the same element are suppressed with a short de-dupe window (~500 ms).

Custom componentsTo make custom components captured, build them from standard HTML and ARIA roles. For example, a custom list row should be a clickable element (<button> / <a href>) carrying role="option" (or role="listitem") to be reported as list_item_selected; a custom toggle should carry role="switch".

Component Value Gating

By default, user-input values are stripped from event payloads — is_checked, selected dates and times, slider values, and dropdown selections do not leave the device. To include them, pass enableInteractionValueCapture: true in setup options. Position and configuration fields such as selected_index and slider min/max are always captured because they don’t reveal user input; selected_value is only included when value capture is enabled.

Privacy Controls

Global flags govern what is captured:

Text capture — enableInteractionTextCapture
Accessibility label capture — enableInteractionAccessibilityLabelCapture
Value payload capture — enableInteractionValueCapture

Disabling text capture removes target_text from the payload. Redaction replaces an existing text/title with ****; when no text exists, the property is omitted. Redaction is scoped to target_text. It does not mask accessibility_label — accessibility labels are developer-authored, so they are controlled only by enableInteractionAccessibilityLabelCapture. Auto capture never sends typed input values verbatim — only the field’s label plus has_text / text_length.

`userpilotRedactText`

Redaction replaces the captured target_text 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. A selector is resolved when the call is made, so call it once the target elements are in the DOM:

userpilot.userpilotRedactText('#profile-form');
userpilot.userpilotRedactText(document.querySelector('.credit-card'));

A declarative HTML attribute is also supported:

<form data-userpilot-redact>
  <input type="email" />
</form>

`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');
userpilot.userpilotIgnoreInteractions(myElement);

A declarative HTML attribute is also supported:

<div data-userpilot-ignore>
  <button>Internal action</button>
</div>

Attribute	Effect
`data-userpilot-ignore`	Drops auto capture for the element and its subtree.
`data-userpilot-redact`	Masks `target_text` for the element and its subtree.

Runtime Controls

Auto capture starts automatically from setup (based on options). To stop or resume collection at runtime without re-passing the config — for example a “private mode” — use:

userpilot.stopAutoCapture(onSuccess, onFail);   // detaches all listeners
userpilot.resumeAutoCapture(onSuccess, onFail); // restarts with the same config

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.

Limitations

WebView only. Auto capture observes the DOM rendered in the Cordova WebView. Anything rendered outside the WebView (fully native screens or plugins with their own UI) is not captured by this engine.
Custom widgets need semantic markup. Elements that handle interactions without using standard tags or ARIA roles (for example a clickable <div> with no role and no handler attribute) are not classified. Use the supported building blocks in the interaction table — or add the appropriate role — to be captured.
Typed input values are never captured. For text fields, target_text is the field’s label and only has_text / text_length describe the content; the value itself is never sent.
Text fields need a label to report one. target_text is resolved from aria-labelledby, an associated/wrapping <label>, or a label attribute. A placeholder is deliberately not used as a label — it is reported separately as placeholder.
One screen source at a time. Manual screen(...) is suppressed whenever enableScreenAutoCapture is configured, 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

`userpilotRedactText`

`userpilotIgnoreInteractions`

Runtime Controls

Limitations

​SDK Configuration

​Screen Capture

​Interaction Capture

​Component Value Gating

​Privacy Controls

​userpilotRedactText

​userpilotIgnoreInteractions

​Runtime Controls

​Limitations

SDK Configuration

Screen Capture

Interaction Capture

Component Value Gating

Privacy Controls

`userpilotRedactText`

`userpilotIgnoreInteractions`

Runtime Controls

Limitations