Tealeaf

UI Capture reference

The Tealeaf UI Capture library configuration is a JSON object. You modify the config object in the defaultconfiguration.js file to specify the configuration settings according to your application and analytics requirements. The library configuration includes different sections.

  • Core configuration object: Contains configuration information about Document Object Model events to which the library listens. See Core configuration.
  • Services configuration object: Contains configuration information about the individual services that extend the core and provide the necessary functionality that is required by the library. See Services configuration.
  • Modules configuration object: Contains configuration information about the modules that are enabled in the library. See Modules configuration object.

Core configuration

The core configuration object contains basic information about the DOM events to which the Acoustic Tealeaf UI Capture library listens.

In Core, you define properties to assure capture of UI events.

Note: Do not modify these settings unless directed to do so by Tealeaf. For more information, contact Acoustic Professional Services.

For details about the Core configuration object, check out these sections:

TLT.init({
   /**
    * Base configuration for the core.
    * It specifies which modules should listen to which events, which frames
    * to ignore, which elements to block, and which links are excluded from
    * triggering an unload.
    * @type {Object}
    */
   core: {
       /**
        * Use this to add a custom note which will be available for eventing
        * in the session data.
        */
      buildNote: "r3 MP 12/7/2020",
     
       /**
        * The ieExcludedLinks entry specifies a set of links that should
        * not trigger the beforeunload event, which destroys the UI
        * Capture library. This addresses a known issue with Internet
        * Explorer. Specified as a comma separated list of CSS selectors.
        */
       ieExcludedLinks: ["a.ignore"],

       /**
         * The blockedElements entry specifies a set of elements for
         * which no user interaction is to be reported. No user interaction
         * will be reported for the specified element and any child elements.
         * Elements can be specified as a comma separated list of CSS selectors.
         *
         * Warning: The blockedElements entry is evaluated for each event.
         * Specifying inefficient CSS selectors can cause performance issues.
         *
         * Note: This is an advanced feature which has implications for
         * Tealeaf functionality and must only be used in unique situations
         * that require such a restriction.
         *
         */
       blockedElements: [],

       /**
        * This is the module configuration section contains options 
        * relevant to the core.
        * It contains the events to which the modules attempt to listen.
        * NOTE: Please do not use this section for module-specific
        * configuration, which you must access inside of your modules.
        * @type {Object}
        */
       modules: {
           performance: {
               enabled: true,
               events: [
                   {
                       name: "load",
                       target: window
                   },
                   {
                       name: "unload",
                       target: window
                   }
               ]
           },
           replay: {
               enabled: true,
               events: [
                   /* Lifecycle events - not optional */
                   {
                       name: "load",
                       target: window
                   },
                   {
                       name: "unload",
                       target: window
                   },
                   /* User interaction events - not optional */
                   {
                       name: "change",
                       target: changeTarget,
                       recurseFrames: true
                   },
                   {
                       name: "click",
                       recurseFrames: true
                   },

                   /* Dwell time and previous state */
                   {
                       name: "focus",
                       target: "input, select, textarea, [contenteditable]",
                       recurseFrames: true
                   },
                   {
                       name: "blur",
                       target: "input, select, textarea, [contenteditable]",
                       recurseFrames: true
                   },

                   /* Hash change - optional */
                   {
                     name: "hashchange",
                     target: window
                   },

                   /* ClientState events - not optional */
                   {
                       name: "resize",
                       target: window
                   },
                   {
                       name: "scroll",
                       target: window
                   },

                   /* Mobile DOM events - optional */
                   {
                       name: "orientationchange",
                       target: window
                   },
                   {
                       name: "touchend"
                   },
                   { 
                       name: "visibilitychange"
                   }
               ]
           }
       }
   },
},
/* Following settings are related to the TLT.getSessionData() Public API */

/**
* Set the sessionDataEnabled flag to true only if it is OK to expose Tealeaf
* session data to 3rd party scripts.
*/
sessionDataEnabled: false,

/**
* The sessionData object specifies the query parameter name OR cookie name to
* get the session id value from. An actual deployment would only specify one
* of the methods to obtain the session id. If both are specified, the
* sessionQueryName takes precedence over sessionCookieName. If neither is
* specified, an internal default of "TLTSID" will be looked up in the cookies.
*/
sessionData: {
    /**
    * Specify sessionQueryName only if the session id is derived from a
    * query parameter.
    */
    sessionQueryName: "sessionID",

    /* Optionally, specify the query string delimiter. Default is */
    sessionQueryDelim: ";",

    /* The cookie being used for sessionization in Tealeaf. */
    sessionCookieName: "jsessionid",

    /**
    * Optionally, specify if the value needs to be hashed to derive the
    * session ID.
    */
    sessionValueNeedsHashing: true
}
   /**
    * The framesBlacklist array specifies the CSS selectors which correspond to the
    * frame/iframe elements that should not be accessed.
    */
framesBlacklist: [
    ".tlBlock"
]
},

   /* End of core configuration */

   // Services configuration

   ...

   // Module specific configuration

   ...

});

