Tracking User Actions¶

Browser Monitoring automatically detects user interactions and provides deeper insight into user behavior without requiring you to manually detect every click in your application.

You can achieve the following goals:

• Understand the performance of critical interactions (for example, clicking an action button)
• Quantify feature adoption
• Determine the steps leading to a browser error

Controlling Whether Action Collection Is Enabled¶

The trackUserInteractions initialization parameter enables collection of user clicks in your application. This means sensitive and private data contained in the page may be included to identify the elements users interact with.

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    // Other initialization configuration
    trackUserInteractions: true
  })

Tracking User Interactions¶

The RUM SDK automatically tracks clicks. A click Action is created when all of the following conditions are met:

• Activity is detected after the click, i.e., the page is in the active state;
• The click does not cause a new page to load; in that case, the RUM SDK generates another RUM View event;
• An Action name can be obtained.

Action Metrics¶

The RUM SDK calculates the Action loading duration by listening for page activity after each click. The Action is considered complete when the page has no further activity.

Action Attributes¶

Action Names¶

The RUM SDK infers the Action name from the clickable element and its parent elements. If the automatically generated name is not stable enough, you can name the Action explicitly using a built-in attribute.

Add data-truewatch-action-name to the clickable element or its parent:

<button type="button" data-truewatch-action-name="Submit Order">Submit Order</button>

Use the actionNameAttribute initialization parameter to specify a custom attribute that determines the Action name for an element.

Specify the attribute name during initialization:

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    // Other initialization configuration
    trackUserInteractions: true,
    actionNameAttribute: "data-custom-name"
  })

Set the corresponding attribute on the clickable element or its parent:

<button type="button" data-custom-name="Submit Order">Submit Order</button>

When both the built-in attribute and the custom attribute configured via actionNameAttribute exist on the same element, the built-in attribute takes precedence.

Protecting Automatically Collected Action Names¶

RUM SDK 3.3.14 and later supports enablePrivacyForActionName: true, which applies the DOM privacy level to automatically inferred Action names:

window.DATAFLUX_RUM &&
  window.DATAFLUX_RUM.init({
    // Other initialization configuration
    trackUserInteractions: true,
    enablePrivacyForActionName: true,
    defaultPrivacyLevel: "mask-user-input"
  })

This switch defaults to false to preserve the existing Action naming behavior of your application. When enabled, the SDK computes the effective privacy level by combining defaultPrivacyLevel with the data-gc-privacy attribute or gc-privacy-* class names on ancestor elements.

Names explicitly specified via the built-in attribute above or actionNameAttribute are treated as business metadata intentionally provided by the application and remain usable under mask and mask-user-input; hidden subtrees still do not generate automatic Actions. This switch only affects automatically collected Action names; names passed via addAction() remain under application control.

Actions in Shadow DOM¶

The RUM SDK supports automatic collection of click Actions inside open Shadow DOM (mode: "open"):

• Generates the Action name and location information including Shadow boundaries based on the actual clicked element in the event;
• Supports elements created by an iframe's JavaScript realm and then mounted into a ShadowRoot, such as buttons rendered by the Wujie micro-frontend;
• Supports deriving names from elements associated via aria-labelledby within the same ShadowRoot;
• Supports single-level and nested open ShadowRoots.

When crossing Shadow DOM boundaries, automatic Action names only use explicit naming attributes or interactive elements with clear semantics, such as buttons, links, and ARIA elements. Aggregated text from arbitrary text nodes, table rows, or card containers is not used as a name. For custom containers without native interactive semantics, add data-guance-action-name to the clicked element or its ancestors, or configure a custom naming attribute via actionNameAttribute:

<div data-guance-action-name="Open Payment Order" role="button">
  <!-- Payment order content -->
</div>

This restriction applies only to automatic Action naming across Shadow DOM boundaries; regular DOM retains the original naming strategy.

Closed Shadow DOM (mode: "closed") does not expose internal nodes to external scripts, so collection can only rely on the Shadow Host information provided by the browser event. The name and location information of internal elements cannot be guaranteed.

Custom Actions¶

For business Actions that cannot be expressed as clicks, use the addAction API to create Custom Actions.

Verify the Integration¶

1. Click a button with a clear name.
2. In the browser Network panel, confirm that a request is reported to /v1/write/rum.
3. In the Action Explorer of the corresponding web application, check the Action name, duration, and the associated Resource and Error counts.

If no Action appears, verify in order that trackUserInteractions is true, that the current Session was selected by sampling, and that attributable page activity occurred after the click.