Tealeaf Web SDK reference
The Tealeaf Web SDK library configuration is a JSON object. You modify the config
object in the defaultconfiguration.js file to specify the configuration settings according to your application and analytics requirements. The library configuration includes different sections.
- Core configuration object: Contains configuration information about Document Object Model events to which the library listens. See Core configuration.
- Services configuration object: Contains configuration information about the individual services that extend the core and provide the necessary functionality that is required by the library. See Services configuration.
- Modules configuration object: Contains configuration information about the modules that are enabled in the library. See Modules configuration object.
Core configuration
The core configuration object contains basic information about the DOM events to which the Acoustic Tealeaf Web SDK listens.
In Core, you define properties to assure capture of UI events.
Note: Do not modify these settings unless directed to do so by Tealeaf. For more information, contact Acoustic Professional Services.
For details about the Core configuration object, check out these sections:
- Internet Explorer links
- Blocking Web SDK from initializing on specific User Agents and Bots
- Custom events to trigger logging of load events
- Configure client events by module
TLT.init({
/**
* Base configuration for the core.
* It specifies which modules should listen to which events, which frames
* to ignore, which elements to block, and which links are excluded from
* triggering an unload.
* @type {Object}
*/
core: {
/**
* Use this to add a custom note which will be available for eventing
* in the session data.
*/
buildNote: "r3 MP 12/7/2020",
/**
* The ieExcludedLinks entry specifies a set of links that should
* not trigger the beforeunload event, which destroys the UI
* Capture library. This addresses a known issue with Internet
* Explorer. Specified as a comma separated list of CSS selectors.
*/
ieExcludedLinks: ["a.ignore"],
/**
* The blockedElements entry specifies a set of elements for
* which no user interaction is to be reported. No user interaction
* will be reported for the specified element and any child elements.
* Elements can be specified as a comma separated list of CSS selectors.
*
* Warning: The blockedElements entry is evaluated for each event.
* Specifying inefficient CSS selectors can cause performance issues.
*
* Note: This is an advanced feature which has implications for
* Tealeaf functionality and must only be used in unique situations
* that require such a restriction.
*
*/
blockedElements: [],
/**
* This is the module configuration section contains options
* relevant to the core.
* It contains the events to which the modules attempt to listen.
* NOTE: Please do not use this section for module-specific
* configuration, which you must access inside of your modules.
* @type {Object}
*/
modules: {
performance: {
enabled: true,
events: [
{
name: "load",
target: window
},
{
name: "unload",
target: window
}
]
},
replay: {
enabled: true,
events: [
/* Lifecycle events - not optional */
{
name: "load",
target: window
},
{
name: "unload",
target: window
},
/* User interaction events - not optional */
{
name: "change",
target: changeTarget,
recurseFrames: true
},
{
name: "click",
recurseFrames: true
},
/* Dwell time and previous state */
{
name: "focus",
target: "input, select, textarea, [contenteditable]",
recurseFrames: true
},
{
name: "blur",
target: "input, select, textarea, [contenteditable]",
recurseFrames: true
},
/* Hash change - optional */
{
name: "hashchange",
target: window
},
/* ClientState events - not optional */
{
name: "resize",
target: window
},
{
name: "scroll",
target: window
},
/* Mobile DOM events - optional */
{
name: "orientationchange",
target: window
},
{
name: "touchend"
},
{
name: "visibilitychange"
}
]
}
}
},
},
/* Following settings are related to the TLT.getSessionData() Public API */
/**
* Set the sessionDataEnabled flag to true only if it is OK to expose Tealeaf
* session data to 3rd party scripts.
*/
sessionDataEnabled: false,
/**
* The sessionData object specifies the query parameter name OR cookie name to
* get the session id value from. An actual deployment would only specify one
* of the methods to obtain the session id. If both are specified, the
* sessionQueryName takes precedence over sessionCookieName. If neither is
* specified, an internal default of "TLTSID" will be looked up in the cookies.
*/
sessionData: {
/**
* Specify sessionQueryName only if the session id is derived from a
* query parameter.
*/
sessionQueryName: "sessionID",
/* Optionally, specify the query string delimiter. Default is */
sessionQueryDelim: ";",
/* The cookie being used for sessionization in Tealeaf. */
sessionCookieName: "jsessionid",
/**
* Optionally, specify if the value needs to be hashed to derive the
* session ID.
*/
sessionValueNeedsHashing: true
}
/**
* The framesBlacklist array specifies the CSS selectors which correspond to the
* frame/iframe elements that should not be accessed.
*/
framesBlacklist: [
".tlBlock"
]
},
/* End of core configuration */
// Services configuration
...
// Module specific configuration
...
});
Internet Explorer links
(ieExcludeLinks)
Clicking some link URLs that use "intent", "mailto", "sms", or "tel" protocols can cause premature unload events. The Web SDK automatically ignores these unloads.
In Internet Explorer, clicking an href=javascript link can trigger the beforeunload event. If this link does not trigger a navigation change, then the Web SDK is destroyed prematurely, and subsequent UI events on the page are not captured.
To address this issue, you can specify a series of CSS Selectors that resolve to HTML elements, which, when clicked, do not trigger the beforeunload event.
In the ieExcludedLinks field, you can specify these HTML elements as an array of CSS selectors. In the example below, an <a>
anchor with a specified class (ignore) and an anchor with a specific class (foo) containing a span element are specified. If the user clicks either of these element types, then the resulting beforeunload event in Internet Explorer is ignored.
ieExcludedLinks: ["a[href^=javascript]", "a.ignore"],
Blocking Web SDK from initializing on specific User Agents and Bots
(blockedElements)
Web SDK can be prevented from capturing data on specific User Agents or Bots by adding a blockedUserAgents list to the core configuration. The list entries can be a string or a regular expression as shown in the example below. If the string or regex pattern matches with the User Agent string then the Web SDK will self-terminate and not capture any data from that browser.
blockedUserAgents: [{
regex: "(Google|Bing|Face|DuckDuck|Yandex|Exa)bot",
flags: "i"
},
{
regex: "spider",
flags: "i"
},
{
regex: "archiver",
flags: "i"
},
"PhantomJS"
],
This feature can be used to prevent crawl data from Bots, web crawlers, automated tests or unwanted browsers from interfering with your analytics reports. Do not use this feature if you intend to track Bot visits within Tealeaf.
NOTE: This feature prevents the Web SDK from capturing data. This feature cannot and will not prevent the Bot agent from crawling your site. This feature is NOT intended for and does not offer any security against malicious User Agents.
Custom events to trigger logging of load events
Web SDK triggers "load" events on initialization. You can use custom events to trigger logging of load events by adding "screenviewLoadEvent" in the core configuration.
In some cases, Web SDK triggers the load event before the page is fully rendered, which produces an incomplete initial DOM capture. To solve this problem, configure a custom event that triggers the load event at an appropriate time.
core: {
....
screenviewLoadEvent: {
name: "click", //This could be any custom event, or DOM event.
target: window
}
....
}
Configure client events by module
(modules)
The modules subsection of the core configuration specifies the events to which each module listens. Do not change the default settings.
See the following sections for a description of the modules and how to format events:
Format
An example configuration for an individual user interface event is:
{
name: "load",
target: window
},
Where:
- name identifies the W3C name of the user interface event.
- target identifies the client object that is the target of the event.
- The target can be a Document Object Model element such as document or window.
- The target can also be a string that contains comma-separated CSS selectors to be used as the targets.
- If target is not specified, it defaults to the document element.
Note: To disable an event, comment out or remove the entry. Some events are not optional and must remain enabled for correct operation of the library.
For some user interface events, configuration might be in this format:
{
name: "click",
recurseFrames: true
},
If recurseFrames is set to true, then evaluation is applied to all frames and subframes on the page that originate from the same domain as the page.
Performance
(performance)
The performance module parses the W3C Navigation Timing performance object and includes this information as the performance message in the JSON data stream that is sent back to the Tealeaf capture server.
For correct operation, do not modify this configuration. If the performance module is not required, remove this section from the core configuration.
###Replay
(replay)
The replay module provides the underlying data in form of JSON messages that enable features such as:
- Rich Internet Application (RIA) Replay: Browser Based Replay and RealiTea Viewer.
- Tealeaf cx Overstat usability functionality; heatmaps, form analytics, and attention maps.
- Step-based eventing.
Events are tracked for replay purposes on the client. Most of the events are required for replay. This table lists and describes the events tracked for replay purposes:
Property | Description |
---|---|
load | Page load event. This event is required. |
unload | Page unload event. This event is required. |
change | Control change event. This event is required. By default, it is configured to track all HTML elements that support the change event. Optionally, you can set recurseFrames to true to scan all frames and subframes of the page for these events. |
click | Click events on the page. This event is required. Optionally, you can set recurseFrames to true to scan all frames and subframes of the page for these events. |
focus | Focus events on the control. This event is required. Optionally, you can set recurseFrames to true to scan all frames and subframes of the page for these events |
blur | Blur events on the control. This event is required. Optionally, you can set recurseFrames to true to scan all frames and subframes of the page for these events. |
hashchange | When enabled, this option generates screen view events when a hash change was identified in the URL of the page.
|
resize | Resize events on the client. |
scroll | Scroll events on the client.Depending on your application, tracking windows that scroll can generate a significant number of events.Replay of scroll events is supported for mobile sessions in Browser Based Replay only.Note: For Attention Maps to work on scrollable pages, Web SDK must send scroll events. If you configure Web SDK not to send scroll events for such pages, the Attention map will not render correctly. |
orientationchange | Orientation change events for mobile devices.These events are replayed only if you licensed Tealeaf CX Mobile. For more information, contact your Tealeaf representative. |
touchend | Touch end events for mobile devices.These events are replayed only if you licensed Tealeaf CX Mobile. For more information, contact your Tealeaf representative.Pinch and zoom gestures can be captured on the iOS platform only. They cannot be captured on the Android platform. |
pointerup | Used in conjunction with pointerdown to infer "click" actions on disabled target elements. |
pointerdown | Used in conjunction with pointerup to infer "click" actions on disabled target elements. |
visibilitychange | Visibility change event. This event tracks when the browser tab is minimized/hidden or visible. |
Support for all of these replay events is provided in Browser-Based Replay only.
A subset of replay events might work in the RealiTea Viewer.
Services configuration
The Services configuration object contains options that are used by the individual services that are part of the Tealeaf Web SDK.
Note: When integrating the library with a new application, you typically modify only few of these configuration items.
See the following sections for a description of the services:
- Queue service configuration
- Message service configuration
- Serializer service configuration
- DOM Capture service configuration
- Browser service configuration
services: {
queue: {
// WARNING: Enabling asynchronous request on unload may result in incomplete or missing data
asyncReqOnUnload: false,
queues: [{
qid: "DEFAULT",
endpoint: "/TealeafTarget.php",
maxEvents: 50,
timerInterval: 300000,
maxSize: 300000
}
]
},
message: {
privacy: [{
targets: [
// CSS Selector: All password input fields
"input[type=password]"
],
"maskType": 3
}
]
},
serializer: {
json: {
defaultToBuiltin: true,
parsers: ["JSON.parse"],
stringifiers: ["JSON.stringify"]
}
},
encoder: {
gzip: {
/**
* The encode function should return encoded data in an object like this:
* {
* buffer: "encoded data"
* }
*/
encode: "window.pako.gzip",
defaultEncoding: "gzip"
}
},
domCapture: {
diffEnabled: true
},
browser: {
normalizeTargetToParentLink: true
}
}
Queue service configuration
Through the Queue service configuration, you can configure properties which determine the extent of the buffering and the endpoint destination to which the messages will be sent via HTTP POST.
Property | Description |
---|---|
asyncReqOnUnload | Enables asynchronous XHR on page unload.Warning: Enabling this option may result in incomplete or missing data. This is because most browsers will cancel outstanding asynchronous XHR or fetch requests during page unload. |
qid | Identifies the name of available event queues.Note: By default, one queue is defined as DEFAULT. Do not remove this queue or change its name. |
endpoint | Identifies the target URL to which the messages are sent. For on-prem, this value corresponds to a target page path. Sample target pages for JSP and PHP environments are included in the Web SDK release package. For SaaS, this value corresponds to the collector URL. |
maxEvents | The maximum number of messages in a queue. If this number is exceeded, the queue is automatically flushed, and all queued messages are sent to the configured endpoint. |
timerInterval | The user inactivity interval in milliseconds after which the queue is automatically flushed, and all queued messages are sent to the configured endpoint. The default value is 5 minutes. If this option is set to 0, the timer-based flush is disabled.Note: Keep this setting at the default value, unless a more immediate flushing of data is required, such as when Tealeaf users are shadow-browsing a visitor's session. |
maxSize | The maximum serialized length of the queue. If this is exceeded, the queue is automatically flushed, and all queued messages are sent to the configured endpoint. If this option is set to 0, the serialized length based flush is disabled.The recommended value for this setting is between 50000 to 300000. |
useBeacon | A boolean flag indicating if the W3C Beacon API should be used to send the request instead of XHR on page unload.Note: This setting should be set to false for Tealeaf Customer Experience on-prem using PCA versions below 3740. |
useFetch | A boolean flag indicating if the Fetch API should be used to send the request instead of asynchronous XHR. By default, the Web SDK uses fetch when available. Synchronous requests will continue to use XHR or Beacon as appropriate. |
Message service configuration
You use the Message service configuration to define options such as privacy rules applied to the JSON messages submitted to the Tealeaf server for capture. Applications using Shadow DOM should enable the Shadow DOM cache feature in order to optimize the Shadow DOM snapshot data sent to the server.
message: {
/**
* Applications using Shadow DOM should enable this setting.
*/
shadowDOMCacheEnabled: true,
/**
* Define privacy rules to modify/mask reported values in the
* messages sent to the server.
* @type {Array}
* @optional
*/
privacy: [
/**
* An example privacy rule.
*/
{
/**
* Specify the targets to which this rule should apply.
* @type {Array}
*/
targets: [
{
id: "htmlid",
idType: -1
},
{
id: "myid=custom",
idType: -3
}
],
/**
* The maskType defines how the value should get
* transformed.
* maskType 1: The value gets set to an empty string
* maskType 2: The value gets replaced with the fixed
* string "XXXXX".
* maskType 3: The value gets replaced by a mask where:
* each lowercase character gets replaced by "x",
* each uppercase character by "X",
* each number by "9"
* each symbol by "@"
* e.g. "HelloWorld123" becomes "XxxxxXxxxx999"
* maskType 4: The value gets replaced by the return
* value from the custom function that is
* specified as maskFunction.
* @type {Number}
*/
maskType: 3
},
/**
* another example of a privacy rule.
*/
{
targets: [
{
id: "[[\"html\",0],[\"body\",0],[\"input\",0]]",
idType: -2
}
],
maskType: 4,
/**
* A custom mask function that replaces the value
* with its return value ("masked", in this example)
* @param {String} value The value to replace.
* @return {String} Can return any string.
*/
maskFunction: function (value) {
return "masked";
}
}
]
}
Privacy configuration for Web SDK
Tealeaf Web SDK enables the blocking and masking of sensitive information within the client browser before the data is forwarded to Tealeaf for capture, while it allows the data to be forwarded to your web servers for normal processing. Sensitive data that was cleansed through Web SDK never reaches Tealeaf, which ensures that your customer's interactions are secure in Web SDK.
- Web SDK enables the blocking of user input data by element ID, name, or xpath.
- Masks can be expressed as explicit strings, replacements for character types, or custom functions.
- Use the blockedElements configuration setting in the Core configuration file to define a set of elements for which no user interaction is to be reported. For more information, see Core configuration.
Note: If you have questions about implementing data privacy in Web SDK, see Privacy masking and blocking sensitive data. Additionally, you can contact Tealeaf Professional Services for a consultation.
To specify a privacy rule, you must define:
- The type of identifier.
- The targets to which the rule applies.
- The type of masking to apply to the targets.
Specifying a privacy rule
In the configuration, a single privacy rule is specified within the privacy object by using the following configuration template.
{
targets: [
{
id: "htmlid",
idType: -1
}
],
maskType: 3
}
Specifying targets
To specify a target, you must specify the following properties.
Note: You can specify multiple id or idType targets for each masking rule.
Property | Description |
---|---|
id | The identifier for the target element. This value is specified according to the idType value.In the configuration file, you can use a regular expression to specify matching identifiers. For example, the following target configuration matches all HTML identifiers that end with _pii:message: { |
idType | The type of identifier. The following types are supported:Note: Values for idType are recorded as negative numbers.-1 - HTML ID -2 - xpath identifier -3 - HTML name or other element attribute identifier |
CSS selector
In the configuration file, you can also specify CSS selector values to match CSS elements for privacy masking. In the example below, the designated privacy rule is applied to all password input fields:
message: {
privacy: [
{
targets: [
"input[type=password]"
],
"maskType": 3
}
]
}
Specifying mask type
Tealeaf Web SDK supports the following mask types (maskType values):
Value | Description | Example | Masked example |
---|---|---|---|
1 | Value is blocked and replaced by an empty string. | "HelloWorld123" | "" |
2 | Value is masked with a fixed string of x's | "HelloWorld123" | XXXXX |
3 | Value is masked according to the following parameters:A lowercase letter is replaced by x. An uppercase letter is replaced by X. A numeral is replaced by 9. A non-alphanumeric value is replaced by @. | "HelloWorld123" | "XxxxxXxxxx999" |
4 | Custom functionNote: A masking function must be defined as maskFunction. | "HelloWorld123" | Defined on the defined function |
Serializer service configuration
You can specify which JSON parser and serializer functionality to use through the Serializer service configuration.
The library uses JSON as its message format. All modern browsers have built-in support for serializing and parsing JSON. However, legacy browsers (Internet Explorer 6 and 7) do not have this built-in support. For such browsers, a third-party library that provides JSON serialization and parsing capabilities is required. By default, the Web SDK relies on the built-in JSON capabilities of the browser where available, and defaults to a simplified internal implementation in other cases. If your application or IT environment mandates use of specific JSON parser or serializer, you can specify it using this configuration.
Warning: JSON serialization and parsing are fundamental to the library's ability to function and produce correct output. Thorough cross-browser testing is necessary if any changes are made to this configuration.
serializer: {
json: {
defaultToBuiltin: true,
parsers: [ "JSON.parse" ],
stringifiers: [ "JSON.stringify" ]
}
},
encoder: {
gzip: {
/**
* The encode function should return encoded data in an object like this:
* {
* buffer: "encoded data"
* }
*/
encode: "window.pako.gzip",
defaultEncoding: "gzip"
}
},
domCapture: {
diffsEnabled: true
},
browser: {
normalizeTargetToParentLink: true
}
},
DOM Capture service configuration
The DOM Capture service configuration provides options for enabling or disabling DOM diff, capturing same domain frame/iframes and specifying thresholds related to mutations and snapshot size.
Note:
DOM diff is supported only in Tealeaf SaaS. In Tealeaf On-premises, DOM diff is supported for web-only and not supported for replaying Hybrid Mobile apps.
domCapture: {
diffEnabled: true
}
Property | Description |
---|---|
diffEnabled | Set this to true (default) to enable DOM diff. Set to false to disable DOM diff. |
Optional configuration properties can be specified as follows:
domCapture: {
diffEnabled: true,
options: {
maxMutations: 500,
captureFrames: true
}
}
Property | Description |
---|---|
maxMutations | Specifies the mutation threshold after which a full DOM snapshot is taken instead of a diff. The default value is 100. Increase this value to improve the efficiency of DOM diff. Reduce this value if calculating the DOM diff results in performance issues due to processing a large number of mutations. |
maxLength | Specifies a safety threshold for DOM snapshot size. Snapshot sizes exceeding this value will not be sent. The default value is 1,000,000. Increasing this threshold can have an impact on application performance. |
captureFrames | Set this to true to enable DOM capture of same domain frames and iframes. The default value is false. |
captureShadowDOM | Set this to true to enable DOM capture of Shadow DOM content. The default value is false. |
removeScripts | Set this to false to disable removing script content from the DOM snapshots. The default value is true. |
removeComments | Set this to false to disable removing comments from the DOM snapshots. The default value is true. |
captureStyle | Set this to false to remove inline style so as to reduce the size of the DOM capture message. When set to true, the default value, the SDK captures all interior styles. |
discardBase64 | Set this to an 0 to remove the base64 image src string and reduce the size of DOM capture message. For every removed base64 image, Web SDK cleans the src attribute and adds an extra attribute to the element, which makes the node look like the following: By default, there is no "discardBase64" setting in configuration and the SDK captures all base64 images. If you set "discardBase64", its value serves as a threshold. 0 discards everything. You can set discardBase64 to other values, such as 20,000. In this case, base64 image capturing is discarded if the length of image src string exceeds 20,000. |
captureDynamicStyles | Set this to true to capture styles created with the CSSOM at the DOM level. If captureShadowDOM is enabled, the CSSOM for shadows will also be captured. |
captureHREFStyles | Set this to true to capture all CSS static files at the DOM level. This is only recommended for debugging purposes or when the proxy server can't access the static CSS files. |
Note:
The capture of Dynamic styles relies on the CSS OM to track changes to the style sheets. CSS OM is currently not supported in Safari/WebKit. To add support for the CSS OM, you must add a polyfill to your web application. This is an example of a polyfill to add the support for the CSS OM https://www.npmjs.com/package/construct-style-sheets-polyfill.
Browser service configuration
Through the Browser service configuration, you can specify browser objects and elements that have dynamic or duplicate HTML IDs.
browser: {
/**
* useCapture is a boolean flag to indicate if the event capture phase
* should be used on browsers that support event capture. This flag
* is enabled by default.
*
* If disabled or the browser does not support event capture then
* event bubbling will be used. Event bubbling could cause some events
* to be missed if the application is preventing them from bubbling.
*
* For additional details on event capture and bubbling refer to the
* W3C DOM specification at:
* http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-flow
* @type {Boolean}
*/
useCapture: true,
/**
* To specify elements whose HTML ids cannot be used as identifiers
* or in xPath generation. Could be a string object with one or two
* properties, "regex" (mandatory) and "flags". These are specified
* as strings. The regex that is evaluated against the node id.
* @type {Array}
* @optional
*/
blacklist: [
"duplicateid", {
regex: "/password|pass|pin|tan/",
flags: "gi"
}
],
/**
* If the application uses custom attributes as an ID replacement,
* you may specify the attribute name here.
* @type {Array}
* @optional
*/
customid: ["name", "custom-attribute"],
normalizeTargetToParentLink: true,
logAttributes: [
"attr1",
"attr2",
"attr3",
"attr4",
"attr5",
]
},
blacklist | You can optionally specify a set of document elements whose HTML IDs are not guaranteed to be static or unique. These HTML IDs of these blacklisted objects are not used to identify the elements and alternate mechanisms, such as a customid (if configured) or an xpath. |
customid | If your web application uses a custom attribute that can be used to uniquely identify the elements, you can specify the attribute name here. |
normalizeTargetToParentLink | By default the Web SDK uses the link element that encapsulates the target of the event. If set to false, the Web SDK uses the actual target element instead. For example, consider the following HTML source:
By default, clicking on the image will cause the Web SDK to log the link element "logo_link" as the target of the click. When this property is set to false, clicking on the image causes the Web SDK to log the image element “logo_image” as the target of the click. |
logAttributes | An optional list of target element attributes to be logged in type 4 or type 9 message. There is no limit to the number of attributes specified in the configuration. However, logging is limited to a maximum of 5 attributes per target element. Additionally, each attribute value is restricted to a maximum of 60 characters. Attribute values exceeding 60 characters will be truncated. |
Modules configuration object
The Modules configuration object contains options that are used by individual modules that are enabled in the Tealeaf Web SDK.
For details about the Modules configuration object, check out these sections:
- Overstat module configuration
- Performance module configuration
- Replay module configuration
- TLCookie module configuration
Overstat module configuration
The following example shows the Overstat module options that are in the defaultconfiguration.js file. The Overstat module options can also be configured through the Configuration wizard.
overstat: {
hoverThreshold: 1000
},
Performance module configuration
The Performance module options can also be configured through the Configuration wizard. The Performance module options correspond to the available options of the W3C navigation timing specification. For more information about the W3C navigation timing specification, see http://www.w3.org/TR/navigation-timing/#sec-navigation-timing-interface.
Property | Description |
---|---|
calculateRenderTime | If enabled, the render time is calculated on browsers that do not support the W3C navigation timing interface. For the calculated render time to be accurate, the library should be statically included at the top of the page in the HEAD section. |
renderTimeThreshold | The threshold in milliseconds that render time is capped. This prevents outlier values from impacting the render time reports. |
delay | Optional delay in milliseconds that specifies how long to wait after page load before logging the type 7 performance message. |
performanceAlert | Enables performance alert (type 17) messages. Disabled by default. To enable, add the performanceAlert setting to the Performance module. |
The following example shows the Performance module options that are in the defaultconfiguration.js file.
modules: {
performance: {
calculateRenderTime: true,
renderTimeThreshold: 600000,
},
Performance Alert
Performance Alert messages are disabled by default. To enable Performance Alert messages, add the performanceAlert
setting to the Performance module.
When enabled, the Web SDK will also log any mixed content violations for the page. The total number of violations is logged on page unload in a type 20 Mixed Content violations message.
Note:
Performance Alerts are supported on the following browsers: Chrome 52+, Firefox 57+, Opera 39+, Safari 11+
Property name | Data type | Description |
---|---|---|
enabled | Boolean | Required. False by default. |
threshold | Number | Optional. Capture data if the resources loading time exceeds threshold. Threshold is measured in milliseconds. The recommended value is 1000 (1 second).Note: Setting a small value for threshold or a large value for maxAlert will result in a large number of performance messages. |
maxAlert | Integer | Optional. Set the maximum number of alerts to be logged. The recommended value is 40.Note: Setting a small value for threshold or a large value for maxAlert will result in a large number of performance messages. |
resourceTypes | String Array | Optional. Specify the resource type to monitor. For example, ["script", "img"]. Monitors all resources, by default. |
blacklist | String Array or Regex Object Array | Optional. Used to blacklist specific resources by specifying the resource name (url). For example, ["sdk"]. |
modules: {
performance: {
performanceAlert: {
/* required
* boolean
*/
enabled: true,
/* optional
* measured in ms
* capture the data if resources loading time exceeds threshold
*/
threshold:3000,
/* optional
* an integer number
* set the maximum number of alerts to be logged
*/
maxAlerts: 400,
/* optional
* array of strings
* specify the resource type to monitor, monitor all resources by default
* possible values are "script", "link", "img", "xmlhttprequest", "iframe", etc
*/
resourceTypes: ["script", "img"],
/* optional
* array of a string or regex object
* used to blacklist certain resources by matching the resource name (url)
*/
blacklist: [{regex: "collector"}, {regex: "tealeaf"}, {regex: "tlt-worker"}, {regex: "bam\\.nr"}]
}
...
}
...
}
Replay module configuration
The following example shows the Replay module options that are in the defaultconfiguration.js file. The Replay module options can also be configured through the Configuration wizard.
replay: {
// DOM Capture configuration
domCapture: {
/**
* NOTE: Enabling DOM Capture has significant implications
* on data transmission and infrastructure.
* Hence this feature should be enabled judiciously. If
* enabled, it requires further configuration
* to only perform the DOM Capture based on specific events and
* elements. Please refer to the
* documentation for more details.
*/
enabled: false,
/**
* The rules for triggering DOM Snapshots are similar to the
* Privacy configuration.
* It accepts a mandatory "event" followed by one or more
* optional targets
* as well as an optional delay after which to take the
* DOM snapshot.
*
* The default configuration below will capture a full DOM
* snapshot for each and every click, change
* action as well as for all screenview load and unloads.
* Please refer to the documentation for
* details on fine tuning this configuration to specific
* elements and screenviews.
*/
triggers: [
{
event: "click"
},
{
event: "change"
},
{
{ event: "load", delayUntil: { selector: ".page-picker-spinner", exists: false, timeout:10000 }, fullDOMCapture:true}
}
],
}
}
Disable DOM capture for specific screenviews
You can use the Screenview blacklist option to disable DOM capture for specific screenviews. Define rules in the blacklist that identify web page screenviews that you want blacklisted. A rule can be a string (exact match) or an object of regular expression (match by regex). The rules are used to compare with the web page's screenview name, which is "path + hash". For example, the screenview name of "www.abc.com/xx/yy#zz" will be "/xx/yy#zz".
If a match is found, Web SDK does not take a dom capture of the screenview. To disable this feature, simply remove the definition of "screenviewBlacklist".
replay: {
domCapture: {
enabled: true,
screenviewBlacklist:[
"/some/url",
{
regex: "somerRegEx", //JS Regex pattern
flags: "someFlag" //Optional JS Regex flags
}, ...
],
triggers: [{
event: "load"
}, ...
]
}
}
Screenview loads are associated with the URL fragment for page loads with #fragment appended to the URL
By default, the initial screenview name is derived from the URL hash fragment (location.hash). If you set the forceRootScreenview option to true, the Web SDK will always log the initial screenview as "root" irrespective of the location.hash value.
TLCookie module configuration
The TLCookie module records the application cookies in the Tealeaf session. For information, see type 14 JSON message schema. The TLCookie module is required for Acoustic Tealeaf on Cloud environments.
TLTSID (Session ID)
The TLTSID is a cookie used to identify a visitor session uniquely. The session identifier is a random 32-character alphanumeric string stored in the TLTSID cookie by default. You can store the session identifier in local storage instead of the TLTSID cookie by setting the sessionIDUsesStorage property to true. The Web SDK defaults to using cookies if local storage is unavailable. To prevent the Web SDK from storing the session identifier in cookies, set the sessionIDUsesCookie property to false. Available options and the corresponding Web SDK behavior are summarized in the table below.By default, the session identifier is a random 32-character alphanumeric string stored in the TLTSID cookie. By setting the sessionIDUsesStorage property to true, the session identifier is stored using local storage instead of cookies. The Web SDK defaults to using cookies if local storage is unavailable. To prevent the Web SDK from storing the session identifier in cookies, set the sessionIDUsesCookie property to false. Available options and the corresponding Web SDK behavior are summarized in the table below.
Impact of Incognito and Private browsing modes
Browser implementation of storage and cookies in incognito or private browsing modes varies across vendors. Browsers continue to evolve their respective implementations based on market and legal requirements. The Web SDK will always respect the browser's implementation for cookies and storage in incognito or private browsing modes. Unfortunately, using these browsing modes can cause browser tabs to be split across multiple Tealeaf sessions even though each tab is simultaneously browsing the same site. This impact is more likely to occur if the
sessionIDUsesStorage
property is enabled. For additional information, refer to the browser documentation on storage and cookie behavior in incognito or private browsing mode.
sessionIDUsesStorage | sessionIDUsesCookie | Web SDK behavior |
---|---|---|
Not specified (default) | Not specified (default) | TLTSID in cookie only. |
Not specified (default) | true | TLTSID in cookie only. |
false | true | TLTSID in cookie only. |
false | Not specified (default) | TLTSID in cookie only. |
true | Not specified (default) | TLTSID in storage with fallback to cookie. |
true | true | TLTSID in storage with fallback to cookie. |
true | false | TLTSID in storage only. |
Not specified (default) | false | NO SESSION ID* |
false | false | NO SESSION ID* |
The session identifier can be stored in the WCXSID cookie for applications integrated with multiple Acoustic offerings. The Web SDK allows the WCXSID session identifier to supersede any TLTSID setting in the TLCookie module, thus ensuring Tealeaf uses the same common session identifier established for all Acoustic offerings.
The following example shows the TLCookie module options in the defaultconfiguration.js file. The TLCookie module options can also be configured through the Configuration wizard.
TLCookie: {
/**
* Comma separated whitelist of cookie names (strings) or regular
* expressions (objects). The specified application cookies will
* be recorded on each screenview load. No application cookies
* will be recorded if this list is undefined or empty.
*/
appCookieWhitelist: [{
regex: ".*"
}
],
/**
* Copy and paste the TL SaaS application key.
*/
tlAppKey: ""
}
Securing the TLTSID cookie
By default, the TLTSID cookie that the Web SDK creates is not secure, thus ensuring Tealeaf can correctly sessionize data from secure (HTTPS) and regular (HTTP) pages into a single session. For HTTPS-only applications, Web SDK can be configured to create TLTSID as a secure cookie. You can configure this by setting the secureTLTSID property to true in the configuration.
Note:
If the secureTLTSID property is set to true, Tealeaf cannot correctly sessionize data from regular (HTTP) pages or from pages where the domain is an IP address. DO NOT enable this setting for applications with mixed HTTP and HTTPS pages.
TLCookie: {
secureTLTSID: true,
...
}
Overriding the samesite=Strict
setting
samesite=Strict
settingBy default, the TLTSID cookie created by the Web SDK has the samesite
property set to Strict
. Depending on application needs, you can override this setting. The following example instructs the Web SDK to set the samesite
property of the TLTSID cookie to None
.
TLCookie: {
secureTLTSID: true,
samesite: "None",
...
}
Check7UIC7Cookie7Configuration77 session id
If the Web SDK is unable to create or retrieve the session identifier in the browser, it sends a special value of Check7UIC7Cookie7Configuration77
. When this happens, Tealeaf on Cloud will use the Client IP address to generate a unique session identifier.
The most common reasons for the Check7UIC7Cookie7Configuration77
value to be sent are:
- Web SDK is configured to neither use Cookies nor Local Storage for the session id, i.e., the "NO SESSION ID" entries described in the previous table.
- Web SDK is configured only to use Cookies, but the session cookie could not be set due to:
- Browser-specific limits have been reached for cookie creation on the application domain.
- 3rd-party scripts or extensions are preventing the default TLTSID cookie from being created. Specifying a different name for the cookie via the
sessionizationCookieName
configuration property could help to work around such issues. - Cookies are disabled on the browser.
- Web SDK is configured only to use local storage but the storage key could not be created due to:
- Browser-specific limits have been reached for the local storage.
- 3rd party scripts or extensions prevent the default TLTSID key from being created. Specifying a different name for the key via the
sessionizationCookieName
configuration property could help to work around such issues. - Local storage is disabled on the browser.
TLTDID (Device ID)
The TLTDID is a cookie used to identify a visitor's device uniquely. A Device ID, or device identifier, helps distinguish between different devices and associate specific events with them. The device identifier is a unique alphanumeric string stored in the TLTDID cookie by default. You can disable the TLTDID cookie by setting the property disableTLTDID
to true
in the module section for TLCookie.
modules: {
...
TLCookie: {
// Parameterize
appCookieWhitelist: [{ regex: ".*" }],
tlAppKey: "",
disableTLTDID: false
}
...
}
DataLayer module
The dataLayer module logs the application data layer. The data layer is a JavaScript object. It is used to exchange application information with analytics and tag managers. If the application has implemented a data layer object, you can configure the Web SDK to log the data layer. The data layer log is then available in the Tealeaf session for creating events and reports.
Configure the location of the data layer object, as shown in the following example.
modules: {
dataLayer: {
dataObjects: [
{
dataObject: "window.dataLayer",
rules: {
includeEverything: true,
permittedProperties: [],
propertyBlocklist: [],
screenviewBlocklist: [],
filter: [
{
matchProperty: 'event',
matchValue = 'gtm.dom'
}
]
}
}
],
}
}
DataLayer properties
includeEverything
true – Use the value true
to capture the entire dataObject
.
false – Use the value false
when you do not want to capture the dataObject
.
permittedProperties
This property is used to indicate properties to capture from dataObject. For example:
modules: {
dataLayer: {
dataObjects: [
{
dataObject: "window.dataLayer",
rules: {
includeEverything: true,
permittedProperties: ['gtm.uniqueEventId'],
propertyBlocklist: ['event'],
screenviewBlocklist: [],
filter: [
{
matchProperty: 'event',
matchValue = 'gtm.dom'
}
]
}
}
],
}
}
propertyBlocklist
This property is used to block properties to capture from dataObject. For example:
modules: {
dataLayer: {
dataObjects: [
{
dataObject: "window.dataLayer",
rules: {
includeEverything: true,
permittedProperties: [],
propertyBlocklist: ['event'],
screenviewBlocklist: [],
filter: [
{
matchProperty: 'event',
matchValue = 'gtm.dom'
}
]
}
}
],
}
}
screenviewBlocklist
This property is used to block the capture dataObject using the name of the screen view. For example:
modules: {
dataLayer: {
dataObjects: [
{
dataObject: "window.dataLayer",
rules: {
includeEverything: true,
permittedProperties: [],
propertyBlocklist: [],
screenviewBlocklist: ['home','expo'],
filter: [
{
matchProperty: 'event',
matchValue = 'gtm.dom'
}
]
}
}
],
}
}
filter
This property is used to filter dataObject from data which is an array like Google Tag Manager(gtm) data. For example:
modules: {
dataLayer: {
dataObjects: [
{
dataObject: "window.dataLayer",
rules: {
includeEverything: true,
permittedProperties: [],
propertyBlocklist: [],
screenviewBlocklist: [],
filter: [
{
matchProperty: 'event',
matchValue = 'gtm.dom'
}
]
}
}
],
}
}
DataLayer configuration examples
Example datalayer
[
{event: 'gtm.dom', gtm.uniqueEventId: 17},
{0: 'set', 1: 'url_passthrough', 2: false},
{"0":"set","1":{"user_id":"","page_path":"","page_title":"","page_location":"https://fakestore.com/us/cart"}},
{"0":"event",
"1":"view_cart",
"2":{"page_title":"SHOPPING CART|CART",
"page_type":"SHOPPING CART",
"market":"US",
"version_info":"global|tenv.prod|ut4.49.202308021007|glass|DF0FD2B",
"url":"https://fakestore.com/us/cart",
"pathname":"/us/cart",
"page_owner":"ECOM",
"send_to":["G-4DGGV4HV95"],
"currency":"USD",
"items":[
{"item_id":"IF72873488",
"item_name":"DAILY MY SHOES",
"item_brand":"ESSEN",
"item_category":"SHOES",
"item_variant":"IF72873488_640",
"price":"65.00",
"currency":"USD",
"quantity":"8"},
{"item_id":"ID462800451",
"item_name":"GAZZZ",
"item_brand":"Y",
"item_category":"SHOES",
"item_variant":"ID462800451_650",
"price":"330.00",
"currency":"USD",
"quantity":"8"},
]
}
}
]
Example scenario 1
If you only want to capture a property named 'event' with the following value 'gtm.dom', see the following example:
Data captured in the Tealeaf session:
{event: 'gtm.dom', gtm.uniqueEventId: 17}
Configuration example 1:
modules: {
dataLayer: {
dataObjects: [
{
dataObject: "window.dataLayer",
rules: {
includeEverything: true,
permittedProperties: [],
propertyBlocklist: [],
screenviewBlocklist: [],
filter: [
{
matchProperty: 'event',
matchValue = 'gtm.dom'
}
]
}
}
],
}
}
Configuration example 2 – Use a regular expression for matchValue
:
modules: {
dataLayer: {
dataObjects: [
{
dataObject: "window.dataLayer",
rules: {
includeEverything: true,
permittedProperties: [],
propertyBlocklist: [],
screenviewBlocklist: [],
filter: [
{
matchProperty: 'event',
matchValue = /gtm/
}
]
}
}
],
}
}
Example scenario 2
If you only want to capture a property named 'event', see the following example:
Data captured in the Tealeaf session:
{event: 'gtm.dom', gtm.uniqueEventId: 17}
dataObject:
{"0":"event",
"1":"view_cart",
"2":{"page_title":"SHOPPING CART|CART",
"page_type":"SHOPPING CART",
"market":"US",
"version_info":"global|tenv.prod|ut4.49.202308021007|glass|DF0FD2B",
"url":"https://fakestore.com/us/cart",
"pathname":"/us/cart",
"page_owner":"ECOM",
"send_to":["G-4DGGV4HV95"],
"currency":"USD",
"items":[
{"item_id":"IF72873488",
"item_name":"DAILY MY SHOES",
"item_brand":"ESSEN",
"item_category":"SHOES",
"item_variant":"IF72873488_640",
"price":"65.00",
"currency":"USD",
"quantity":"8"},
{"item_id":"ID462800451",
"item_name":"GAZZZ",
"item_brand":"Y",
"item_category":"SHOES",
"item_variant":"ID462800451_650",
"price":"330.00",
"currency":"USD",
"quantity":"8"},
]
}
}
Configuration example 1:
modules: {
dataLayer: {
dataObjects: [
{
dataObject: "window.dataLayer",
rules: {
includeEverything: true,
permittedProperties: [],
propertyBlocklist: [],
screenviewBlocklist: [],
filter: [
{
matchProperty: 'event'
}
]
}
}
],
}
}
Configuration example 2 – use a regular expression for matchProperty
:
modules: {
dataLayer: {
dataObjects: [
{
dataObject: "window.dataLayer",
rules: {
includeEverything: true,
permittedProperties: [],
propertyBlocklist: [],
screenviewBlocklist: [],
filter: [
{
matchProperty: /eve/
}
]
}
}
],
}
}
Example scenario 3
Example with multiple objects and filters:
modules: {
dataLayer: {
dataObjects: [
{
dataObject: "window.dataLayer",
rules: {
includeEverything: true,
permittedProperties: [],
propertyBlocklist: [],
screenviewBlocklist: [],
filter: [
{
matchProperty: 'event'
},
{
matchProperty: 'set'
},
]
}
},
{
dataObject: "window.utag",
rules: {
includeEverything: true,
permittedProperties: [],
propertyBlocklist: [],
screenviewBlocklist: [],
}
}
],
}
}
Updated 6 months ago