Internet Explorer links

(ieExcludeLinks)

Clicking some link URLs that use "intent", "mailto", "sms", or "tel" protocols can cause premature unload events. The UIC automatically ignores these unloads.

In Internet Explorer, clicking an href=javascript link can trigger the beforeunload event. If this link does not trigger a navigation change, then the UI Capture library is destroyed prematurely, and subsequent UI events on the page are not captured.

To address this issue, you can specify a series of CSS Selectors that resolve to HTML elements, which, when clicked, do not trigger the beforeunload event.

In the ieExcludedLinks field, you can specify these HTML elements as an array of CSS selectors. In the example below, an <a> anchor with a specified class (ignore) and an anchor with a specific class (foo) containing a span element are specified. If the user clicks either of these element types, then the resulting beforeunload event in Internet Explorer is ignored.

ieExcludedLinks: ["a[href^=javascript]", "a.ignore"],

Blocking UIC from initializing on specific User Agents and Bots

(blockedElements)

UIC can be prevented from capturing data on specific User Agents or Bots by adding a blockedUserAgents list to the core configuration. The list entries can be a string or a regular expression as shown in the example below. If the string or regex pattern matches with the User Agent string then the UIC will self-terminate and not capture any data from that browser.

blockedUserAgents: [{
        regex: "(Google|Bing|Face|DuckDuck|Yandex|Exa)bot",
        flags: "i"
    },
    {
        regex: "spider",
        flags: "i"
    },
    {
        regex: "archiver",
        flags: "i"
    },
    "PhantomJS"
],

This feature can be used to prevent crawl data from Bots, web crawlers, automated tests or unwanted browsers from interfering with your analytics reports. Do not use this feature if you intend to track Bot visits within Tealeaf.

NOTE: This feature prevents the UIC from capturing data. This feature cannot and will not prevent the Bot agent from crawling your site. This feature is NOT intended for and does not offer any security against malicious User Agents.

Custom events to trigger logging of load events

UIC triggers "load" events on initialization. You can use custom events to trigger logging of load events by adding "screenviewLoadEvent" in the core configuration.

In some cases, UIC triggers the load event before the page is fully rendered, which produces an incomplete initial DOM capture. To solve this problem, configure a custom event that triggers the load event at an appropriate time.

core: {
    ....
    screenviewLoadEvent: {         
        name: "click",   //This could be any custom event, or DOM event.      
        target: window         
    }
    ....
}

Configure client events by module

(modules)

The modules subsection of the core configuration specifies the events to which each module listens. Do not change the default settings.
See the following sections for a description of the modules and how to format events:

Format

An example configuration for an individual user interface event is:

                   {
                       name: "load",
                       target: window
                   },

Where:

  • name identifies the W3C name of the user interface event.
  • target identifies the client object that is the target of the event.
    • The target can be a Document Object Model element such as document or window.
    • The target can also be a string that contains comma-separated CSS selectors to be used as the targets.
    • If target is not specified, it defaults to the document element.
      Note: To disable an event, comment out or remove the entry. Some events are not optional and must remain enabled for correct operation of the library.

For some user interface events, configuration might be in this format:

                   {
                       name: "click",
                       recurseFrames: true
                   },

If recurseFrames is set to true, then evaluation is applied to all frames and subframes on the page that originate from the same domain as the page.

Performance

(performance)
The performance module parses the W3C Navigation Timing performance object and includes this information as the performance message in the JSON data stream that is sent back to the Tealeaf capture server.

For correct operation, do not modify this configuration. If the performance module is not required, remove this section from the core configuration.

Replay

(replay)
The replay module provides the underlying data in form of JSON messages that enable features such as:

  • Rich Internet Application (RIA) Replay: Browser Based Replay and RealiTea Viewer.
  • Tealeaf cx Overstat usability functionality; heatmaps, form analytics, and attention maps.
  • Step-based eventing.
    Events are tracked for replay purposes on the client. Most of the events are required for replay. This table lists and describes the events tracked for replay purposes:
Property
Description

load

Page load event. This event is required.

unload

Page unload event. This event is required.

change

Control change event. This event is required. By default, it is configured to track all HTML elements that support the change event.

