This section includes frequently asked questions about how to acquire, implement, and use the Acoustic Experience Analytics (Tealeaf) UI Capture (UIC) SDK.

Note: Except as noted, questions and answers in this section apply to the Experience Analytics (Tealeaf) UI Capture SDK only.


Getting started

What is UI Capture?

UI Capture is a JavaScript library that is used to capture the visitor’s interactions with the web page (mouse clicks, text input, scroll, touch interactions…), browser environment (window dimensions…), and performance information (for example, render times).

UI Capture collects this information and builds a JSON message that is posted to a target page on the customer’s application server for the on-prem product or to the Acoustic cloud for the SaaS product. This data is used to replay and report on the user interaction occurring within the page. The data is buffered and posted on page unload, after a pre-defined time interval, or after the message queue reaches a pre-defined size.

For the on-prem product, the target page hosted on the customer’s application server simply collects the request data without performing any processing and responds with an HTTP 200 status. The entire request and response is captured by the Passive Capture Appliance (PCA) and made available as part of the visitor session.

Why do I need UI Capture?

Experience Analytics (Tealeaf) uses data gathered by the UIC from the visitor’s browser to enable you to visualize the user experience and interaction with your web app. Without this information, you will not be able to Replay or perform Usability analysis.

Even if you are using the on-prem product, certain user experience data only exists in the browser and is never transmitted back to the server. This data includes render times, order of form field entry, form abandonment, and more.

How do I get started with the UI Capture implementation for my web app?

Refer to Getting started with the UI Capture SDK.

What is the size of UI Capture?

A production deployment of the UIC that is minified and compressed is approximately 40K.

Can I bundle the UI Capture library with other JavaScript?

It is NOT recommended to bundle the UIC with other unrelated JavaScript.

Acoustic recognizes that some customers bundle their JavaScript resources into a single file to simplify deployment of static content. However, due to the following risks and costs that are associated with bundling unrelated JavaScript, we do not support bundling the UIC with other unrelated JavaScript.

Risks

  • The UIC SDK is mutually independent of any other code that runs in the context of your web application. Maintain this separation as a general policy for ease of maintenance and troubleshooting.
  • The browser treats each JavaScript include tag as a single unit of execution. When you bundle JavaScript, a dependency is created between otherwise independent libraries. An error in one of the bundled scripts can prevent the other libraries from running. In the worst case scenario, an error in a peripheral script such as the UIC can result in an application outage.
  • If bundling is unavoidable, the customer is responsible for performing risk mitigation through exhaustive testing of the bundled package to verify that no problems are being introduced.

Other costs of bundling

  • The UIC can require configuration updates and in some cases multiple iterations to verify.
  • Individual script changes or upgrades will require an entirely new bundle to be versioned, tested, and deployed.

Potential problems

Debugging problems in a bundled script is more complicated. Individual libraries cannot be easily enabled or disabled by using proxy tools such as Fiddler.

Note: If separating the UIC from your bundled scripts is not an option, then in most situations the UIC should be the last component of the bundle. Consult with Acoustic Professional Services to ensure effective management of the development and deployment of the bundle.

Will UI Capture impact the performance or behavior of my website?

Refer to Impact on your website.

Where can I get latest version of UI Capture?

Refer to step 1 in Getting started with the UI Capture SDK.

What is the TLTSID cookie?

For Experience Analytics SaaS, TLTSID is a web session cookie that is created by the UIC to track the visitor session. For additional details, see Configuring the TLCookie module.

For CXA, TLTSID will be a copy of the WCXSID cookie which is used to track the visitor session.

Why doesn’t the TLTSID cookie use the “httponly” flag?

For Experience Analytics SaaS, TLTSID cannot be “httponly” because the cookie is created by JavaScript. Cookies with the “httponly” flag are created with the HTTP Set-Cookie header and are NOT accessible by JavaScript. An “httponly” cookie on the website domain is not accessible to any script, including the UIC.

Why doesn’t the TLTSID cookie use the “secure” flag?

TLTSID does not use a “secure” flag by default because the UIC tracks the entire visitor session regardless if the visitor is visiting an http or https page. If the “secure” flag is set, TLTSID is available only on https pages, and visitor interactions with http pages cannot be correctly sessionized by Tealeaf.

For https-only applications, UIC can be configured to create TLTSID as a secure cookie. For more information, see Securing the TLTSID cookie.

What is being captured by UI Capture?

Depending on how you configure, UIC can capture render times, browser dimensions, user interaction events (click, text input, scroll information, and so on), rendered HTML and more.

For a list of properties that can be captured, refer to JSON message type schemas and examples for UI Capture.


Using UI Capture

How do I configure what is captured by UI Capture?

UI Capture monitors a predefined set of user interaction events, performance data, and properties as well as configurable choices like DOM snapshot triggers.

In addition, you can configure UI Capture to capture custom events and data specific to your web application. Refer to the UI Capture Public API Reference for more information.

