This section includes frequently asked questions about how to acquire, implement, and use the IBM Tealeaf UI Capture library that is provided by UI Capture.

Note: Except as noted, questions and answers in this section apply to IBM Tealeaf UI Capture only.

Getting started

What is UI Capture?

UI Capture is a JavaScript library, an example server-side application, and documentation. You use UI Capture to capture the visitor's interactions with the web page (mouse clicks, keyboard input, scroll, and touch interactions, and so on), browser environment (window dimensions, and so on), and performance information (for example, render times).

UI Capture collects this information and builds a message that is later posted to a target page on the application server. The target page does not perform any processing and returns an HTTP 200 status.

Posting can occur on unload, after a pre-defined time interval, or after the message queue reaches a pre-defined size.

Since the IBM Tealeaf core product captures all request and response interactions between the browser and the server, the posted UI Capture data can be used to replay and report on the user interaction occurring within the page.

What versions of UI Capture are available?

UI Capture is available in two versions.

Beginning in Release 8.6, IBM Tealeaf introduced IBM Tealeaf UI Capture. UI Capture submits data in an updated JSON schema. IBM Tealeaf UI Capture is required for IBM Tealeaf cxOverstat.

Why do I need UI Capture?

UI Capture captures user interactions with an application.

Some 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.

Replay of Ajax web applications requires the inclusion of the UI Capture JavaScript to capture the UI events generated as a result of the user interaction with the application. These captured UI events are used to stimulate the application during replay to match the Ajax requests/responses.

How do I implement UI Capture?

The following steps describe the basic process to implement the IBM Tealeaf UI Capture.


  1. Determine which pages must be instrumented. Typically, these pages include JavaScript based functionality of interest. For more information, contact
  2. Obtain the library from your software distribution. For more information on downloading IBM Tealeaf, see IBM Passport Advantage Online.
    • For the latest version information, see the Release Notes published on
    • You can access IBM Tealeaf Online Help through the Help menu in your IBM Tealeaf Portal. If you know your company login, use the URL above.
  3. Determine the capture options that are required for your web application. These options can vary for different pages on the website.
  4. Based on the options you select, modify the JavaScript configuration files that are provided in the library.
    IBM Tealeaf UI Capture includes a GUI utility to help the configuration of your UI Capture solution. This Configuration Wizard performs data validation and configures the IBM Tealeaf JavaScript depending on your selections.
  5. Modify the JavaServer page (.jsp) provided by IBM Tealeaf to meet your requirements. Or, you can choose to replicate it in a different server language, such as ASP or PHP.

    This page accepts the posts from the IBM Tealeaf JavaScript running on the browser and returns a success code. It does not evaluate or manipulate the received data, which is forwarded to and processed by your IBM Tealeaf system.

  6. Modify the pages that call the UI Capture library to include the IBM Tealeaf JavaScript.
  7. In a test environment or on a non-production page on your production site, publish the IBM Tealeaf target page, the configured IBM Tealeaf JavaScript, and the modified pages.
    Note: This environment must be captured by IBM Tealeaf as a separate test environment instance or the production instance that is configured to keep the test traffic separate from your production traffic.
  8. Test the web pages to ensure that the addition of the IBM Tealeaf JavaScript interacts correctly with the page.
  9. Test the captured traffic on your IBM Tealeaf instance to verify that the UI traffic was captured.

    In some cases, you modify the replay rules to correctly replay these sessions. If you have any problems, review the documentation or contact

  10. After you verify that all instrumented UI elements are being properly captured and processed by IBM Tealeaf, publish the changes to your production environment with your normal publishing and change control processes.

What is the size of UI Capture?

When the UI Capture JavaScript is turned into a production version that is minified and compressed, it is approximately 22K.

Can I bundle the UI Capture library with other JavaScripts?

No. Do not combine the UI Capture library with other JavaScripts.

