With the Configuration wizard, you can complete the necessary configuration tasks to modify your IBM Tealeaf UI Capture solution to work with your web application. Through its step-based interface, you configure IBM Tealeaf UI Capture, after which the configuration changes can be applied to the JavaScript in your environment.

Supported browsers

The IBM Tealeaf UI Capture is supported in Chrome and Firefox 17 and later.

Internet Explorer is not supported.

Configuration wizard

Use the Configuration wizard to do a basic configuration for UI Capture. The configuration wizard is only intended as a starting point, and does not provide detailed configuration options to better optimize the installation. For full scale implementations, consult IBM Professional Services or a knowledgeable web developer.

The Configuration wizard is available in the installation package in the Wizard directory.

In the Configuration wizard, you can access context-specific documentation through the Help icon next to available options.

For Release 8.6 and later, you must use UI Capture, the new version of the UI Capture SDK.

Wizard basic configuration options

With the Configuration wizard, you configure the:

  1. Browser service – the service that is used to monitor objects in the browser.
  2. Queue service – the service that is used to store JSON messages locally before they are submitted to the Tealeaf target page for capture and processing.
  3. DOM Capture service – an optional service that takes HTML snapshots of the page according to preconfigured user interaction triggers.
  4. Message service – the message service that is used for privacy settings so that sensitive data detected on the client is blocked or masked before submission to Tealeaf for capture.
  5. Serializer – the built-in parser/serializer used if none is available.
  6. Modules – the modules to enable in your Tealeaf solution.
  7. Miscellaneous settings – specify frames to exclude from data collection and set data sharing options.

Build types

Build types are set with the Configuration wizard. Production versions of the JavaScript are minified, which means:

  • Comments and other non-functional text is removed.
  • Variable names are reduced to the smallest possible files.
  • Overall JavaScript payload is reduced to ease bandwidth requirements.
  • Code is no longer easily read.

This table lists and describes the build types:

Build type Description
Production build (minified) The default setting.
Production build (non-minified) All production build options are applied. However, the JavaScript is not minified, which enables a review of the deployed code.
Development build (non-minified)

Extra debug code is enabled.

This option is primarily for developers or power users of the library who want to debug the code. Do not deploy this type of build in production.

If you are still developing and testing your IBM Tealeaf UI Capture solution, select the Production build (non-minified) build option.

Advanced users

Advanced users can set basic configuration settings without using the Configuration wizard. The Configuration wizard writes setting to the defaultconfiguration.js file. Advanced users can modify the settings in this file. For more information on the file and the configuration components, see UI Capture reference.

Configuration wizard

Use the Configuration wizard to do a basic configuration for UI Capture. The configuration wizard is only intended as a starting point, and does not provide detailed configuration options to better optimize the installation. For full scale implementations, consult IBM Professional Services or a knowledgeable web developer.

Version

The Configuration wizard is available in the installation package in the Wizard directory.

For Release 8.6 and later, you must use UI Capture, the new version of the UI Capture SDK.

Configuration wizard supported browsers

The IBM Tealeaf UI Capture Configuration wizard is supported in Chrome and Firefox 17 and later.

Internet Explorer is not supported.

Configuration wizard controls

When you use the UI Capture Configuration wizard, you complete different actions with these user interface controls.

  • To go to the next screen in the wizard, click Next.
  • To return to the previous screen, click Previous.
  • To complete the configuration, click Finish.
  • To reset the configuration to the defaults provided by Tealeaf, click Reset to defaults.
  • To define and test regular expressions for use in your configuration, click RegEx tester. See RegEx Tester for more information.

In the Configuration wizard, you can access context-specific documentation through the Help icon next to available options.

Browser service configuration

The Browser service is used to monitor objects in the browser. There are two options for Browser service – jQuery or W3C. The jQuery version of the library is recommended for applications that have already been using jQuery 1.7 or above. The W3C version of the library is used for all other applications. The W3C option requires the additional 3rd party library, Sizzle.js for maintaining legacy Internet Explorer compatibility.

You choose either jQuery or W3C. Depending on what you select, you have different options under the Advanced Options section.

Click Help icon in the Configuration wizard for more details on each setting.

jQuery optional settings

The optional settings that you can specify for jQuery include:

  • Use capture phase for event listening – indicates if the event capture phase should be used on browsers that support event capture. The useCapture setting is enabled by default. When disabled or if the browser does not support event capture; then, event bubbling is used. Some events might be missed if the application is preventing the events from bubbling. For more information about event capture and bubbling, see the W3C DOM specification at https://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-flow.
  • jQuery object – the path to the jQuery object.
  • Blacklist elements – one or more element ids that are not unique or dynamically generated. Element IDs that match with any of the blacklisted entries are replaced with custom attribute values or XPATH.
  • Custom attribute ID – one or more attribute names that can be used to uniquely identify an element when its HTML id is not available or blacklisted.
  • Internet Explorer Excluded Links – an array of CSS selectors. For example, the configuration would be specified as ieExcludedLinks: ['a.ignore'], to ignore the beforeunload that is triggered by the link, < a href ='javascript:process();' class='ignore'>Click< /a>.

