Guides

Shadow DOM Insights: Area and Event Tracking

This documentation explains configuring Insights tracking for areas and elements inside a shadow root. It ensures a clear understanding of the structure and configuration steps, catering to technical and non-technical users.

Suggest Edits

1. Overview

Purpose

This document provides step-by-step instructions for:

  1. Configuring Areas for elements inside a shadow root.
  2. Enabling time activity tracking for user interaction analysis.
  3. Monitoring and collecting data on user interactions with target elements.

Applicability

This guide applies to tracking user interactions on web pages that use custom web components implemented with Shadow DOM.

2. Prerequisites

Before starting, ensure the following:

  • Familiarity with the webpage’s HTML structure.
  • Access to the Insights Configuration Tool.
  • Ability to inspect web elements using browser DevTools.

3. HTML Structure

My Application UI Structure

Overview

The My Application UI contains web components that encapsulate elements in shadow DOMs.

Key Elements

  • Main Component: Contains the app title and navigation.
  • Content Area: Hosts the custom app-container component.
  • App-Container: Dynamically generates multiple app-card components.
  • App-Card: Represents individual cards with titles and action buttons.

HTML Tree

Below is the structure of the UI:

<body>
├── <div class="main-component">
│   ├── <h1>My Application</h1>
├── <div class="content">
│   └── <app-container>
│       └── Shadow Root (of <app-container>)
│           ├── <div id="app-container">
│               ├── <app-card id="app1" title="App 1">
│               │   └── Shadow Root (of <app-card>)
│               │       └── <div id="app1-child">
│               │           └── <button>Click Me</button>
│               ├── <app-card id="app2" title="App 2">
│                   └── Shadow Root (of <app-card>)
│                       └── <div id="app2-child">
│                           └── <button>Click Me</button>

Scenario 1: Configuring Areas and Interaction Tracking in Shadow DOM

Description

This scenario explains how to define areas and trackable elements within a shadow root using CSS selectors. It covers enabling interaction tracking and time activity tracking to monitor user engagement with elements inside a custom shadow DOM structure.


Configuration Steps

Step 1: Validate Shadow DOM Integration

  1. Open the application in a browser.
  2. Inspect the shadow DOM structure using DevTools.
  3. Verify the presence of target elements like #app1-child and #app2-child within the shadow DOM.
  4. Ensure shadow DOM mode is set to open for seamless tracking.

Tip: Use DevTools to interact with the shadow DOM elements and confirm their IDs or selectors.

DevTools Shadow DOM Inspection

Step 2: Define Areas in the Insights Tool

  1. Access the Insights Configuration Tool.
  2. Create an Area for App 1:
    • Name: My Application - App 1
    • CSS Selector: #app1-child
  3. Create an Area for App 2:
    • Name: My Application - App 2
    • CSS Selector: #app2-child
  4. Save the configuration.

Example Configuration Screenshot:

Configuration of Areas

Step 3: Enable Time Activity Tracking

  1. Locate the Time Activity setting for each Area in the configuration tool.
  2. Toggle Time Activity Tracking ON.
  3. Specify the minimum interaction duration (e.g., 5 seconds).

Example Configuration Screenshot:

Time Activity Tracking Configuration

Step 4: Preview results

Debug mode allows for real-time validation of Insights configuration and visual debugging.

Instructions

  1. Log in to the Insights portal.
  2. Enable Debug Mode in the settings.
  3. Verify the configured areas using debug borders displayed on the webpage.

Example

Below is an example of the debug mode visualization:

Scenario 2: Tracking and Extracting Labels from Shadow DOM Elements

Description

This scenario details how to define areas and trackable elements using selectors that target custom shadow root tags while extracting meaningful labels from specific elements. It ensures precise interaction tracking and label extraction for enhanced insights.

Steps to Configure

Step 1: Define Areas and Trackable Elements

  1. Access the Insights Configuration Tool.
  2. Create an Area for the App Container:
    • Name: My Application - App Container
    • CSS Selector: #app-container
  3. Add Trackable Elements:
    • App Card 1:
      • CSS Selector: app-card
    • App Card 2:
      • CSS Selector: #app2
  4. Enable Click Tracking for both elements.
  5. Save the configuration.

Example Screenshot:

Trackable Elements Configuration


Step 2: Configure Text Extraction

  1. Navigate to the Text Extraction tab.
  2. Configure Label Extraction for App Card 1:
    • CSS Selector: #app1-child
    • Extraction Method: Text
    • Regex (Optional): Filter patterns like ^App \d+.
  3. Configure Label Extraction for App Card 2:
    • CSS Selector: button
    • Extraction Method: textContent
    • Regex (Optional): Extract button-specific text like Click Me.
  4. Save the configuration.

Example Screenshot:

Text Extraction Configuration


Step 4: Enable Time Activity Tracking

Below is an example of the debug mode visualization:

4. FAQs

1. What is a Shadow Root?

A Shadow Root is the encapsulated DOM subtree of a web component that ensures the isolation of styles and functionality from the main document.

2. How can elements inside a shadow root be inspected?

  1. Open DevTools (right-click > Inspect).
  2. Locate the shadow root's parent element (e.g., <app-container>).
  3. Expand the shadow root to view child elements.

3. Can dynamically added shadowRoot elements be tracked?

Yes, if their selectors remain consistent and predictable. Update configurations as necessary.

4. What happens if an incorrect CSS selector is used?

Tracking fails. To fix:

  • Verify the selector using DevTools.
  • Enable Debug Mode for real-time validation.

5. Conclusion

By following these instructions, you can effectively configure Insights tracking for shadowRoot elements, extract meaningful data, and monitor user interactions accurately.

Updated 9 days ago