Optionally, you can set recurseFrames to true to scan all frames and subframes of the page for these events.

click

Click events on the page. This event is required.

Optionally, you can set recurseFrames to true to scan all frames and subframes of the page for these events.

focus

Focus events on the control. This event is required.

Optionally, you can set recurseFrames to true to scan all frames and subframes of the page for these events

blur

Blur events on the control. This event is required.

Optionally, you can set recurseFrames to true to scan all frames and subframes of the page for these events.

hashchange

When enabled, this option generates screen view events when a hash change was identified in the URL of the page.

  • A screenview is defined as a change in state for the overall page. For example, if a page has multiple tabs, each tab can be defined as a separate screen view for the page.
  • When this option is enabled, a screen view event is inserted in the session data, and UI events that are captured by UI Capture can be organized beneath the screen view on which they occurred.
  • If your web application does not use screen views, disable this option.

resize

Resize events on the client.

scroll

Scroll events on the client.

Depending on your application, tracking windows that scroll can generate a significant number of events.

Replay of scroll events is supported for mobile sessions in Browser Based Replay only.

Note: For Attention Maps to work on scrollable pages, UI capture must send scroll events. If you configure UI capture not to send scroll events for such pages, the Attention map will not render correctly.

orientationchange

Orientation change events for mobile devices.

These events are replayed only if you licensed Tealeaf CX Mobile. For more information, contact your Tealeaf representative.

touchend

Touch end events for mobile devices.

These events are replayed only if you licensed Tealeaf CX Mobile. For more information, contact your Tealeaf representative.

Pinch and zoom gestures can be captured on the iOS platform only. They cannot be captured on the Android platform.

pointerup

Used in conjunction with pointerdown to infer "click" actions on disabled target elements.

pointerdown

Used in conjunction with pointerup to infer "click" actions on disabled target elements.

visibilitychange

Visibility change event. This event tracks when the browser tab is minimized/hidden or visible.

Support for all of these replay events is provided in Browser-Based Replay only.
A subset of replay events might work in the RealiTea Viewer.

Services configuration

The Services configuration object contains options that are used by the individual services that are part of the Tealeaf UI Capture library.

Note: When integrating the library with a new application, you typically modify only few of these configuration items.

See the following sections for a description of the services:

services: {
    queue: {
        // WARNING: Enabling asynchronous request on unload may result in incomplete or missing data
        asyncReqOnUnload: false,
        queues: [{
                qid: "DEFAULT",
                endpoint: "/TealeafTarget.php",
                maxEvents: 50,
                timerInterval: 300000,
                maxSize: 300000
            }
        ]
    },
    message: {
        privacy: [{
                targets: [
                    // CSS Selector: All password input fields
                    "input[type=password]"
                ],
                "maskType": 3
            }
        ]
    },
    serializer: {
        json: {
            defaultToBuiltin: true,
            parsers: ["JSON.parse"],
            stringifiers: ["JSON.stringify"]
        }
    },
    encoder: {
        gzip: {
            /**
             * The encode function should return encoded data in an object like this:
             * {
             *     buffer: "encoded data"
             * }
             */
            encode: "window.pako.gzip",
            defaultEncoding: "gzip"
        }
    },
    domCapture: {
        diffEnabled: true
    },
    browser: {
        normalizeTargetToParentLink: true
    }
}

Queue service configuration

Through the Queue service configuration, you can configure properties which determine the extent of the buffering and the endpoint destination to which the messages will be sent via HTTP POST.

Property
Description

asyncReqOnUnload

Enables asynchronous XHR on page unload.

Warning: Enabling this option may result in incomplete or missing data. This is because most browsers will cancel outstanding asynchronous XHR or fetch requests during page unload.

qid

Identifies the name of available event queues.

Note: By default, one queue is defined as DEFAULT. Do not remove this queue or change its name.

endpoint

Identifies the target URL to which the messages are sent. For on-prem, this value corresponds to a target page path. Sample target pages for JSP and PHP environments are included in the UI Capture release package. For SaaS, this value corresponds to the collector URL.

maxEvents

The maximum number of messages in a queue. If this number is exceeded, the queue is automatically flushed, and all queued messages are sent to the configured endpoint.

timerInterval

The user inactivity interval in milliseconds after which the queue is automatically flushed, and all queued messages are sent to the configured endpoint. The default value is 5 minutes. If this option is set to 0, the timer-based flush is disabled.

Note: Keep this setting at the default value, unless a more immediate flushing of data is required, such as when Tealeaf users are shadow-browsing a visitor's session.

maxSize

