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
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.
- Log in to Acoustic Tealeaf as an administrator.
- In the menu bar, click your user profile and select Admin.
![Admin area access in Tealeaf](https://files.readme.io/0694600-admin-area-access.png)
Admin area access in Tealeaf
- On the Admin page, open the Applications tab.
![Applications module in Tealeaf](https://files.readme.io/7272763-applications-module.png)
Applications module in Tealeaf
- If a new app is required, click to add an app and fill out required settings.
- 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](https://files.readme.io/84b5440-code-snippet-for-web.png)
Code snippet for web applications
Setup instructions
Step A: Create a custom JavaScript file
- Download the latest version of the SDK from our GitHub directory.
![Installation files for the Tealeaf SDK](https://files.readme.io/741b7bc-installation-files-for-connect-sdk.png)
Installation files for the Tealeaf SDK
- In a text editor such as Notepad++ or Visual Studio Code, create a new .js file.
- 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).
- 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.
- 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.
- 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
- Open your custom JavaScript file.
- In the
queue
object, navigate to thequeues
property and submit theendpoint
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"
}]
},
- In the
modules
object, navigate to theTLCookie
property and submit thetlAppKey
parameter for it. Use the application key generated at step A.
modules: {
TLCookie: {
appCookieWhitelist: [{
regex: ".*"
}],
tlAppKey: "47ba3bec0404ae386852ba908000000ad",
disableTLTDID: false
}
}
- In another
modules
object, navigate to theTLCookie
property and set theenabled
parameter totrue
.
modules: {
TLCookie: {
enabled: true
}
},
- In the
replay
object, navigate to thedomCapture
property and set theenabled
parameter totrue
.
replay: {
domCapture: {
enabled: true,
triggers: [{
event: 'click'
},
{
event: 'change'
},
{
event: 'load'
},
{
event: 'visibilitychange'
}
]
},
- Save the changes.
Required configuration parameters
Here is a summary of required configuration parameters.
Parent object | Property | Parameter | Values | Definition |
---|---|---|---|---|
queue | queues | endpoint | String | The endpoint allocated to your organization within Acoustic Tealeaf. Use the full URL. |
queue | queues | encoder | Default and required value - gzip . | gzip prompts the SDK to use the included pako library. |
modules | TLCookie | tlAppKey | String | A unique number used to route traffic from the endpoint to the correct app and organization. |
replay | domCapture | enabled | Boolean. Default value - false . Required value - true . | Enables visual replay. |
modules | TLCookie | enabled | Boolean. 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)
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.
Parameter | Values | Definition |
---|---|---|
checkEndpoint | Boolean. 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. |
endpointCheckTimeout | Number (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. |
Step D: Enable the Tealeaf SDK on your website
- Upload the customised JavaScript file to your web server, for example to the root directory or to a dedicated scripts directory.
- In the webpage template, add the following code snippet anywhere within the
<head>
tag. In thesrc
attribute, specify the path to the custom JavaScript file.
<script src="scripts/tealeaf.js"</script>
- 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:
- Remove the Tealeaf script from your webpage template.
- Remove the custom JavaScript file from your web server.
- Log in to Tealeaf and make sure there are no new sessions from your web application.
- If applicable, remove related events from Tealeaf.
Note
Save a copy for the custom JavaScript file before you get down to uninstallation.
Updated about 2 months ago