W3C optional settings

If you have iFrame on your website, any actions within the iFrame on a Legacy IE browser do not bubble up to be captured. This only applies to W3C.

The optional settings that you can specify for W3C include:

  • Use capture phase for event listening – indicates if the event capture phase should be used on browsers that support event capture. The useCapture setting is enabled by default. When disabled or if the browser does not support event capture; then, event bubbling is used. Some events might be missed if the application is preventing the events from bubbling. For more information about event capture and bubbling, see the W3C DOM specification at https://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-flow.
  • Sizzle object – the path to the Sizzle object.
  • Blacklisted elements – one or more element ids that are not unique or dynamically generated. Element ids that match with any of the blacklisted entries are replaced with custom attribute values or XPATH.
  • Custom attribute ID – one or more attribute names that can be used to uniquely identify an element when its HTML id is not available or blacklisted.
  • Internet Explorer Excluded Links – an array of CSS selectors. For example, the configuration would be specified as ieExcludedLinks: ['a.ignore'], to ignore the beforeunload that is triggered by the link, < a href ='javascript:process();' class='ignore'>Click< /a>.
  • For the Internet Explorer Excluded Links option, a CSS selector value results in an exception in Chrome and Webkit browsers, if an invalid character (for example $) is specified, and it is not properly escaped with \.

    Example:

    { 
    //Name Value Blocking 
    "targets": ["input[name=login\\$password]"], 
    "maskType" : 2 //Replace with XXX's
    } 

Queue Service configuration

To minimize the number of network requests between the client and the server, data is buffered in an internal message queue and the queue is flushed periodically. You configure the message queue for data that is used to store JSON messages locally before they are submitted to the IBM Tealeaf target page for capture and processing. You can configure only one queue. You can also enable the encoder service.

Queue Service required configuration settings

When you configure the Queue Services, you configure the Default Endpoint (Target page) with the:

  1. Endpoint name – the name of the endpoint. This queue must be named DEFAULT.
  2. Endpoint (Target Page) – the URL of the target page
  3. Size (Max Messages) – the limit to the number of messages to allow in the queue before it is sent. By default, messages are queued locally in the visitor's browser. When the queue reaches a defined number of messages, the data that is contained in it is serialized and submitted to the IBM Tealeaf target page, which enables Tealeaf to capture and process the messages.
  4. Timer interval – the time period to flush the queue irrespective of the number of messages. Set the time to enable the ability to replay in near real time what the user is doing. This capability is shadow browsing. Otherwise, leave the time at 0 to disable this setting.
  5. Size (Max serialized length) – the threshold for the serialized length of the queue. When the threshold is met or exceeded, the queue is flushed. If this value is 0, the setting is disabled. Because the queue is serialized to compute the size, there might be performance costs when you use this setting.
  6. Check endpoint – when enabled, the configured endpoint is sent a test request after each page load to verify that the service is available. The test request can be identified by the presence of the X-Tealeaf-EndpointCheck HTTP request header. If a timeout occurs, the UI Capture library shuts down and no session data for the page is sent to the endpoint. This feature can be used as a safety check when the endpoint is hosted cross-domain.
    Note: The check endpoint feature should be enabled for use with IBM Tealeaf on Cloud.
  7. Check endpoint timeout – the time, in milliseconds, that the UI Capture library waits for a reply from the endpoint before shutting down. It is recommended to configure a timeout for no more than twice the typical endpoint response time.

Queue Services optional configuration settings

You can configure additional information for the Queue Services:

  1. Enable cross-domain POST messages – Enabling POST requests to be sent to a different server than the parent page.
  2. Enable asynchronous XHR on page unload – Enabling asynchronous request on page unload might result in incomplete or missing data.

Encoder service

The UI Capture library supports an encoder service. The encoder service relies on the "pako" Open Source library that must be included in the application for the encoder service to function. The "pako" Open Source library must be independently downloaded and included on the page before the UI Capture library in order for the Encoder service to function correctly.

When you enable the encoder service, the SDK uses the pako gzip library.

For more information and downloads see the github site:: https://github.com/nodeca/pako.

You can enable the encoder with the Configuration wizard.

You can also manually enable the encoder service in the queue service by editing the defaultconfiguration.js file. Enable the encoder by adding the line encoder: "gzip" to the queue configuration.

Message Service configuration (privacy masking configuration)