The maximum serialized length of the queue. If this is exceeded, the queue is automatically flushed, and all queued messages are sent to the configured endpoint. If this option is set to 0, the serialized length based flush is disabled.

The recommended value for this setting is between 50000 to 300000.

useBeacon

A boolean flag indicating if the W3C Beacon API should be used to send the request instead of XHR on page unload.

Note: This setting should be set to false for Tealeaf Customer Experience on-prem using PCA versions below 3740.

useFetch

A boolean flag indicating if the Fetch API should be used to send the request instead of asynchronous XHR. By default, the UIC uses fetch when available. Synchronous requests will continue to use XHR or Beacon as appropriate.

Message service configuration

You use the Message service configuration to define options such as privacy rules applied to the JSON messages submitted to the Tealeaf server for capture. Applications using Shadow DOM should enable the Shadow DOM cache feature in order to optimize the Shadow DOM snapshot data sent to the server.

message: {
    /**
     * Applications using Shadow DOM should enable this setting.
     */
    shadowDOMCacheEnabled: true,

    /**
     * Define privacy rules to modify/mask reported values in the
     * messages sent to the server.
     * @type {Array}
     * @optional
     */
    privacy: [
        /**
         * An example privacy rule.
         */
        {
            /**
             * Specify the targets to which this rule should apply.
             * @type {Array}
             */
            targets: [
                {
                    id: "htmlid",
                    idType: -1
                },
                {
                    id: "myid=custom",
                    idType: -3
                }
            ],
            /**
             * The maskType defines how the value should get
             * transformed.
             * maskType 1: The value gets set to an empty string
             * maskType 2: The value gets replaced with the fixed
             *             string "XXXXX".
             * maskType 3: The value gets replaced by a mask where:
             *     each lowercase character gets replaced by "x",
             *     each uppercase character by "X",
             *     each number by "9"
             *     each symbol by "@"
             *     e.g. "HelloWorld123" becomes "XxxxxXxxxx999"
             * maskType 4: The value gets replaced by the return
             *             value from the custom function that is
             *             specified as maskFunction.
             * @type {Number}
             */
            maskType: 3
        }, 
        /**
         * another example of a privacy rule.
         */
        {
            targets: [
                {
                    id: "[[\"html\",0],[\"body\",0],[\"input\",0]]",
                    idType: -2
                }
            ],
            maskType: 4,
            /**
             * A custom mask function that replaces the value
             * with its return value ("masked", in this example)
             * @param  {String} value The value to replace.
             * @return {String} Can return any string.
             */
            maskFunction: function (value) {
                return "masked";
            }
        }
    ]
}

Privacy configuration for UI Capture

Tealeaf UI Capture enables the blocking and masking of sensitive information within the client browser before the data is forwarded to Tealeaf for capture, while it allows the data to be forwarded to your web servers for normal processing. Sensitive data that was cleansed through UI Capture never reaches Tealeaf, which ensures that your customer's interactions are secure in UI Capture.

  • UI Capture enables the blocking of user input data by element ID, name, or xpath.
  • Masks can be expressed as explicit strings, replacements for character types, or custom functions.
  • Use the blockedElements configuration setting in the Core configuration file to define a set of elements for which no user interaction is to be reported. For more information, see Core configuration.
    Note: If you have questions about implementing data privacy in UI Capture, see Privacy masking and blocking sensitive data. Additionally, you can contact Tealeaf Professional Services for a consultation.

To specify a privacy rule, you must define:

  • The type of identifier.
  • The targets to which the rule applies.
  • The type of masking to apply to the targets.

Specifying a privacy rule

In the configuration, a single privacy rule is specified within the privacy object by using the following configuration template.

               {
                   targets: [
                       {
                           id: "htmlid",
                           idType: -1
                       }
                   ],
                   maskType: 3
               }

Specifying targets

To specify a target, you must specify the following properties.

Note: You can specify multiple id or idType targets for each masking rule.

Property
Description

id

The identifier for the target element. This value is specified according to the idType value.

In the configuration file, you can use a regular expression to specify matching identifiers. For example, the following target configuration matches all HTML identifiers that end with _pii:
<!-- HTML generated using hilite.me -->

message: {
privacy: [{
targets: [{
id: {
regex: ".+_pii$"
},
idType: -1
}, ],
"maskType": 3
}]
}

idType

The type of identifier. The following types are supported:

Note: Values for idType are recorded as negative numbers.

-1 - HTML ID
-2 - xpath identifier
-3 - HTML name or other element attribute identifier

CSS selector

In the configuration file, you can also specify CSS selector values to match CSS elements for privacy masking. In the example below, the designated privacy rule is applied to all password input fields:

