Install the Tealeaf Web SDK


Download and install the Web SDK.

Before you begin

Review the Tealeaf Web SDK overview for system prerequisites, supported browsers, and guidelines and tips before installing.

Download Web SDK

Download the latest release of our Web SDK.

Install the Web SDK JavaScript on your web server

The Web SDK should be installed in a web server directory that contains site JavaScript. For best performance, the JavaScript should be served with caching, and compression encoding (gzip) enabled. Consult your web server documentation to enable these settings.

Do not bundle Web SDK with unrelated scripts. Doing so creates an unnecessary dependency between otherwise completely independent scripts. The Web SDK can be bundled with 3rd party scripts that it has dependencies on, such as pako, hammer, and jQuery.

Use the non-minified, human-readable copy of Web SDK to ease the integration and debugging in the development environment. The non-minified JavaScript makes it easier to debug and add console logging functionality. Using the non-minified build in a production setting or during performance testing is not recommended.

Verify the JavaScript is accessible by navigating to the URL in the browser.

The Tealeaf Web SDK consists of a single JavaScript file. You place this JavaScript file with the other static files served by your site. To track the activity on a web page, you add a reference to the required Web SDK JavaScript file.
Every served page that requires client event tracking must have

If you place the Web SDK JavaScript in a place other than the root directory on your web server, adjust the src= parameter in the reference to point to the correct location.

Include the Web SDK JavaScript in your web application

Use the URL of the Web SDK JavaScript and include it in the HTML using the script tag. It is strongly recommended to set the async attribute for the best performance.

The Web SDK JavaScript can be included anywhere in the HTML and at any time during the page lifecycle, including after the page load. However, verifying correct operation with a simple static include is important before switching to any dynamic loading mechanisms.


Using script loaders or Tag Managers may cause the Web SDK not to be initialized in a timely manner on the page resulting in missed interactions or incomplete session replay. In a worst case scenario, issues with the loader may prevent the Web SDK from being loaded at all causing a complete loss of session data.

To capture all user interaction with the page and provide reliable analytics, the script must be statically included at the top of the HTML page in the head section as follows:

  <!-- NOTE: Replace /scripts/tealeaf.js with the path and name specific to your installation. -->
  <script async src="/scripts/tealeaf.js"></script>

Verify the JavaScript is loaded by checking for the presence of the window.TLT object on the page.

Install the Web SDK on web pages

When you plan the installation of the Web SDK, consider that it does use system resources to process on the website and the Tealeaf capture systems. Install the library only on the pages that you want to capture and replay.

Installing the Web SDK can cause the following effects.

  • Page load times can increase slightly during the first download. Tealeaf provides strategies for minimizing the effect on load times, including caching the JavaScript after the initial download.
  • More data is posted by the web page to the server, but it is not processed.
  • Tealeaf must process and store the additional data.
    Tealeaf Web SDK is designed to minimize these burdens.

Unique HTML IDs

To capture the client events for a Document Object Model object, each object or control available with which the visitor can interact must have a unique HTML ID. Without unique IDs, Tealeaf cannot properly replay the UI events on the page.

If you did not instrument your application to support unique IDs or unique names in the document object model, Tealeaf Web SDK automatically generates paths to the node that support the requirement of uniqueness.

Tealeaf also supports the creation of ID blacklists, which forces the use of Xpath or name attribute values as identifiers. See Web SDK reference for more information.


The web session must use cookies for sessionization. Cookies allow the client events to send messages without having to understand the sessionization mechanism.

For best results in capturing client UI events, deploy the Tealeaf Cookie Injector in your web server environment. The Tealeaf Cookie Injector provides unique session IDs regarding captured Tealeaf session data.

Uninstall Web SDK

To uninstall the Web SDK, apply the following changes in your Development environment.

  1. Save a copy of the currently deployed Web SDK JavaScript. If you minified the JavaScript, save a version of the source JavaScript.
  2. Remove the references to the Web SDK files from the pages of your web application.
  3. Remove the Web SDK files from the area where they are installed on your web server.
  4. Remove the Tealeaf target page.
  5. Push the changes to the server.
  6. Verify that no browser errors are generated in visitor browsers when you visit your own web application.
  7. Verify that Tealeaf Web SDK events are no longer being captured and processed by Tealeaf.
  8. Disable any Tealeaf event objects that reference UI events captured by Tealeaf Web SDK.

If the changes are applied successfully in your development environment, you can apply them in your Test and Production environments in succession.