You can configure privacy settings so that sensitive data detected on the client is blocked or masked before submission to IBM Tealeaf for capture.

Configuration of privacy through IBM Tealeaf UI Capture ensures that sensitive data never touches IBM Tealeaf.

IBM Tealeaf provides multiple methods for applying privacy throughout the IBM Tealeaf solution.

Click the Help icon in the Configuration wizard for more details on each setting.

More details are available in the Reference section. See UI Capture reference.

Privacy masks

In the Configuration wizard, you can configure multiple privacy masks. Each privacy mask configuration has a MaskType and consists of at least one Target. The target includes:

  • an ID
  • an IDTypes
  • a CSS Selector

To remove an individual target from a privacy mask configuration, click Remove Target. To remove an entire privacy mask configuration, click Remove Privacy Configuration.

Empty privacy masks that you add in the Wizard are not added to the configuration file.

The value that you enter for the CSS selector results in an exception in Chrome and Webkit browsers, if an invalid character (for example $) is specified, and it is not properly escaped with \.

Example:

{ 
//Name Value Blocking 
"targets": ["input[name=login\\$password]"], 
"maskType" : 2 //Replace with XXX's 
} 

Password field masking

Password fields can be masked if you use the defaultconfiguration.js and set the input type=password fields. If you use the Configuration Wizard, then the password fields must be masked by explicitly adding the following to the privacy configuration in the defaultconfiguration.js.

                    {
                        targets: [
                            // CSS Selector: All password input fields
                            "input[type=password]"
                        ],
                        "maskType": 3
                    }

Serializer configuration

Modern browsers come equipped with native JSON serializer/parser. Older browsers like Internet Explorer 6, 7, and 8, do not have native JSON support. By default, for older browsers, UIC uses a built-in JSON parser/serializer. With the serializer configuration, you can disable the UIC built-in JSON support and use your own 3rd party JSON handling serializer or parser.

When you add parsers and serializers, you should add:

  • Parsers that contain functions for UI Capture to use (for example, JSON.parse). The first parser is the most important. If UI Capture does not find the first parser, UI Capture tries again, and so on.
  • Serializers that contain functions for UI Capture to use (for example, JSON.stringify). The first serializer is the most important. If UI Capture does not find the first serializer, UI Capture tries again, and so on.

Modules that are enabled with the Configuration wizard

The UI Capture library is the data capture library for various Tealeaf components and features. You can prevent the resource cost of collecting and transmitting data by enabling only the modules that you plan to use in your Tealeaf solution. You can set advanced options for specific modules. You can enable or disable Performance, Replay, and Overstat modules.

Performance module

The Performance module events comply with the W3C standard on navigation timing. The Performance Module parses the W3C Navigation Timing performance object and includes this information as the Performance (Type 7) message in the JSON data stream that is sent back to the Tealeaf capture server. By default, Performance data is not captured because it can affect bandwidth. When you enable the Performance module, you capture all performance data. You can use the Performance Setting Advanced Options to disable the capture of specific data.

For more information about W3C Navigation Timing, go to http://www.w3.org/TR/navigation-timing/.

With the Configuration Wizard, you configure how you want Render Time to be calculated based on what the browser supports and you set the threshold for excluding outlier data:

  • Calculate render time for browsers that do not support W3C Navigation Timing. Select this option to have the Render Time for your page calculated when the page is in a browser that does not support W3C Navigation Timing. If you use this option, to make the calculation as accurate as possible, you must include the tealeaf.js at the top of the page that is being rendered.
  • renderTimeThreshold. Use this option to set a time limit to exclude outliers from the Render Time report. This value is the time, in milliseconds, after which Render Time values are not included in the render time report. If your average Render Time is 2 seconds (2000 milliseconds), you might set this value to 4 seconds (4000 milliseconds) to exclude non-typical data from the report.
When you enable the Performance Module, data is capture for all of these filters:

  • navigationStart
  • unloadEventStart
  • unloadEventEnd
  • redirectStart
  • redirectEnd
  • fetchStart
  • domainLookupStart
  • connectStart
  • connectEnd
  • ssecureConnectionStart
  • requestStart
  • responseStart
  • responseEnd
  • domLoading
  • domINteractive
  • domContentLoadedEventStart
  • domContentLoadedEventEnd
  • domeComplete
  • loadEventStart
  • loadEventEnd

During configuration, you can use the Performance Setting Advanced Options to disable any of these settings or filters.

Performance Render Time calculations

If the browser supports W3C Navigation Time, the Render Time value is the difference between the responseEnd and loadEventStart. If the browser does not support W3C Navigation Timing and you select the Performance Module configuration Calculate option, the Render Time is the difference between UIC load and page load. If the Render Time exceeds the time that you specify for the renderTimeThreshold, then the Render Time is NOT reported in the JSON Performance (Type 7) message. Instead, the value gets reported as "invalidRenderTime".