What is captured from mobile web sessions?

Besides the usual data gathered from desktop browsers, mobile web browsers typically provide additional user interaction data related to touch, pinch and orientation. Customers can integrate HammerJS into their mobile web app to process high level gestures such as tap, doubletap, swipe etc.

Refer to Gestures configuration for UI Capture for additional information.

What if I find a bug with UI Capture?

If you find a bug, access the Support Portal to report it.

Provide the following information in your report:

  • UI Capture version (found in tealeaf.js or tealeaf.min.js as @version 5.6.0.1875 or by invoking the TLT.getLibraryVersion() API)
  • Steps to reproduce the issue
  • An Experience Analytics (Tealeaf) session not containing any PII or sensitive information
  • Experience Analytics (Tealeaf) Portal build number at bottom of each Portal page (if applicable)
  • BBR or RealiTea Viewer version (if applicable)

How can I create events from UI Capture data?

Experience Analytics (Tealeaf) UI Capture submits data in JSON format. You can create events and step attributes from this data through the Browser-Based Replay interface, using step-based eventing. These event objects can be modified in the Event Manager as needed.

Refer to JSON message type schemas and examples for UI Capture for additional information.

How can I search for UI Capture data?

Data from the UIC is in JSON format. The JSON data is indexed and available for search. Additionally, you can search for UI Capture data if you created events and attributes to track the data.

Refer to JSON message type schemas and examples for UI Capture for additional information.

How do I report on client-side validation/error messages?

To capture app specific data such as user input validation, you can create custom events using the TLT.logCustomEvent API.

For Experience Analytics on-prem, any validation or error condition that is detected on the server and communicated to the client is recorded in the Experience Analytics (Tealeaf) session. Client-side validation is normally done by a JavaScript running in the visitor’s browser. This validation does not result in a data exchange between the browser and the web server. While client-side validation messages can be seen during replay of the session by virtue of replaying the same user input events that lead to the validation failures, they cannot be detected by Experience Analytics (Tealeaf) events that operate on the network traffic.

For Experience Analytics SaaS, this information will have to be explicitly recorded in the Experience Analytics (Tealeaf) session using the UIC TLT.logCustomEvent API.

Refer to UI Capture Public API Reference for additional information.

How do I control the network requests made by the UIC?

By default, UIC queues captured messages for transmission. This buffering is based on predefined thresholds. In some cases, it is necessary to force the sending of a set of queued events to the web server. In rare cases, the app may decide to take full control of the flushing of the UIC queue.

UIC provides the TLT.flushAll() API to initiate an explicit flush of its queue. UIC also provides the TLT.setAutoFlush() API to enable or disable automatic flushing based on predefined thresholds. Refer to UI Capture Public API Reference for additional information.

For the first phase, the only desired metric is the Page Render time. Are there configuration settings that limit the captured data to just that metric?

Yes. You can configure the UIC so that only performance data is submitted.

In the UI Capture Configuration Wizard, enable the Performance module only. Disable the Replay and Overstat modules.

Will UI Capture capture the dynamically rendered DOM elements?

Yes. In DOM Capture configuration, specify a trigger event which occurs after the elements have been added to the DOM. For apps using lazy load to populate the content it is a best practice to fire a custom event to indicate when the app has finished the dynamic content update. The UIC can then be configured to take a DOM snapshot using this custom event as the trigger.

Do I need to have IDs assigned to my DOM elements that I would like to capture?

It is strongly recommended to assign static and unique IDs to the HTML elements that must be tracked from an analytics perspective. If doing so is not an option, assign static and unique IDs to the nearest ancestor HTML element. E.g. If it is not possible to assign static and unique HTML IDs to individual input elements contained within a form or a div, then the next best thing would be to ensure the parent form or div element has a static and unique HTML ID.

In the absence of any HTML ID, UIC builds an XPath like identifier, which ends on the nearest ancestor with a valid HTML ID. In general, the reliability of the XPath is inversely proportional to its length.

Can I customize UI Capture JavaScript?

Modifications other than documented configuration changes to the UIC JavaScript that are not implemented with an Acoustic Professional Services engagement voids the warranty concerning the software, and such modified code is not supported under the Maintenance and Support program. If you need a custom implementation of the UIC, contact Acoustic Professional Services.

Why do I get cross-domain error messages in my browsers debug console related to iFrames on my site?

When the UIC is initialized, it tries to identify and attach event listeners to the frames on the page. However, if these frame pages do not originate from the same domain as the web application, the browser will register the UIC action as a cross-origin access.

The UIC and your application will continue to function normally. However, visitor actions that occur in the cross-origin frame or iframe will not be monitored.

Some browsers record an error message in the console. This message can be ignored and does not adversely impact either the UIC or your application.

Why does the UI Capture library not capture data immediately after loading?