IBM Tealeaf 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 JavaScripts, IBM Tealeaf does not support bundling.


  • The IBM Tealeaf library is mutually independent of any other code that runs in the context of your web application. Maintain this separation as a general policy.
  • The browser treats each JavaScript include tag as a single unit of execution. When you bundle JavaScripts, a dependency is created between 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 IBM Tealeaf 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 bundled library needs to be tested concerning the application, as well as any required testing for individual libraries. The IBM Tealeaf JavaScripts can require configuration updates and multiple iterations to verify.
  • Individual script changes or library upgrades 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 IBM Tealeaf JavaScript from your bundled scripts is not an option, then in most situations the IBM Tealeaf JavaScript should be the last component of the bundle. Consult with IBM 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?

The library is designed to minimize the load on the web server and the web page running in the browser.

As part of the above implementation steps, the downloaded JavaScript is minimized and is cached by the browser.

Web server optimizations can further improve performance through server-side compression and caching settings.

See UI Capture installation and implementation for more information.

The server application accepting the posts is very simple and does nothing with the data.

The library posts add an extra hit or two to every page being captured by IBM Tealeaf. The size of the hit is small, normally increasing IBM Tealeaf storage requirements by less than 10%.

By design, the IBM Tealeaf system does not mix these hits with normal page hits in the page count reports.

With the library, your IBM Tealeaf solution may need to be configured with new replay rules to obtain replay fidelity.

Where can I get latest version of UI Capture?

To obtain latest version of the UI Capture JavaScript code, go to IBM Passport Advantage Online.

What is the TLTSID cookie?

For Tealeaf on Cloud, TLTSID is a session cookie that is created by the UIC to track the visitor session. For additional details, see Configuring the TLCookie module.

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

For Tealeaf on Cloud, TLTSID cannot be “httponly” because the TLTSID 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 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 the library, UI Capture can capture render times, browser dimensions, UI events (click, text input, scroll information, and so on) and more.

What is the eval function and why does the UI Capture SDK use it?

The UI Capture SDK uses the eval function to perform JSON parsing on browsers that do not have built-in support for JSON. All modern browsers support JSON parsing, but older browsers, such as Internet Explorer 6 and Internet Explorer 7, do not have native support for JSON. UIC uses the eval function to provide a simplified JSON parsing implementation for these browsers.

Can I prevent the UI Capture SDK from using the eval function?

Yes. You can disable eval by setting the defaultToBuiltIn flag to false in the Serializer Service configuration. For more information, see the Serializer Service configuration in the UI Capture Reference.

When you disable built-in JSON support by disabling eval, the library does not function on browsers that do not have native JSON support, unless you use an alternative 3rd-party JSON library that provides equivalent JSON parsing capability on the browsers. For example, you might want to use a 3rd-party library that provides a more elaborate implementation of JSON parsing by checking data before performing an eval operation. If your website supports visitors using older browsers that do not have native JSON support, select a JSON parsing library that meets your IT security requirements and ensure that you configure the UI Capture SDK through the Serializer Service configuration to make use of the 3rd-party JSON library.

I am having trouble with UI Capture implementation. Where do I get support or help?

To contact Customer Support, visit the IBM Support Portal or connect through your Salesforce account.

Using UI Capture

How do I configure what is captured by UI Capture?

Currently, the IBM Tealeaf UI Capture solution does not support dynamic or configurable capture levels.

UI Capture monitors a predefined set of user interface events and properties, submitting messages for those that are detected and captured.

You can configure UI Capture to capture custom events specific to your web application. See UI Capture Public API Reference for more information.

What is captured from mobile web sessions?

Mobile web sessions are captured by using the same JSON schema that is used for desktop sessions, with some exceptions.

What if I find a bug with UI Capture?

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