message: {
    privacy: [
        {
            targets: [
                "input[type=password]"
            ],
            "maskType": 3
        }
    ]
}

Specifying mask type

Tealeaf UI Capture supports the following mask types (maskType values):

Value
Description
Example
Masked example

1

Value is blocked and replaced by an empty string.

"HelloWorld123"

""

2

Value is masked with a fixed string of x's

"HelloWorld123"

XXXXX

3

Value is masked according to the following parameters:

A lowercase letter is replaced by x.
An uppercase letter is replaced by X.
A numeral is replaced by 9.
A non-alphanumeric value is replaced by @.

"HelloWorld123"

"XxxxxXxxxx999"

4

Custom function

Note: A masking function must be defined as maskFunction.

"HelloWorld123"

Defined on the defined function

Serializer service configuration

Through the Serializer service configuration, you can specify which JSON parser and serializer functionality to use.

The library uses JSON as its message format. All modern browsers have built-in support for serializing and parsing JSON. However, legacy browsers (for example, Internet Explorer 6 and 7) do not have this built-in support. For such browsers, a third-party library that provides JSON serialization and parsing capabilities is required. By default, the UI Capture library relies on the built-in JSON capabilities of the browser where available, and defaults to a simplified internal implementation in other cases. If your application or IT environment mandates use of specific JSON parser or serializer, you can specify it using this configuration.

Warning: JSON serialization and parsing are fundamental to the library's ability to function and produce correct output. Thorough cross-browser testing is necessary if any changes are made to this configuration.

serializer: {
                json: {
                    defaultToBuiltin: true,
                    parsers: [ "JSON.parse" ],
                    stringifiers: [ "JSON.stringify" ]
                }
            },
            encoder: {
                gzip: {
                    /**
                     * The encode function should return encoded data in an object like this:
                     * {
                     *     buffer: "encoded data"
                     * }
                     */
                    encode: "window.pako.gzip",
                    defaultEncoding: "gzip"
                }
            },
            domCapture: {
                diffsEnabled: true
            },
            browser: {
                normalizeTargetToParentLink: true
            }
        },

DOM Capture service configuration

The DOM Capture service configuration provides options for enabling or disabling DOM Diff, capturing same domain frame/iframes and specifying thresholds related to mutations and snapshot size.

            domCapture: {
                diffEnabled: true
            }
Property
Description

diffEnabled

Set this to true (default) to enable DOM Diff. Set to false to disable DOM Diff.

Optional configuration properties can be specified as follows:

            domCapture: {
                diffEnabled: true,
                options: {
                    maxMutations: 500,
                    captureFrames: true
                }
            }
Property
Description

maxMutations

Specifies the mutation threshold after which a full DOM snapshot is taken instead of a diff. The default value is 100. Increase this value to improve the efficiency of DOM Diff. Reduce this value if calculating the DOM Diff results in performance issues due to processing a large number of mutations.

maxLength

Specifies a safety threshold for DOM snapshot size. Snapshot sizes exceeding this value will not be sent. The default value is 1,000,000. Increasing this threshold can have an impact on application performance.

captureFrames

Set this to true to enable DOM capture of same domain frames and iframes. The default value is false.

captureShadowDOM

Set this to true to enable DOM capture of Shadow DOM content. The default value is false.

removeScripts

Set this to false to disable removing script content from the DOM snapshots. The default value is true.

removeComments

Set this to false to disable removing comments from the DOM snapshots. The default value is true.

captureStyle

Set this to false to remove inline style so as to reduce the size of the DOM capture message. When set to true, the default value, the SDK captures all interior styles.

discardBase64

Set this to an 0 to remove the base64 image src string and reduce the size of DOM capture message. For every removed base64 image, UIC cleans the src attribute and adds an extra attribute to the element, which makes the node look like the following:

<
img src = ""
removedByUIC = "true"... >

By default, there is no "discardBase64" setting in configuration and the SDK captures all base64 images. If you set "discardBase64", its value serves as a threshold. 0 discards everything. You can set discardBase64 to other values, such as 20,000. In this case, base64 image capturing is discarded if the length of image src string exceeds 20,000.

Browser service configuration

Through the Browser service configuration, you can specify browser objects and elements that have dynamic or duplicate HTML IDs.