When the UI Capture library is included in a page as recommended, the loading of the UIC from the network or browser cache typically occurs before the DOM is fully created. After the DOM is created, the browser triggers the DOMContentLoaded event. The UIC initialization occurs after the DOMContentLoaded event is triggered. Any holdup in building the DOM delays the triggering of the DOMContentLoaded event thereby impacting the ability of the UIC to initialize in a timely manner.

The UIC is designed to ensure that it does not interfere during the critical phase of the page loading process. Use the TLT.isInitialized() API to check that the UIC is initialized successfully. The UIC starts capturing data after it is initialized.

For best results, the UIC should be included as described in Step 3 of Getting started with the UI Capture SDK.

For additional details on the DOMContentLoaded event and how to speed up the page load process, see Window: DOMContentLoaded event.

Why does the UI Capture library stop recording user interactions after an extended period of user inactivity on a page?

After initialization, the UI Capture library records user interactions that occur in a page until the page unloads or the browser is closed by the user.

If there is an extended period of inactivity where no user interactions are observed, the library ends the recording. The default inactivity threshold is 10 minutes.

Refer to Inactivity timeout setting for additional information.

Can DOM Capture track dynamic changes to CSS stylesheets made by insertRule, addRule, and deleteRule methods?

Dynamic changes to CSS stylesheets that use insertRule, addRule, and deleteRule methods do not result in any DOM Mutations. Therefore, these changes cannot be tracked and captured by using DOM Capture. Applications that use these methods to dynamically alter the CSS or use similar CSS-in-JS technologies might not replay correctly.

Why doesn’t UI Capture record all scroll events?

When a visitor scrolls on a page, the browser generates hundreds of scroll events, which UIC processes and combines into one consolidated type 1 Clientstate scroll message. When creating the message, UIC uses a scroll event timeout. The default scroll timeout is 2 seconds. The scroll events (including the scrolling action) must be paused for at least 2 seconds for the UIC to process and generate the scroll message. Any scrolling action that occurs within the scroll timeout window of the previous scroll action is considered to be part of the previous scroll action and is combined into a single message.

To increase the frequency at which UIC reports the scroll messages, configure the scroll timeout to be less than the 2 second default. Setting the timeout too low (< 0.5 second) can result in a large number of scroll messages being recorded and may impact application performance.

To configure the scroll timeout value and override the default, specify the scrollTimeout (in milliseconds) in the replay module configuration:

replay: {
    scrollTimeout: 500,     // Override the default scroll timeout
    // DOM Capture configuration
    domCapture: {
        enabled: true,
        triggers: [
    ...

Upgrading the library

How do I determine which version of the library I am using?

The library version information can be found in the following ways:

  • In the X-Tealeaf request header of the HTTP POST request to the endpoint.
  • Invoking TLT.getLibraryVersion() API at runtime.
  • Examining the JavaScript source for the version string.

How do I determine which version of the TealeafTarget file I am using?

Navigate to the TealeafTarget URL hosted by your web server and examine the response.

When do I upgrade?

You should integrate the UI Capture upgrade into the existing maintenance and deployment processes for your application.

If you are experiencing UI capture issues, you must upgrade to the latest version of Experience Analytics (Tealeaf) UI Capture since it contains the most recent improvements.

How do I find out about available updates?

Refer to the Release Notes.

Conditional Initialization

Can I initialize the UI Capture SDK only when an application specific condition is met?

Yes

Normally, the UI Capture library is required to capture all user interaction from page load to page unload. However, in certain application specific situations it may be desirable to initiate and terminate this capture functionality depending on various runtime variables.

For example, consider an application that requires user consent before it begins capturing analytics data. In such a case, the application can choose to implement its application specific user interface to obtain such a consent. If consent is given then the application can invoke the initialization process of the UIC.

To accomplish this, a simple change needs to be made in the UIC configuration section as follows:

  1. Locate the UI Capture configuration section. This section is normally found towards the end of the UI Capture JavaScript file.
  2. Replace the anonymous self-executing function which invokes the TLT.init() API with a named function (e.g. initUIC()) which can be called at a later stage from within the application.
    function initUIC() {
        "use strict";
        var TLT = window.TLT,
            changeTarget;
    
        if (TLT.getFlavor() === "w3c" && TLT.utils.isLegacyIE) {
            changeTarget = "input, select, textarea, button";
        }
    
        TLT.init({
            core: {
                modules: {
                    overstat: {
                        events: [{
                                name: "click",
                                recurseFrames: true
                            },
                            {
                                name: "mousemove",
                                recurseFrames: true
                            },
                            {
                                name: "mouseout",
                                recurseFrames: true
                            },
                            {
                                name: "submit",
                                recurseFrames: true
                            }
                        ]
                    },
    
                    ...
    
         });
    }
    
  3. With this change, the UIC will not initialize automatically on page load. Rather, the named function initUIC() has to be explicitly invoked by the application in order to initialize the UIC. The application can choose to invoke this function based on any runtime condition.

Once initialized, UIC will continue operation until page unload. To terminate the UIC at any time, invoke the TLT.destroy() API.