This section includes frequently asked questions about how to acquire, implement, and use Tealeaf Web SDK.

Note: Except as noted, questions and answers in this section apply to the Tealeaf Web SDK only.

Getting started

Question: What is Web SDK?

Web SDK 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).

Web SDK 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.

Question: Why do I need Web SDK?

Tealeaf uses data gathered by the Web SDK 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.

Question: What is the size of Web SDK?

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

Question: Can I bundle the Web SDK with other JavaScript?

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

Acoustic recognizes that some customers bundle their JavaScript resources into a single file to simplify the 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 Web SDK with other unrelated JavaScript.

Risks

The Web 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 Web SDK, 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 Web SDK 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 Web SDK from your bundled scripts is not an option, then in most situations the Web SDK 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.

Question: What is the TLTSID cookie?

For Tealeaf SaaS, TLTSID is a web session cookie that is created by the Web SDK 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.

Question: Why doesn't the TLTSID cookie use the "httponly" flag?

For Tealeaf 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 Web SDK.

Question: Why doesn't the TLTSID cookie use the "secure" flag?

TLTSID does not use a “secure” flag by default because the Web SDK 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, Web SDK can be configured to create TLTSID as a secure cookie. For more information, see Securing the TLTSID cookie.

Question: What does it mean when the TLTSID cookie contains the value "DND"?

When the Web SDK is initialized on the first page visit, it performs an automatic asynchronous request to check the status of the killswitch. If the killswitch is enabled, the Web SDK terminates itself for the remainder of the session. The TLTSID cookie value is set to "DND" in this case and no data is captured during this period. The TLTSID cookie will be reset when the visitor initiates a new browsing session.

Question: What is being captured by Web SDK?

Depending on how you configure, Web SDK 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 Web SDK JSON message types .

Using Web SDK

Question: How do I configure what is captured by Web SDK?

Web SDK 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 Web SDK to capture custom events and data specific to your web application. Refer to the Web SDK Public API Reference for more information.

Question: 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 additional information.

Question: What if I find a bug with Web SDK?

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

Provide the following information in your report:

Web SDK 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
A Tealeaf session not containing any PII or sensitive information
Tealeaf Portal build number at bottom of each Portal page (if applicable)
BBR or RealiTea Viewer version (if applicable)

Question: How can I create events from Web SDK data?

Tealeaf Web SDK 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 additional information.

Question: How can I search for Web SDK data?

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

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

Question: 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 Tealeaf on-prem, any validation or error condition that is detected on the server and communicated to the client is recorded in the Tealeaf session. Client-side validation is normally done by JavaScript running in the visitor’s browser. This validation does not result in 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 Tealeaf events that operate on the network traffic.
For Tealeaf SaaS, this information will have to be explicitly recorded in the Tealeaf session using the Web SDK TLT.logCustomEvent API.

Refer to Web SDK Public API Reference for additional information.

Question: How do I control the network requests made by the Web SDK?

By default, Web SDK 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 Web SDK queue.

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

Question: 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 Web SDK so that only performance data is submitted.

In the Web SDK Configuration Wizard, enable the Performance module only. Disable the Replay and Overstat modules.

Question: Will Web SDK 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 Web SDK can then be configured to take a DOM snapshot using this custom event as the trigger.

Question: 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, Web SDK 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.

Question: Can I customize Web SDK JavaScript?

Modifications other than documented configuration changes to the Web SDK 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 Web SDK, contact Acoustic Professional Services.

Question: Why do I get cross-domain error messages in my browser's debug console related to iFrames on my site?

When the Web SDK 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 Web SDK action as a cross-origin access.

The Web SDK 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 Web SDK or your application.

Question: Why does the Web SDK not capture data immediately after loading?

When the Web SDK is included in a page as recommended, the loading of the Web SDK 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 Web SDK 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 Web SDK to initialize in a timely manner.

The Web SDK 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 Web SDK is initialized successfully. The Web SDK starts capturing data after it is initialized.

For best results, the Web SDK should be included as described in Step 3 of Web SDK.

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

Question: Why does the Web SDK stop recording user interactions after an extended period of user inactivity on a page?

After initialization, the Web SDK 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.

Question: 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 Web SDK record all scroll events?
When a visitor scrolls on a page, the browser generates hundreds of scroll events, which Web SDK processes and combines into one consolidated type 1 Clientstate scroll message. When creating the message, Web SDK 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 Web SDK 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 Web SDK 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

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

The library version 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 using the browsers developer console.
Examining the JavaScript source for the version string.

Question: 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.

Question: When do I upgrade?

You should integrate the Web SDK upgrade into the existing maintenance and deployment processes for your application.

If you are experiencing Web SDK issues, you must upgrade to the latest version of Tealeaf Web SDK since it contains the most recent improvements.

Question: What are the best practices for upgrading the Web SDK?

The best practice is to incorporate the Web SDK as part of the application development and QA cycle.

Upgrading the Web SDK typically involves the following steps:

Replace the pako gzip encoder with the version specified in the Web SDK Release Notes.
Replace the core library with a copy of tealeaf.js or tealeaf.min.js from the release package.
Replace any custom or optional modules with their latest versions.
Review and merge existing configuration settings into the defaultconfiguration.js from the release package.

It is recommended to use a diff/merge tool such as WinMerge, P4Merge, or BeyondCompare to simplify the upgrade process.

Please contact Acoustic Services if you need assistance with the upgrade.

Conditional Initialization

Question: Can I initialize Web SDK only when an application-specific condition is met?

Yes

Normally, the Web SDK is required to capture all user interactions 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 consent. If consent is given, then the application can invoke the initialization process of the Web SDK.

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

Locate the Web SDK configuration section. This section is normally found towards the end of the Web SDK JavaScript file.
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
                        }
                    ]
                },

                ...

     });
}

With this change, the Web SDK 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 Web SDK. The application can choose to invoke this function based on any runtime condition.

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