browser: {
           /**
            * useCapture is a boolean flag to indicate if the event capture phase
            * should be used on browsers that support event capture.  This flag
            * is enabled by default.
            *
            * If disabled or the browser does not support event capture then
            * event bubbling will be used. Event bubbling could cause some events
            * to be missed if the application is preventing them from bubbling.
            *
            * For additional details on event capture and bubbling refer to the
            * W3C DOM specification at:
            *  http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-flow
            * @type {Boolean}
            */
            useCapture: true,

           /**
            * To specify elements whose HTML ids cannot be used as identifiers
            * or in xPath generation. Could be a string object with one or two
            * properties, "regex" (mandatory) and "flags". These are specified
            * as strings. The regex that is evaluated against the node id.
            * @type {Array}
            * @optional
            */
           blacklist: [ 
               "duplicateid",
               {
                   regex: "/password|pass|pin|tan/",
                   flags: "gi"
               }
           ],
           /**
            * If the application uses custom attributes as an ID replacement,
            * you may specify the attribute name here.
            * @type {Array}
            * @optional
            */
           customid: [ "name", "custom-attribute" ],

           normalizeTargetToParentLink: true
       },

blacklist

You can optionally specify a set of document elements whose HTML IDs are not guaranteed to be static or unique. These HTML IDs of these blacklisted objects are not used to identify the elements and alternate mechanisms, such as a customid (if configured) or an xpath.

customid

If your web application uses a custom attribute that can be used to uniquely identify the elements, you can specify the attribute name here.

normalizeTargetToParentLink

By default the UIC uses the link element that encapsulates the target of the event. If set to false, the UIC uses the actual target element instead. For example, consider the following HTML source:

<a id="logo_link" href="/"><img id="logo_image" src="logo.png" /></a>


By default, clicking on the image will cause the UIC to log the link element "logo_link" as the target of the click. When this property is set to false, clicking on the image causes the UIC to log the image element “logo_image” as the target of the click.

Modules configuration object

The Modules configuration object contains options that are used by individual modules that are enabled in the Tealeaf UI Capture library.

For details about the Modules configuration object, check out these sections:

Overstat module configuration

The following example shows the Overstat module options that are in the defaultconfiguration.js file. The Overstat module options can also be configured through the Configuration wizard.

overstat: {
                hoverThreshold: 1000
          },

Performance module configuration

The Performance module options can also be configured through the Configuration wizard. The Performance module options correspond to the available options of the W3C navigation timing specification. For more information about the W3C navigation timing specification, see http://www.w3.org/TR/navigation-timing/#sec-navigation-timing-interface.

Property
Description

calculateRenderTime

If enabled, the render time is calculated on browsers that do not support the W3C navigation timing interface. For the calculated render time to be accurate, the library should be statically included at the top of the page in the HEAD section.

renderTimeThreshold

The threshold in milliseconds that render time is capped. This prevents outlier values from impacting the render time reports.

delay

Optional delay in milliseconds that specifies how long to wait after page load before logging the type 7 performance message.

performanceAlert

Enables performance alert (type 17) messages. Disabled by default. To enable, add the performanceAlert setting to the Performance module.

The following example shows the Performance module options that are in the defaultconfiguration.js file.