Be prepared to provide the following information:

  • UI Capture version (found in tealeaf.js or tealeaf.min.js as @version
  • IBM Tealeaf Portal build number (at bottom of each Portal page)
  • RealiTea Viewer version (if used)
  • An IBM Tealeaf session not containing any sensitive information

How can I create events from UI Capture data?

IBM 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.

How can I search for UI Capture data?

JSON-based data is indexed and available for search. Additionally, you can search for UI Capture data if you created events and attributes to track and capture the data.

How do I capture only mouseover events on menu?

IBM Tealeaf UI Capture does not support capture of mouseover events.

How do I capture keyup events?

The JSON version of IBM Tealeaf CX UI Capture for AJAX does not capture keyup events from the client.

Instead, monitor the change events for the same objects.

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

IBM Tealeaf captures data that is exchanged between the browser and web server. To capture data that is not exchanged between the browser and web server, such as client-side validation, you create custom events.

As such, any validation or error condition that is detected on the server and communicated to the client is recorded in the IBM Tealeaf session.

Client-side validation is normally done by a JavaScript running on the user's browser. This validation does not result in a data exchange between the browser and 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 IBM Tealeaf events that operate on the network traffic.

One solution is to make the client-side validation triggers part of the network traffic. Using an API provided with UI Capture, you can create a custom UI event in the browser by the same code that detects and triggers the validation message.

In the following example, a client-side validation function checks to verify that an input field is not empty.

function Validation_Check(user_input_element)
     if (!user_input_element.value) {
          // Input is empty, validation failed
          return FAILURE;
     return SUCCESS;

To capture this validation trigger in an IBM Tealeaf session, you must create a custom event by using the TLT.logCustomEvent() method. The generated output can be captured from JSON format.

How do I force the sending of queued events?

By default, IBM Tealeaf queues captured UI events for transmission that 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 for capture by IBM Tealeaf.

For example, if a UI element such as a Submit button triggers the onbeforeunload event, the execution of that code can empty the queue of events before the onclick chain of events were properly submitted the queued events. In such a case, the onclick event that arrives after the completion of the site's event handler is lost.

To handle these situations, the library enables the forced flushing of the event queue during the unload phase.

To manually start this API in your code call TLT.flushAll()

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

You can configure the UI Capture Configuration Wizard so that only performance data is submitted.

In the UI Capture Configuration Wizard, enable the Performance module only. Disable the Replay module. This configuration forces IBM Tealeaf UI Capture to submit only performance data, which includes the Page Render time metric.

See Configuring settings and features with the Configuration wizard for more information.

I use DHTML on my checkout form. Is UI Capture going to capture the dynamically rendered DOM elements?

DHTML is managed by calling to TLT.rebind() to attach event handlers to your dynamically created input elements.

How do I get render times from UI Capture?

You can configure the UI Capture Configuration Wizard so that only performance data is submitted.

In the UI Capture Configuration Wizard, enable the Performance module only. Disable the Replay module. This configuration forces IBM Tealeaf UI Capture to submit only performance data.

For all modern browsers that implement the W3C Navigation Timing specification, render times are reported through the Performance module.

See Configuring settings and features with the Configuration wizard for more information.

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

If possible, assign unique IDs to the HTML elements that must be tracked. If doing so is not an option, assign unique IDs to the nearest ancestor HTML element.

In the absence of an ID, IBM Tealeaf UI Capture builds an XPath like Document Object Model (DOM) path, which ends on the nearest ancestor with a valid HTML ID.

Can I customize UI Capture JavaScripts?

No. IBM Tealeaf UI Capture provides configurable libraries for capturing user interface events for visitors to your j2 application, including many configuration options for tailoring the events to be captured and the methods by which they are captured.

These options are indicated in the product documentation and in the UI Capture scripts.

IBM Tealeaf is disabled during Replay by setting Tealeaf and its objects to empty objects. This allow us to block Tealeaf from running during Replay. In the specific case where you added custom code, and did not disable it during Replay, while the rest of Tealeaf is disabled during replay through ReplaySplice JS, you may encounter JavaScript errors during replay, which causes replay to appear broken. If you add any custom code, you must make sure it is disabled in ReplaySpliceJS on the Replay Server.

Note: Modifications other than configuration changes to the JavaScript code of IBM Tealeaf UI Capture that are not implemented by IBM Tealeaf according to an IBM Professional Services engagement voids the warranty concerning the software, and such modified code is not supported under the IBM Tealeaf Maintenance and Support program. For more information, contact IBM Professional Services.

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

When the UI Capture solution is initialized on any page of your web application, it tries to attach to any frame elements on the page. However, if these frame elements are not in the same domain as the web application, most browsers register this action as cross-domain access and forbid the execution of the UI Capture script.

There is no means of anticipating the browser denying access due to this security restriction.

UI Capture continues to function normally. However, actions that are executed in the iFrame cannot be monitored.

Some browsers record an error message in the console. For purposes of UI Capture functions that are described above, this message can be ignored and does not adversely impact either UI Capture 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 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, include the UIC 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

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

The inactivity timeout setting stops recording user interactions for a page after specified amount of user inactivity on the 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. Terminating the recording prevents later POST requests (UI hits) of the library from creating one-hit or orphaned sessions. The termination also prevents any interference or accidental activation of the keep-alive behavior within an application. In order for this setting to be effective, the inactivity timeout threshold should be kept lesser than the session timeout on the server. The timer interval in the queue configuration should also be set to enable the queue to flush after a specific threshold. The threshold to flush the queue should be less than the inactivity timeout. This ensures that any pending data in the queue is flushed long before the inactivity timer expires.

A good model would be to follow this formula:

Server session timeout >= Inactivity timeout + Queue timer interval

For example, if the session timeout is 30 minutes and the queue timer interval is set to 5 minutes then an appropriate inactivity timeout setting would be 20 – 25 minutes.

Note: The inactivity timer is reset when any event in the default configuration occurs, except for the orientationchange event. The orientationchange event does not reset the inactivity timer because the mobile device might report an orientationchange event when the user is not deliberately interacting with the application. For example, the orientation of the mobile device might change while the device is stored inside a pocket, bag, or carrier.

The default inactivity-timeout setting is configured for 10 minutes. Setting the value to 0 disables the inactivity-timeout feature and allows the library to continue recording user interactions on the page. UI hits continue to POST while the page remains active, regardless of any periods of user inactivity on the page. Disabling the inactivity-timeout feature is not recommended in a production environment.

The value for the inactivity-timeout setting can be configured in the core configuration by using the Configuration wizard or by changing the value for inactivityTimeout. The value for the inactivityTimeout is specified in milliseconds.

The following snippet shows how to change in the inactivity-timeout setting in the core configuration. This example sets the inactivityTimeout for 8 minutes.

core: {
  // Set the inactivity timeout to 8 minutes (480000 milliseconds)
  inactivityTimeout: 480000,
  modules: {
    performance: {

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

insertRule, addRule, and deleteRule do not cause any DOM Mutations and cannot be tracked or captured by using DOM Capture.

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 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. Do not set the timeout too low (< 0.5 second) because this can result in a large number of scroll messages being recorded.

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
    // Geolocation configuration
    geolocation: {
        enabled: false,
        triggers: [

Upgrading the library

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

For IBM Tealeaf UI Capture, library version information is provided in the X-Tealeaf header.

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

Through the browser, navigate to the TealeafTarget.jsp file on your website by using the version query parameter.

The following URL is an example:

Note: If this URL does not return the version information, you do not have the latest version.

When do I upgrade?

Whenever possible, use the latest version of IBM Tealeaf UI Capture.

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

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

How do I find out about available updates?

  1. Acquire the version number for your current installation of IBM Tealeaf UI Capture. See How do I determine which version of the library I am using?
  2. Compare the above number to the latest available version. For more information on downloading IBM Tealeaf, see IBM Passport Advantage Online.

Version information is also published in the general Release Notes in the IBM Tealeaf Online Help.

Conditional Initialization

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


Normally, the UI Capture SDK 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 UI Capture SDK.

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

  1. Locate the UI Capture configuration section. This section is normally found towards the end of the UI Capture SDK JavaScript file.
  2. Replace the anonymous self-executing function which invokes the TLT.init() API with a named function which can be called at a later stage from within the application.
    function initTealeafUIC() {
        "use strict";
        var TLT = window.TLT,
        if (TLT.getFlavor() === "w3c" && TLT.utils.isLegacyIE) {
            changeTarget = "input, select, textarea, button";
            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 UI Capture SDK will not initialize automatically on page load. Rather, the named function initTealeafUIC() has to be explicitly invoked by the application in order to initialize the UI Capture SDK. The application can choose to invoke this function based on any runtime condition.

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

Join The Discussion

Your email address will not be published. Required fields are marked *