The Tealeaf Web SDK is a JavaScript library that captures visitors' interactions with web applications. The findings are available in Acoustic Tealeaf.

Requirements

To use the Tealeaf SDK, your company must have an active Tealeaf subscription.

We support all types of web applications using standard HTTP and HTTPs protocols.

Recommendations

To make implementation faster and easier, consider these recommendations for your website.

• Discuss with your team the primary user flows and the type of data on your website that you want to capture.
• Ideally, assign unique static IDs to all HTML elements you want to track and to all sensitive user input fields.
• Use static container elements (div) with unique HTML IDs as placeholders for subsequent dynamic AJAX updates.

Static vs. dynamic content

To minimize the amount of data to process, the SDK doesn't capture static content (images, CSS files, script files, etc). All of it is downloaded during session replay. To make the most of this feature, we suggest that you clearly separate the static and the dynamic content of your web application into different container elements.

• Check for large blocks of inline CSS in the source of your pages. If possible, move styles to external stylesheet files that can be cached by the browser.
• Do not inline large data URIs in the HTML. Consider moving them into their own resource file or an external CSS file.

DOM

The following is important for correct session replay.

• Consolidate DOM changes to minimize the number of mutation records that need to be processed.
• Make DOM node insertions and removals to the innermost container elements instead of outer elements, like the document body.
• When using data binding for element attributes such as id, name, class etc., ensure that these values will also be reflected in the HTML DOM. An example of this is the Polymer framework's reflectToAttribute flag.

Shadow DOM

If your application uses Shadow DOM, ensure the following:

• Create Shadow roots in the “open” mode. Shadow DOM in “closed” mode is not captured.
• Minimize the number of Shadow DOM trees. The Tealeaf Web SDK and Replay performance is proportional to the number of Shadow DOM trees and the size of the HTML DOM content.

For information regarding limitations related to applications using Shadow DOM, see Supported application types in Tealeaf Web SDK overview.

Before you begin

To start using the Tealeaf SDK, you need access credentials.

1. Log in to Acoustic Tealeaf as an administrator.
2. In the menu bar, click your user profile and select Admin.

3. On the Admin page, open the Applications tab.

4. If a new app is required, click to add an app and fill out required settings.
5. Click the SDK link for your web app. Copy access credentials from the code snippet on the JavaScript tab: application code and endpoint URL. Keep them handy for step B.

Setup instructions

Step A: Create a custom JavaScript file

1. Download the latest version of the SDK from our GitHub directory.

2. In a text editor such as Notepad++ or Visual Studio Code, create a new .js file.
3. Copy the pako compression library into the .js file you have created (it reduces payload size before sending it to the Acoustic endpoints). Use pako deflate library version 1.0.11 (it works well with the SDK).
4. Open tealeaf.js (the minified version of the core library) and copy its contents into your .js file after pako.

🚧

Warning

The core library must stay as is. Do not make any changes to it unless instructed so by our services team.

5. Open defaultconfiguration.js and copy its contents to your .js file after the core library. Mark this section of the file as Configuration. This is where all the settings are.
6. Save the changes.

// custom .js file structure
<pako library, minified> // don't edit
<core library, minified> // don't edit
<configuration> // for editing

Step B: Configure required properties

1. Open your custom JavaScript file.
2. In the queue object, navigate to the queues property and submit the endpoint parameter for it. Use the endpoint URL you received at step A.

queue: {
	asyncReqOnUnload: true,
	useBeacon: true,
	useFetch: true,
	xhrEnabled: true,
	queues: [{
		qid: "DEFAULT",
		endpoint: "https://lib-eu-1.brilliantcollector.com/collector/collectorPost",
		maxEvents: 30,
		timerInterval: 60000,
		maxSize: 300000,
		checkEndpoint: false,
		endpointCheckTimeout: 4000,
		encoder: "gzip"
	}]
},

3. In the modules object, navigate to the TLCookie property and submit the tlAppKey parameter for it. Use the application key generated at step A.

modules: {
	TLCookie: {
		appCookieWhitelist: [{
			regex: ".*"
		}],
		tlAppKey: "47ba3bec0404ae386852ba908000000ad",
		disableTLTDID: false
	}
}

4. In another modules object, navigate to the TLCookie property and set the enabled parameter to true.

modules: {
	TLCookie: {
		enabled: true
	}
},

5. In the replay object, navigate to the domCapture property and set the enabled parameter to true.

replay: {
        domCapture: {
            enabled: true,
            triggers: [{
                    event: 'click'
                },
                {
                    event: 'change'
                },
                {
                    event: 'load'
                },
                {
                    event: 'visibilitychange'
                }
            ]
        },

6. Save the changes.

Required configuration parameters

Here is a summary of required configuration parameters.

👍

Tip

Do not minify the Configuration section before you complete testing.

Step C: Configure recommended properties (optional)

In your custom JavaScript file, navigate to the queue.queues object and enable the checkEndpoint parameter.

queue: {
    asyncReqOnUnload: isWebkit,
    useBeacon: true,
    queues: [{
        qid: 'DEFAULT',
        endpoint: 'https://lib-eu-1.brilliantcollector.com/collector/collectorPost',
        maxEvents: 50,
        timerInterval: 300000,
        maxSize: 300000,
        checkEndpoint: true,
        endpointCheckTimeout: 7000
    }]
},

Here is a summary of optional configuration parameters that we recommend to configure.

Step D: Enable the Tealeaf SDK on your website

1. Upload the customised JavaScript file to your web server, for example to the root directory or to a dedicated scripts directory.
2. In the webpage template, add the following code snippet anywhere within the <head> tag. In the src attribute, specify the path to the custom JavaScript file.

<script src="scripts/tealeaf.js"</script>

3. Push the changes to the server.

🚧

Warning

If possible, avoid bundling the Tealeaf JavaScript with other JavaScript files. The Tealeaf Web SDK can be bundled with 3rd party scripts that it has dependencies on, such as pako, hammer, and jQuery.

Setup verification

Basic verification

There are several ways to make sure the JavaScript has been added.

• Open the browser developer tools and enter TLT.getLibraryVersion() in the console. The SDK version should be returned. If a "TLT is not defined" message is returned, the library is not loaded.
• In Acoustic Tealeaf, go to Search and search for traffic captured from your web application.

Thorough verification

Verify client events are being posted. Deploy a browser monitoring tool such as Fiddler or HttpWatch, or use the Network tab in the browser developer tools to verify that client events are being posted to the endpoint.

• As a session is being generated, check the value of the TLTSID cookie, which is the Tealeaf session identifier.
• In the POST traffic stream, look for request headers that contain X-Tealeaf and a JSON message such as: {"messageVersion":"2.1.0.0","serialNumber":1,"sessions":....

Removing the Tealeaf Web SDK from your web application

To remove the Tealeaf Web SDK from your web application, do the following:

1. Remove the Tealeaf script from your webpage template.
2. Remove the custom JavaScript file from your web server.
3. Log in to Tealeaf and make sure there are no new sessions from your web application.
4. If applicable, remove related events from Tealeaf.

📘

Note

Save a copy for the custom JavaScript file before you get down to uninstallation.