modules: {
        performance: {
            calculateRenderTime: true,
            renderTimeThreshold: 600000,
        },

Performance Alert

Performance Alert messages are disabled by default. To enable Performance Alert messages, add the performanceAlert setting to the Performance module.

When enabled, the UIC will also log any mixed content violations for the page. The total number of violations is logged on page unload in a type 20 Mixed Content violations message.

Note:

Performance Alerts are supported on the following browsers: Chrome 52+, Firefox 57+, Opera 39+, Safari 11+

Property name
Data type
Description

enabled

Boolean

Required. False by default.

threshold

Number

Optional. Capture data if the resources loading time exceeds threshold. Threshold is measured in milliseconds.
The recommended value is 1000 (1 second).

Note: Setting a small value for threshold or a large value for maxAlert will result in a large number of performance messages.

maxAlert

Integer

Optional. Set the maximum number of alerts to be logged.
The recommended value is 40.

Note: Setting a small value for threshold or a large value for maxAlert will result in a large number of performance messages.

resourceTypes

String Array

Optional. Specify the resource type to monitor. For example, ["script", "img"]. Monitors all resources, by default.

blacklist

String Array or Regex Object Array

Optional. Used to blacklist specific resources by specifying the resource name (url). For example, ["sdk"].

modules: {
	performance: {
		performanceAlert: {
		    /* required
		     * boolean
		     */
		    enabled: true,

   	            /* optional
		     * measured in ms
		     * capture the data if resources loading time exceeds threshold
		     */
		    threshold:3000,
                    
                     /* optional
		     * an integer number
		     * set the maximum number of alerts to be logged
		     */
		    maxAlerts: 400,


                    /* optional
		     * array of strings
		     * specify the resource type to monitor, monitor all resources by default
		     * possible values are "script", "link", "img", "xmlhttprequest", "iframe", etc
		     */
		    resourceTypes: ["script", "img"],

		    /* optional
		     * array of a string or regex object
		     * used to blacklist certain resources by matching the resource name (url)
		     */
		    blacklist: [{regex: "collector"}, {regex: "tealeaf"}, {regex: "tlt-worker"}, {regex: "bam\\.nr"}]
  		}
		...
	}
	...
}

Replay module configuration

The following example shows the Replay module options that are in the defaultconfiguration.js file. The Replay module options can also be configured through the Configuration wizard.

replay: {
                
                // DOM Capture configuration
                domCapture: {
                    /**
                     * NOTE: Enabling DOM Capture has significant implications
                     * on data transmission and infrastructure.
                     * Hence this feature should be enabled judiciously. If
                     * enabled, it requires further configuration
                     * to only perform the DOM Capture based on specific events and 
                     * elements. Please refer to the
                     * documentation for more details.
                     */
                    enabled: false,
                    /**
                     * The rules for triggering DOM Snapshots are similar to the
                     * Privacy configuration.
                     * It accepts a mandatory "event" followed by one or more 
                     * optional targets
                     * as well as an optional delay after which to take the 
                     * DOM snapshot.
                     * 
                     * The default configuration below will capture a full DOM 
                     * snapshot for each and every click, change
                     * action as well as for all screenview load and unloads. 
                     * Please refer to the documentation for
                     * details on fine tuning this configuration to specific 
                     * elements and screenviews.
                     */
                    triggers: [
                        {
                            event: "click"
                        },
                        {
                            event: "change"
                        },
                        {
                            { event: "load", delayUntil: { selector: ".page-picker-spinner", exists: false, timeout:10000 }, fullDOMCapture:true}
                        }
                    ],
                }
            }

Disable DOM capture for specific screenviews

You can use the Screenview blacklist option to disable DOM capture for specific screenviews. Define rules in the blacklist that identify web page screenviews that you want blacklisted. A rule can be a string (exact match) or an object of regular expression (match by regex). The rules are used to compare with the web page's screenview name, which is "path + hash". For example, the screenview name of "www.abc.com/xx/yy#zz" will be "/xx/yy#zz".

If a match is found, UIC does not take a dom capture of the screenview. To disable this feature, simply remove the definition of "screenviewBlacklist".

replay: {
    domCapture: {
        enabled: true,

        screenviewBlacklist:[
            "/some/url",
            {
                regex: "somerRegEx",  //JS Regex pattern
                flags: "someFlag"         //Optional JS Regex flags
            }, ...
        ],

        triggers: [{
            event: "load"
          }, ...
        ]
    }
}

Screenview loads are associated with the URL fragment for page loads with #fragment appended to the URL

By default, the initial screenview name is derived from the URL hash fragment (location.hash). If you set the forceRootScreenview option to true, the UIC will always log the initial screenview as "root" irrespective of the location.hash value.

TLCookie module configuration

The TLCookie module is used to record the application cookies in the Tealeaf session. For information, see type 14 JSON message schema. Additionally, the TLCookie module manages the application key and session identifier that are used to uniquely identify a visitor session. The TLCookie module is required for Acoustic Tealeaf on Cloud environments.

By default, the session identifier is a random 32-character alphanumeric string stored in the TLTSID cookie. By setting the sessionIDUsesStorage property to true, the session identifier is stored using local storage, instead of cookies. If local storage is not available, the UIC defaults to using cookies. To prevent the UIC from storing the session identifier in cookies, set the sessionIDUsesCookie property to false. Available options and the corresponding UIC behavior are summarized in the table below.

Impact of Incognito and Private browsing modes

Browser implementation of Storage and Cookies in Incognito or Private browsing modes varies across vendors. Browsers continue to evolve their respective implementations based on market and legal requirements. The UIC will always respect the browser's implementation for Cookies and Storage in Incognito or Private browsing modes. Unfortunately, the use of these browsing modes can cause browser tabs to be split across multiple Tealeaf sessions even though each tab is simultaneously browsing the same site. This impact is more likely to occur if the sessionIDUsesStorage property is enabled. For additional information, refer to the browser documentation on Storage and Cookie behavior in Incognito or Private browsing mode.

sessionIDUsesStorage
sessionIDUsesCookie
UIC behavior

Not specified (default)

Not specified (default)

TLTSID in cookie only.

Not specified (default)

true

TLTSID in cookie only.

false

true

TLTSID in cookie only.

false

Not specified (default)

TLTSID in cookie only.

true

Not specified (default)

TLTSID in storage with fallback to cookie.

true

true

TLTSID in storage with fallback to cookie.

true

false

TLTSID in storage only.

Not specified (default)

false

NO SESSION ID*

false

false

NO SESSION ID*

For applications that are integrated with multiple Acoustic offerings, the session identifier can be stored in the WCXSID cookie. In this case, the UIC allows the WCXSID session identifier to supersede any TLTSID setting in the TLCookie module. This ensures Tealeaf uses the same common session identifier established for all Acoustic offerings.

The following example shows the TLCookie module options that are in the defaultconfiguration.js file. The TLCookie module options can also be configured through the Configuration wizard.

TLCookie: {

    /**
     * Comma separated whitelist of cookie names (strings) or regular
     * expressions (objects). The specified application cookies will
     * be recorded on each screenview load. No application cookies
     * will be recorded if this list is undefined or empty.
     */
    appCookieWhitelist: [{
            regex: ".*"
        }

    ],

    /**
     * Copy and paste the TL SaaS application key.
     */
    tlAppKey: ""
}

Securing the TLTSID cookie

By default, the TLTSID cookie that is created by the UIC is not a secure cookie. This ensures Tealeaf can correctly sessionize data from both secure (https) and regular (http) pages into a single session. For https-only applications, UIC can be configured to create TLTSID as a secure cookie. This is done by setting the secureTLTSID property to true in the configuration. NOTE: If this property is set, Tealeaf cannot correctly sessionize data from regular (http) pages or from pages where the domain is an IP address. DO NOT enable this setting for applications with mixed http and https pages.

TLCookie: {
    secureTLTSID: true,
    ...
}

Overriding the samesite=Strict setting

By default, the TLTSID cookie created by the UIC has the samesite property set to Strict. Depending on application needs, you can override this setting. The following example instructs the UIC to set the samesite property of the TLTSID cookie to None.

TLCookie: {
    secureTLTSID: true,
    samesite: "None",
    ...
}

Check7UIC7Cookie7Configuration77 session id

If the UIC is unable to create or retrieve the session identifier in the browser it sends a special value of Check7UIC7Cookie7Configuration77 instead. When this happens, Tealeaf on Cloud will use the Client IP address to generate a unique session identifier.

The most common reasons for the Check7UIC7Cookie7Configuration77 value to be sent are:

  • UIC is configured to neither use Cookies nor Local Storage for the session id, i.e., the "NO SESSION ID" entries described in the previous table.
  • UIC is configured to only use Cookies but the session cookie could not be set. This could be due to:
    • Browser-specific limits have been reached for cookie creation on the application domain.
    • 3rd party scripts or extensions are preventing the default TLTSID cookie from being created. Specifying a different name for the cookie via the sessionizationCookieName configuration property could help to work around such issues.
    • Cookies are disabled on the browser.
  • UIC is configured to only use Local Storage but the storage key could not be created. This could be due to:
    • Browser-specific limits have been reached for the local storage.
    • 3rd party scripts or extensions are preventing the default TLTSID key from being created. Specifying a different name for the key via the sessionizationCookieName configuration property could help to work around such issues.
    • Local Storage is disabled on the browser.

Data Layer module

The dataLayer module logs the application data layer. The data layer is a JavaScript object. It is used to exchange application information with analytics and tag managers. If the application has implemented a data layer object, you can configure the UIC to log the data layer. The data layer log is then available in the Tealeaf session for creating events and reports.

Configure the location of the data layer object, as shown in the following example.

modules: {
    dataLayer: {
        dataObject: "window.utag_data"
    },
    ...
}

Usually, the data layer object is defined at the start of the page. If the data layer object is not defined, specify a function that returns the data layer object, as shown in the following example.

modules: {
    dataLayer: {
        dataObject: function () {
            return window.utag_data || null;
        }
    },
    ...
}

The UIC will log the data layer in a type 19 message after every screenview load.

You can configure a blocklist for the screenviews for which you do not want the data layer to be logged. A list of properties that should not be logged can also be specified.

modules: {
    dataLayer: {
        dataObject: "window.utag_data",
        screenviewBlocklist: [
            "#info",
            { regex: "^#search", flags: "i" }
        ],
        propertyBlocklist: [
            "currency",
            { regex: "_code$" }
        ]
    },
    ...
}
Property name
Data type
Description

dataObject

Object or Function

The data layer object or a function that returns the data layer object.

screenviewBlocklist

Array

Optional. List of string or regex values that match the screenview name for which the data layer should not be logged.

propertyBlocklist

Array

Optional. List of string or regex values that match the property name, which should not be logged.

Updated 3 months ago


UI Capture reference


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.