The Acoustic Analytics Developer Hub

Welcome to the Acoustic Analytics developer hub. You'll find comprehensive guides and documentation to help you start working with Acoustic Analytics as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

UI Capture reference

The Acoustic Experience Analytics (Tealeaf) UI Capture library configuration is an anonymous JSON object container. The library configuration includes different sections. You modify the defaultconfigurations.js file to set the configuration settings.

  • 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.
    You can also configure keys for capturing localStorage data.

Core configuration

The core configuration object contains basic information about the DOM events to which the Acoustic Experience Analytics (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 Acoustic Experience Analytics (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: {
       /**
        * 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 Acoustic Experience Analytics (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.
  • Acoustic Experience Analytics (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 Acoustic Experience Analytics (Tealeaf) CX Mobile. For more information, contact your Acoustic Experience Analytics (Tealeaf) representative.

touchend

Touch end events for mobile devices.

These events are replayed only if you licensed Acoustic Experience Analytics (Tealeaf) CX Mobile. For more information, contact your Acoustic Experience Analytics (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 Acoustic Experience Analytics (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
                    }
                ]
            },
            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: {
                sizzleObject: "window.Sizzle",
                jQueryObject: "window.jQuery"
            }
        },
     

Queue service configuration

Through the Queue service configuration, you can add extra event queues for processing and configure event queue properties that are based on traffic volume.

Note: Adding an extra queue is an advanced option and is not required in most deployments.

Property
Description

asyncReqOnUnload

Enables asynchronous XHR on page unload.

Warning: Enabling this option may result in incomplete or missing data.

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 to which messages are sent. This value corresponds to an Acoustic Tealeaf target page identifier. Sample targets for JSP and PHP environments are provided with the UI Capture distribution.

maxEvents

The maximum number of events in a queue. If this number of events is exceeded, the queue is automatically flushed, and all queued events are sent to the target for capture by Acoustic Tealeaf.

Note: Adjust the maximum number of events to a reasonable value, typically between 20 to 50. The maximum allowed value is 100.

timerInterval

The user inactivity interval in milliseconds after which message queues are flushed automatically. 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 Acoustic Experience Analytics (Tealeaf) users are shadow-browsing a visitor's session.

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 Acoustic Experience Analytics (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. 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 Acoustic Experience Analytics (Tealeaf) server for capture.

   message: {
           /**
            * Define privacy rules to modify 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 of
                    *  a custom function that must be specified as
                    *  maskFunction.
                    * @type {Number}
                    */
                   maskType: 3
               },
               {
                   targets: [
                       {
                           id: "[[\"HTML\",0],[\"BODY\",0],[\"SELECT\",0]]",
                           idType: -2
                       }
                   ],
                   maskType: 4,
                   /**
                    * A custom mask function that replaces the reported value
                    * by its return value ("masked", in this example)
                    * @param  {String} value The value to replace.
                    * @return {String}         Could return any string.
                    */
                   maskFunction: function (value) {
                       return "masked";
                   }
               }
           ]
       }
   },

Privacy configuration for UI Capture

Acoustic Experience Analytics (Tealeaf) UI Capture enables the blocking and masking of sensitive information within the client browser before the data is forwarded to Acoustic Experience Analytics (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 Acoustic Experience Analytics (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 Acoustic Experience Analytics (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

Acoustic Experience Analytics (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: {
                sizzleObject: "window.Sizzle",
                jQueryObject: "window.jQuery"
            }
        },

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 inline 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,

            /**
            * sizzleObject is the location of the Sizzle object on the page. If
            * this setting is not specified, it is assumed that the Sizzle object
            * will be in the global scope. i.e. window.Sizzle
            *
            * This setting is only valid when the W3C flavor of the browser
            * service is selected.
            *
            * @type {String}
            * @optional (only needed for W3C browserService and if jQuery
            *            is not defined)
            */
           sizzleObject: "My.location.Sizzle",

           /**
            * jQueryObject is the location of the jQuery object on the page. If
            * this setting is not specified, it is assumed that the jQuery object
            * will be in the global scope. i.e. window.jQuery
            *
            * @type {String}
            * @optional (only needed if jQuery is not defined on the window)
            */
           jQueryObject: "My.location.jQuery",
           /**
            * 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: [ "mycustomid" ]
       },

sizzleObject

This library is used by the W3C flavor of the library to evaluate CSS selectors on older browsers, such as IE7, that do not have native support for CSS selector based queries.

Note: This configuration item is needed only for the W3C browser service and if jQuery or Sizzle is not defined on the window object of your web application. Sizzle is included in jQuery by default so if the application has jQuery, the separate include of Sizzle might not be required.

  • The Sizzle library is required for some older browsers to acquire document elements that use a CSS selector.
  • The list of objects can be specified as comma-separated values, which can be fixed strings or regular expressions. These values are evaluated against the node ID.
  • The Sizzle JS engine is required for correct operation of the W3C flavor of the library in legacy browsers (e.g. IE 7) that do not have native support for CSS selector based querys. Sizzle is included in jQuery by default so if the application has a newer version of jQuery, the separate include of Sizzle may not required.

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 Acoustic Experience Analytics (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.
Supported 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: 1000,
                    
                     /* optional
		     * an integer number
		     * set the maximum number of alerts to be logged
		     */
		    maxAlerts: 40,


                    /* 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: ["sdk"]
  		}
		...
	}
	...
}

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"
                        },
                        {
                            event: "visibilitychange"
                        },
                        {
                            event: "unload"
                        }
                    ],
                }
            }

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 cookie only.

true

true

TLTSID in storage with fallback to cookie.

true

false

TLTSID in storage with fallback to cookie.

Not specified (default)

false

TLTSID in storage only.

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,
    ...
}

Updated 6 days 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.