Replay module

The Replay module enables specific replay events. When you enable the Replay module, you enable:

  • DOM Capture – Use DOM snapshot capture for hybrid applications. You specify:
    • Threshold for snapshots. Any snapshots over this threshold are not sent to the server
    • Whether you want to capture child Frames or iFrames.
    • Whether you want to remove scripts from the captured snapshots.
  • Mobile events – Capture mobile events
  • Screenviews from hashchange
  • Scroll and window size tracking

During configuration, you can use the Replay events Advanced Options to disable any of these events.

Custom Replay events

You can also add custom replay events.

When you add a custom replay event, a CSS selector value results in an exception in Chrome and Webkit browsers, if an invalid character (for example $) is specified, and it is not properly escaped with \.

Example:

{ 
//Name Value Blocking 
"targets": ["input[name=login\\$password]"], 
"maskType" : 2 //Replace with XXX's 
} 

DOM Capture and DOM Diff Capture

DOM capture is part of the Replay module. It has its own page of options in the Configuration wizard. When you enable DOM Capture snapshot, you specify:

  • Threshold for snapshots. Any snapshots over this threshold are not sent to the server
  • Default events to trigger DOM Captures.
  • Custom events to trigger DOM Captures, if you defined the event to be captured by the replay module.
  • Whether you want to capture child Frames or iFrames.
  • Whether you want to remove scripts from the captured snapshots.
  • Whether you want to enable DOM Diff. The default for this is enabled.
  • Threshold for DOM Diff mutations. Performance can be negatively impacted if a high number of DOM Diff mutations occur within an application. If the threshold is exceeded, the capture method reverts to full DOM Capture.

The DOM Diff service captures and processes the changes in a screenview that occur when a user interacts with a page. Processing the changes is often faster than performing a full DOM capture of a page on each user interaction.

For example, on a page that dynamically displays content in response to the user interaction by toggling the CSS properties of the elements, only the CSS style attribute changes are captured as part of the DOM Diff enabled capture. Without DOM Diff enabled, the entire HTML content of the page would be captured.

Depending on the application, there could be a high number of DOM differences to capture. Processing all of the DOM differences into one capture can decrease application performance. The number of mutations that were processed by the UI Capture SDK are indicated in the mutationCount property of the type 12 DOM Capture message. It is recommended to set a threshold for the maximum number of DOM Diff mutations to capture. If the threshold is exceeded, the UI Capture SDK ignores the DOM mutations and performs a full DOM Capture for the page. When the UI Capture SDK reverts to the full DOM Capture, the forced property is added to the type 12 DOM Capture message. The UI Capture SDK automatically switches back to capturing DOM Diffs for subsequent triggers.

You can monitor your application performance and adjust the settings for your environment. If you find that a page continuously has a high number of mutations and often exceeds the threshold, you can disable the DOM Diff feature for the page and use full DOM Capture.

Overstat module

Overstat is the usability analysis components of the Tealeaf products. You must have a license for the Overstat module. This module provides data for usability analysis.

Tealeaf Cookie module

For Tealeaf SaaS there are two ways to do sessionization. You can use the Tealeaf Cookie module to use Tealeaf cookies. If you use Tealeaf cookies, you specify the cookie name and the Tealeaf App Key. Coordinate with the Tealeaf SaaS administrator for how sessionization is done for your application and for the Tealeaf App Key.

Geolocation

Geolocation is also configured as part of the Replay module. When you enable Geolocation, you enable capturing the device's geolocation information. Data is captured only if the user gives the application permission to use geolocation data. If the user does not give permission to use geolocation data, no data is captured, even if you enable Geolocation.

Note: The UI Capture library typically tracks geolocation information within the Web application. When geolocation is enabled in a hybrid mobile application, the geolocation tracking feature in the Web application should be disabled and the mobile application should use the native SDK to capture the geolocation information.

Chrome browser has deprecating the support for API getCurrentPosition() and watchPosition() on insecure origins (HTTP URL). To capture geolocation data, you must use secure origins.

Miscellaneous settings

By default, UI Capture monitors frames and iframes from the same domain as that of the frame or iframe parent page. UIC cannot access 3rd party frame or iframes. You can Blacklist frames and iframes so that UI Capture does not try to access them. Blacklisted frames and iframes are excluded from data collection. You can also set Session Data sharing options.

For the Blacklisted Frames option, a CSS selector value results in an exception in Chrome and Webkit browsers, if an invalid character (for example $) is specified, and it is not properly escaped with \.

Example:

{ 
//Name Value Blocking 
"targets": ["input[name=login\\$password]"], 
"maskType" : 2 //Replace with XXX's 
} 


Join The Discussion

Your email address will not be published. Required fields are marked *