Integrate the Tealeaf SDK into your web application

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

  • 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. This will make implementation easier.
  • 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.

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.
Admin area access in Tealeaf

Admin area access in Tealeaf

  1. On the Admin page, open the Applications tab.
Applications module in Tealeaf

Applications module in Tealeaf

  1. If a new app is required, click to add an app and fill out required settings.
  2. 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.
Code snippet for web applications

Code snippet for web applications

Setup instructions

Step A: Create a custom JavaScript file

  1. Download the latest version of the SDK from our GitHub directory.
Installation files for the Tealeaf SDK

Installation files for the Tealeaf SDK

  1. In a text editor such as Notepad++ or Visual Studio Code, create a new .js file.
  2. 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).
  3. 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.

  1. 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.
  2. 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"
	}]
},
  1. 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
	}
}
  1. In another modules object, navigate to the TLCookie property and set the enabled parameter to true.
modules: {
	TLCookie: {
		enabled: true
	}
},
  1. 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'
                }
            ]
        },
  1. Save the changes.

Required configuration parameters

Here is a summary of required configuration parameters.

Parent objectPropertyParameterValuesDefinition
queuequeuesendpointStringThe endpoint allocated to your organization within Acoustic Tealeaf.

Use the full URL.
queuequeuesencoderDefault and required value - gzip.gzip prompts the SDK to use the included pako library.
modulesTLCookietlAppKeyStringA unique number used to route traffic from the endpoint to the correct app and organization.
replaydomCaptureenabledBoolean.

Default value - false. Required value - true.
Enables visual replay.
modulesTLCookieenabledBoolean.

Default value - false. Required value - true.
Generates a default TLTSID session cookie. When the module is disabled, an existing session cookie is used.

πŸ‘

Tip

Do not minify the Configuration section before you complete testing.

Step C: Configure recommended properties (optional)

We recommend introducing a few more customizations.

  1. Open your custom JavaScript file.
  2. In the queue object, navigate to the queues property and enable the checkEndpoint parameter for it.
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
    }]
},
  1. In the message object, navigate to the privacy property and add a whitelist privacy rule. Feel free to skip this setting when capturing your own test sessions, but keep in mind that it's crucial for production. If the SDK is going to be deployed for testing with real customer data, it makes sense to block everything by default, explicitly specifying what you want to capture in a whitelist, rather than blacklisting elements that you want to block.
message: {
		privacy: [{
				targets: ["input[type=password]"],
				maskType: 2
			},
			{
				targets: ["input[id*=phone]", "input[name*=phone]"],
				maskType: 4, // replace all digits with X except last 3
				maskFunction: function(value) {
					return value.slice(0, -3).replace(/\d/g, "X") + value.slice(-3);
				}
			},
			{
				exclude: true,
				targets: [
					"input[type=hidden]",
					"input[type=radio]",
					"input[type=checkbox]",
					"input[type=submit]",
					"input[type=button]",
					"input[type=search]"
				],
				maskType: 2, // replace all alphas with X and digits with 9
				maskFunction: function(value) {
					return value.replace(/[a-z]/gi, "X").replace(/\d/g, "9");
				}
			}
		],
  1. Save the changes.

πŸ“˜

Note

For examples and detailed instructions on privacy masking, see Privacy masking and blocking sensitive data.

Recommended configuration parameters

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

Parent objectPropertyParameterValuesDefinition
queuequeuescheckEndpointBoolean.

Default value - false. Recommended value for production - true.
The endpoint check feature causes the SDK to send a test POST to the endpoint when it loads. This is a safety feature that prevents the SDK from waiting for the endpoint and potentially impacting site performance and affecting the user experience.
queuequeuesendpointCheckTimeoutNumber (in milliseconds). Default value - 3000 ms.If the endpoint does not respond within the specified timeout, the SDK is simply unloaded. Increase the default value if required.
messageprivacyexcludeBoolean. Default value - false.Set to true to use a whitelist instead of the default blacklist.
messageprivacytargets"input[type=hidden]" "input[type=radio]" "input[type=checkbox]"
"input[type=submit]" "input[type=button]" "input[type=search]"
"input[id*=phone]"
"input[name*=phone]"
The list of elements you don't want to block (in case exclude is set to true).
messageprivacymaskType2 - letters are replaced with X’s and digits are replaced with 9’s

4 - all digits except for the last three are replaced with X’s.
Defines how sensitive data will be masked.

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