The Acoustic Experience Analytics (Tealeaf) UI Capture library configuration is an anonymous JSON object container. The library configuration includes different sections. You modify the defaultconfigurations.js file to set the configuration settings.
- 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.
You can also configure keys for capturing localStorage data.
Core configuration
The core configuration object contains basic information about the DOM events to which the Acoustic Experience Analytics (Tealeaf) UI Capture library listens.
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: { /** * 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" } ] } } }, }, /* 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 ... });
Core
In Core, you define properties to assure capture of UI events.
Note: Do not modify these settings unless directed to do so by Acoustic Experience Analytics (Tealeaf). For more information, contact Acoustic Professional Services.
Internet Explorer links
Clicking some link URLs that use “intent”, “mailto”, “sms”, or “tel” protocols can cause premature unload events. The UIC 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 UI Capture library 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"],
Custom events to trigger logging of load events
The 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, the 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
The modules subsection of the core configuration specifies the events to which each module listens. Do not change the default settings.
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
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 Acoustic Experience Analytics (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
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.
- Acoustic Experience Analytics (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, UI capture must send scroll events. If you configure UI capture 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 Acoustic Experience Analytics (Tealeaf) CX Mobile. For more information, contact your Acoustic Experience Analytics (Tealeaf) representative. |
touchend |
Touch end events for mobile devices. These events are replayed only if you licensed Acoustic Experience Analytics (Tealeaf) CX Mobile. For more information, contact your Acoustic Experience Analytics (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. |
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 Acoustic Experience Analytics (Tealeaf) UI Capture library.
Note: When integrating the library with a new application, you typically modify only few of these configuration items.
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 } ] }, 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: { sizzleObject: "window.Sizzle", jQueryObject: "window.jQuery" } },
Queue service configuration
Through the Queue service configuration, you can add extra event queues for processing and configure event queue properties that are based on traffic volume.
Note: Adding an extra queue is an advanced option and is not required in most deployments.
Property | Description |
---|---|
asyncReqOnUnload |
Enables asynchronous XHR on page unload. Warning: Enabling this option may result in incomplete or missing data. |
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 to which messages are sent. This value corresponds to an Acoustic Tealeaf target page identifier. Sample targets for JSP and PHP environments are provided with the UI Capture distribution. |
maxEvents |
The maximum number of events in a queue. If this number of events is exceeded, the queue is automatically flushed, and all queued events are sent to the target for capture by Acoustic Tealeaf. Note: Adjust the maximum number of events to a reasonable value, typically between 20 to 50. The maximum allowed value is 100. |
timerInterval |
The user inactivity interval in milliseconds after which message queues are flushed automatically. 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 Acoustic Experience Analytics (Tealeaf) users are shadow-browsing a visitor's session. |
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 Acoustic Experience Analytics (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. Synchronous requests will continue to use XHR or Beacon as appropriate. |
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.
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 } }
For property descriptions, see the following table.
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. |
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, /** * sizzleObject is the location of the Sizzle object on the page. If * this setting is not specified, it is assumed that the Sizzle object * will be in the global scope. i.e. window.Sizzle * * This setting is only valid when the W3C flavor of the browser * service is selected. * * @type {String} * @optional (only needed for W3C browserService and if jQuery * is not defined) */ sizzleObject: "My.location.Sizzle", /** * jQueryObject is the location of the jQuery object on the page. If * this setting is not specified, it is assumed that the jQuery object * will be in the global scope. i.e. window.jQuery * * @type {String} * @optional (only needed if jQuery is not defined on the window) */ jQueryObject: "My.location.jQuery", /** * 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: [ "mycustomid" ] },
Property | Description |
---|---|
sizzleObject |
This library is used by the W3C flavor of the library to evaluate CSS selectors on older browswers, such as IE7, that do not have native support for CSS selector based querys. Note: This configuration item is needed only for the W3C browser service and if jQuery or Sizzle is not defined on the window object of your web application. Sizzle is included in jQuery by default so if the application has jQuery, the separate include of Sizzle might not be required.
|
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 UIC uses the link element that encapsulates the target of the event. If set to false, the UIC uses the actual target element instead. For example, consider the following HTML source:
<a id="logo_link" href="/"><img id="logo_image" src="logo.png" /></a> By default, clicking on the image will cause the UIC 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 UIC to log the image element “logo_image” as the target of the click. |
Message service configuration
You use the Message service configuration to define options such as privacy rules applied to the JSON messages submitted to the Acoustic Experience Analytics (Tealeaf) server for capture.
message: { /** * Define privacy rules to modify 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 of * a custom function that must be specified as * maskFunction. * @type {Number} */ maskType: 3 }, { targets: [ { id: "[[\"HTML\",0],[\"BODY\",0],[\"SELECT\",0]]", idType: -2 } ], maskType: 4, /** * A custom mask function that replaces the reported value * by its return value ("masked", in this example) * @param {String} value The value to replace. * @return {String} Could return any string. */ maskFunction: function (value) { return "masked"; } } ] } },
Privacy configuration for UI Capture
Acoustic Experience Analytics (Tealeaf) UI Capture enables the blocking and masking of sensitive information within the client browser before the data is forwarded to Acoustic Experience Analytics (Tealeaf) for capture, while it allows the data to be forwarded to your web servers for normal processing. Sensitive data that was cleansed through UI Capture never reaches Acoustic Experience Analytics (Tealeaf), which ensures that your customer's interactions are secure in UI Capture.
- UI Capture 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 UI Capture, see Privacy masking and blocking sensitive data. Additionally, you can contact Acoustic Experience Analytics (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: { privacy: [ { targets: [ { id: { regex: ".+_pii$" }, idType: -1 }, ], "maskType": 3 } ] } |
idType |
The type of identifier. The following types are supported: Note: Values for idType are recorded as negative numbers.
|
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
Acoustic Experience Analytics (Tealeaf) UI Capture 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:
|
"HelloWorld123" | "XxxxxXxxxx999" |
4 |
Custom function Note: A masking function must be defined as maskFunction. |
"HelloWorld123" | Defined on the defined function |
Enabling shadow DOM cache
If you need to reduce the traffic size to the collector, you can enable shadow DOM cache. Shadow DOM cache is disabled by default.
When this cache is enabled, the SDK caches the captured shadow DOM and uses cacheid to replace the DOM content in type-12 messages, if the same shadow DOM content needs to be sent for a second time.
To enable this cache, add following configuration.
services: { ... message: { shadowDomCacheEnabled: true, ... } ... }
Serializer service configuration
Through the Serializer service configuration, you can specify which JSON parser and serializer functionality to use.
The library uses JSON as its message format. All modern browsers have built-in support for serializing and parsing JSON. However, legacy browsers (for example, 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 UI Capture library 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.
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: { sizzleObject: "window.Sizzle", jQueryObject: "window.jQuery" } },
Modules configuration object
The Modules configuration object contains options that are used by individual modules that are enabled in the Acoustic Experience Analytics (Tealeaf) UI Capture library.
Performance
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, filter: { navigationStart: true, unloadEventStart: true, unloadEventEnd: true, redirectStart: true, redirectEnd: true, fetchStart: true, domainLookupStart: true, domainLookupEnd: true, connectStart: true, connectEnd: true, secureConnectionStart: true, responseStart: true, domLoading: true, domContentLoadedEventStart: true, domContentLoadedEventEnd: true, domComplete: true, loadEventEnd: true } },
Filter
You use the filters available in the Performance section to configure the Performance-related events in the client to monitor by UI Capture. The list of provided metrics that you can filter out is pre-defined by the W3C navigation timing specification.
For more information, visit http://www.w3c.org.
By default, performance timing data that is required for Tealeaf functionality and reporting (e.g. loadEventStart) is excluded from filtering.
Note: When an individual filter is enabled, performance data that is related to that property is not captured by UI Capture.
To enable tracking of any performance property, set its value to false.
Performance Alert
Performance Alert messages are disabled by default. To enable Performance Alert messages, add the performanceAlert
setting to the Performance module.
Supported browsers: Chrome 52+,Firefox 57+, Opera 39+, Safari 11+
Property name | Data type | Description |
---|---|---|
enabled |
Boolean | Required. False by default. |
threshold |
Number | Required. Threshold is measured in milliseconds. For example “2000”. Capture data if the resource loading time exceeds the threshold. |
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”]. |
performanceAlert
modules: { performance: { performanceAlert: { /* required * boolean */ enabled: true, /* required * measured in ms * capture the data if resources loading time exceeds threshold */ threshold: 2000, /* 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: ["sdk"] } ... } ... }
Replay events
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" }, { event: "unload" } ], } }
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, the 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 UIC will always log the initial screenview as “root” irrespective of the location.hash value.
Overstat
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 },
Configuring the TLCookie module
The TLCookie module is used to record the application cookies in the Tealeaf session. For information, see type 14 JSON message schema. Additionally, the TLCookie module manages the application key and session identifier that are used to uniquely identify a visitor session. The TLCookie module is required for Acoustic Tealeaf on Cloud environments.
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. If local storage is not available, the UIC defaults to using cookies. To prevent the UIC from storing the session identifier in cookies, set the sessionIDUsesCookie property to false. Available options are summarized in the table.
sessionIDUsesStorage | sessionIDUsesCookie | UIC behavior | |
---|---|---|---|
Not specified (default) | Not specified (default) | TLTSID in cookie only. | |
Not specified (default) | true | ||
false | true | ||
false | Not specified (default) | ||
true | Not specified (default) | TLTSID in storage with fallback to cookie. | |
true | true | ||
true | false | TLTSID in storage only. | |
Not specified (default) | false | NO SESSION ID | |
false | false |
For applications that are integrated with multiple Acoustic offerings, the session identifier can be stored in the WCXSID cookie. In this case, the UIC allows the WCXSID session identifier to supersede any TLTSID setting in the TLCookie module. This ensures Tealeaf uses the same common session identifier established for all Acoustic offerings.
The following example shows the TLCookie module options that are 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 is created by the UIC is not a secure cookie. This ensures Tealeaf can correctly sessionize data from both secure (https) and regular (http) pages into a single session. For https-only applications, UIC can be configured to create TLTSID as a secure cookie. This is done by setting the secureTLTSID property to true in the configuration.
NOTE: If this property is set, Tealeaf cannot correctly sessionize data from regular (http) pages. DO NOT enable this setting for applications with mixed http and https pages.
TLCookie: { secureTLTSID: true, ... }