IBM Tealeaf Version 5 Release 0.0 September 18, UI Capture Guide IBM

IBM Tealeaf Version 5 Release 0.0 September 18, 2015 UI Capture Guide IBM Note Before using this information and the product it supports, read the...
Author: Malcolm Collins
41 downloads 0 Views 2MB Size
IBM Tealeaf Version 5 Release 0.0 September 18, 2015

UI Capture Guide

IBM

Note Before using this information and the product it supports, read the information in “Notices” on page 151.

This edition applies to version 4, release 0, modification 0 of IBM Tealeaf UI Capture and to all subsequent releases and modifications until otherwise indicated in new editions. © Copyright IBM Corporation 1999, 2015. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents IBM Tealeaf UI Capture Guide . . . ..

v

Chapter 1. IBM Tealeaf CX UI CaptureJ2

1

Working with use cases . . . . . . . . . .. Validating use cases with Client-Side Capture . .. System prerequisites . . . . . . . . . . .. Supported Browsers . . . . . . . . . . .. How UI Capture for replay works . . . . . .. How UI Capture captures interactions . . . .. How UI Capture replays captured interactions .. Capture and Replay Features . . . . . . . .. Gestures configuration . . . . . . . . .. DOM Capture and Replay . . . . . . .. Hybrid application bridge for Android APIs . .. Accessing native Android methods with JavaScript with Tealeaf customized WebView .. Hybrid application bridge for iOS APIs . . . .. Related documentation . . . . . . . . ..

1 1 2 2 2 3 4 5 5 11 22

Chapter 2. UI Capture installation and implementation . . . . . . . . . .. Install version . . . . . . . . . . . .. Support for CX RealiTea Viewer . . . . .. Support for mobile web application capture .. CX Passive Capture Application configuration . .. Installation and deployment plan . . . . . .. Stage 1: Development environment . . . .. Stage 2: Testing environment . . . . . .. Stage 3: Production environment . . . . .. Configuring the JavaScript . . . . . . . .. UI Capture JavaScript interactions with web application pages . . . . . . . . . .. Block sensitive data fields . . . . . . .. Installation on web pages. . . . . . . . .. Unique HTML IDs . . . . . . . . . .. Cookies. . . . . . . . . . . . . .. Installation on the web server . . . . . . .. References to the JavaScript file. . . . . .. IBM Tealeaf target page . . . . . . . .. Configuration of UI Capture JavaScript . . . .. IIS configuration. . . . . . . . . . .. Non-IIS web server configuration . . . . .. Web page modifications . . . . . . . . .. Change management for Document Object Model elements . . . . . . . . . . . . . .. Upgrade UI Capture . . . . . . . . . .. Support for legacy headers . . . . . . .. Uninstalling UI Capture . . . . . . . . ..

Chapter 3. Configure UI Capture basic settings . . . . . . . . . . . . .. Configuration wizard . . . . . Browser service configuration . Services configuration . . . . © Copyright IBM Corp. 1999, 2015

. . .

. . .

. . .

. . .

.. .. ..

26 27 31

33 33 33 33 33 34 34 35 38 39 39 39 40 40 40 40 40 41 43 44 44 44 44 45 45 46

47 48 49 50

Message Service configuration (privacy masking configuration) . . . . . . . . . . .. Serializer configuration . . . . . . . .. Modules that are enabled with the Configuration wizard . . . . . . . . . . . . . .. Miscellaneous settings . . . . . . . . .. RegEx Tester . . . . . . . . . . . . .. Specifying regular expressions for test data . .. Configuring settings and features with the Configuration wizard . . . . . . . . . .. Capturing gestures in your application . . . .. Configuring DOM Capture and Replay for Hybrid applications . . . . . . . . . . . . .. Configuring DOM Capture and Replay for Native Android applications that cannot use PCA Configuring DOM Capture and Replay for Native iOS applications that cannot use PCA ..

51 52 52 55 55 56 57 63 64 65 66

Chapter 4. UI Capture usage guidelines 69 Application scope . . . . . . . . . . .. Supported application types . . . . . . .. Supported protocols . . . . . . . . .. Before you begin development . . . . . . .. IBM Tealeaf access . . . . . . . . . .. Third-party content . . . . . . . . . .. Personnel . . . . . . . . . . . . .. Development considerations . . . . . . . .. Development cycle . . . . . . . . . .. When to deploy UI Capture during development Development and Test environments . . . .. Performance management . . . . . . .. Application content. . . . . . . . . . .. Unique identifiers . . . . . . . . . .. Do not use Document Object Model keywords as form field names . . . . . . . . . .. Application objects . . . . . . . . . .. Private data . . . . . . . . . . . .. Frequency of posts . . . . . . . . . .. UI events overridden by UI Capture . . . .. UI Capture deployment . . . . . . . . .. Placement of UI Capture . . . . . . . .. JavaScript . . . . . . . . . . . . .. Create custom events . . . . . . . . .. JSON message type schemas and examples . . .. Message header properties . . . . . . .. Message header properties schema . . . .. Message header properties schema . . . .. Client state (Type 1) messages . . . . . .. ScreenView (Type 2) messages . . . . . .. Connections (Type 3) messages . . . . . .. Control (Type 4) messages . . . . . . .. Custom Event (Type 5) messages . . . . .. Exception (Type 6) messages. . . . . . .. Performance (Type 7) messages . . . . . .. Web Storage (Type 8) messages . . . . . ..

69 69 69 70 70 70 70 71 71 71 71 72 72 72 72 73 74 74 74 75 75 75 75 76 77 77 78 78 81 83 84 87 88 89 90

iii

Overstat Hover Event (Type 9) messages Layout (Type 10) messages . . . . . Gesture (Type 11) messages . . . . . DOM Capture (Type 12) messages . . GeoLocation (Type 13) messages . . . Examples . . . . . . . . . . . Next steps . . . . . . . . . . .

. . . . . . .

.. .. .. .. .. .. ..

Chapter 5. UI Capture reference . .. Core configuration. . . . . . . Core . . . . . . . . . . Configure client events by module Services configuration . . . . . Queue service configuration . . Browser service configuration . . Message service configuration . . Serializer service configuration . Modules configuration object . . . Performance . . . . . . . . localStorage configuration . . . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . . . . .

.. .. .. .. .. .. .. .. .. .. ..

Chapter 6. UI Capture Public API Reference . . . . . . . . . . . .. TLT.init(object configObject, /*optional*/ function callbackFunction) . . . . . . . . . . .. TLT.IsInitialized() . . . . . . . . . . .. TLT.rebind(/*optional*/ DOMElement root) . .. TLT.flushAll(void) . . . . . . . . . . .. TLT.setAutoFlush(AutoFlushFlag flag) . . . .. TLT.processDOMEvent(DOMEvent event) . . .. TLT.logCustomEvent(DOMString name, object customMsgObj). . . . . . . . . . . .. TLT.logExceptionEvent(DOMString msg, /*optional*/ DOMString url, /*optional*/ long line) . . . . . . . . . . . . . . .. TLT.logScreenviewLoad(DOMString name, /*optional*/ DOMString referrerName, /*optional*/ DOMElement root) . . . . . .. TLT.logScreenviewUnload(DOMString name) . .. TLT.getSessionData() . . . . . . . . . .. TLT.registerBridgeCallbacks . . . . . . .. TLT.logDOMCapture(/*optional*/ DOMElement root, /*optional*/ object configOptions) . . .. TLT.logScreenCapture . . . . . . . . .. TLT.logGeolocation . . . . . . . . . ..

Chapter 7. UI Capture FAQ. . . . .. Getting started . . . . . . . . . . . .. What is UI Capture ? . . . . . . . . .. What versions of UI Capture are available? .. Why do I need UI Capture ? . . . . . .. How do I implement UI Capture ? . . . .. What is the size of UI Capture ? . . . . .. Can I bundle the UI Capture library with other JavaScripts? . . . . . . . . . . . ..

iv

91 91 94 103 107 108 109

111 111 113 114 117 118 118 120 123 124 126 126

129 129 129 130 130 130 130 131

131

132 132 132 133 134 135 135

Will UI Capture impact the performance or behavior of my website?. . . . . . . .. Where can I get latest version of UI Capture ? What is being captured by UI Capture ? . .. I am having trouble with UI Capture implementation. Where do I get support or help? . . . . . . . . . . . . . .. Using UI Capture . . . . . . . . . . .. How do I configure what is captured by UI Capture ?. . . . . . . . . . . . .. What is captured from mobile web sessions? What if I find a bug with UI Capture ? . . .. How can I create events from UI Capture data? How can I search for UI Capture data? . . .. How do I capture only mouseover events on menu?. . . . . . . . . . . . . .. How do I capture keyup events? . . . . .. How do I report on client-side validation/error messages? . . . . . . . . . . . .. How do I force the sending of queued events? For the first phase, the only desired metric is the Page Render time. Are there configuration settings that limit POSTs to just that event? .. I use DHTML on my checkout form. Is UI Capture going to capture the dynamically rendered DOM elements? . . . . . . .. How do I get render times from UI Capture ? Do I need to have IDs assigned to my DOM elements that I would like to capture? . . .. Can I customize UI Capture JavaScripts? . .. How come I get cross-domain error messages in my browsers debug console related to iFrames on my site? . . . . . . . . . . . .. Upgrading the library . . . . . . . . .. How do I determine which version of the library I am using? . . . . . . . . .. How do I determine which version of the TealeafTarget.jsp file I am using? . . . .. When do I upgrade? . . . . . . . . .. How do I find out about available updates? ..

139 140 140

140 140 140 140 140 141 141 141 141 141 142

142

142 142 143 143

143 144 144 144 144 144

Chapter 8. IBM Tealeaf documentation and help . . . . . . . . . . . .. 145 Appendix A. Cross-domain communication . . . . . . . . ..

147

Appendix B. Variations between jQuery and W3c flavors of UI Capture

149

Notices . . . . . . . . . . . . ..

151

137 137 137 137 137 137 138 139

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Trademarks . . . . . . . Privacy Policy Considerations .

. .

. .

. .

. .

. .

.. ..

152 153

IBM Tealeaf UI Capture Guide For Release 8.6 and later, you must use the IBM Tealeaf UI Capture . The IBM Tealeaf UI Capture Guide details how to deploy the latest version of IBM Tealeaf UI Capture for your JavaScript-based web application. IBM Tealeaf UI Capture enables the monitoring of UI events in the visitor's browser that do not result in a request to the web application and cannot be captured through other means.

© Copyright IBM Corp. 1999, 2015

v

vi

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Chapter 1. IBM Tealeaf CX UI CaptureJ2 The following topic provide an overview of prerequisites, supported browsers, features, and supported APIs.

Working with use cases There are three basic uses for IBM Tealeaf UI Capture . You can also develop use cases specific to your needs. These basic use cases are listed in order of increasing capability and complexity: 1. Capture browser environment information that is not typically transmitted to the web server. This data set includes: v Page render time and associated client-side performance timing measurements, as defined in the W3C Navigation Timing specification. See http://www.w3.org/TR/navigation-timing/. v The screen resolution of the client computer or device. More browser information can be captured through user agent information that is extracted and evaluated through IBM Tealeaf cxImpact. See "Managing User Agents" in the IBM Tealeaf cxImpact Administration Manual. 2. Capture predefined events on the page. IBM Tealeaf can capture your own events, which are described later. 3. Capture user interactions (UI) with the web page. These captures are typically the text that is typed into a form field, interaction with controls such as check boxes, select lists, or links. You can develop your own use cases for IBM Tealeaf UI Capture . Specifically, you identify user activities, error conditions, and success criteria for application use. A robust set of use cases can help with the implementation process and in tracking the results in IBM Tealeaf.

Validating use cases with Client-Side Capture IBM Tealeaf provides the Client-Side Capture utility, which enables the capture of web sessions to the local computer without access to an IBM Tealeaf UI Capture capture deployment. Client-Side Capture (CSC) is useful for capturing use cases in the web application. With CSC, web sessions can be captured and saved to your local computer for later replay in the stand-alone IBM Tealeaf CX RealiTea Viewer application. You can use CSC to visit all application areas and to capture specific workflows. You use this procedure to validate that IBM Tealeaf UI Capture is properly capturing all requisite elements of the application. Note: Use sessions that are captured by CSC to verify that all user interface events are being captured. If UI events are not being captured, check for the following issues. v The web application is squashing these events. Review the application to verify that UI events are not being blocked or otherwise prevented from "bubbling" by the site code.

© Copyright IBM Corp. 1999, 2015

1

v The web application is dynamically updating content on the page. The IBM Tealeaf API must be called by the web application so that UI Capture can attach the appropriate event listeners. See "Using Client-Side Capture for Fiddler" in the IBM Tealeaf Client-Side Capture Manual.

System prerequisites Before you deploy IBM Tealeaf UI Capture , you make required modifications to your web application. 1. Statements to include the IBM Tealeaf JavaScript file must be added to those web pages of interest. 2. A target web page must be added to the origin web servers to acknowledge the POSTs being received from the IBM Tealeaf UI Capture library on the browser. 3. Depending on your web page application, actionable user interface elements, such as form fields, buttons, and tags, must be assigned unique HTML IDs to support later replay through IBM Tealeaf. 4. Any Ajax requests from JavaScripts running on the web page must have at least one unique data item so that multiple requests can be differentiated.

Supported Browsers Tealeaf®'s UI Capture JavaScript is supported for deployment to the following browsers: v IE 10.0 and later v Firefox 30.0 and later v iOS 7 Mobile Safari and later v Chrome 30 and later For replay, the IBM Tealeaf CX RealiTea Viewer uses an embedded instance of the version of Internet Explorer that is installed on the local machine. Replay of Tealeaf sessions in IBM Tealeaf CX RealiTea Viewer (RTV), the stand-alone application for desktop replay, requires Internet Explorer support. If Internet Explorer is not supported by your enterprise's IT department, basic replay can be managed through the browser. Creation of events that monitor JSON-based data that is submitted from IBM Tealeaf CX UI Capture for AJAX or IBM Tealeaf UI Capture is not supported in IBM Tealeaf CX RealiTea Viewer. You must use Browser-Based Replay to create events from these versions of UI Capture.

How UI Capture for replay works Of the three basic use cases for IBM Tealeaf UI Capture , capturing UI interactions with the web page for later replay is the most complex. The following diagram shows this use case.

2

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Figure 1. UI capture and replay

Suppose that you are attempting to capture a JavaScript, DHTML, or Ajax web page. Before the inclusion of the UI Capture library, a visit to the page instructs the web server to return the page that contains the HTML/DHTML/JavaScript needed for the page functionality. As the user has interactions in the page, such as entering data on the form, the Ajax code on the page processes that data as designed. v The web page can use Ajax techniques to post requests for data to the web server, which responds with the needed data. Thus, the page can be updated without causing a new page to load. v When the user marks a check box, another Ajax interaction with the web server is triggered. v The user can take an action that causes the current page to "unload", likely to be replaced by another web page. All these Request/Responses are captured by the IBM Tealeaf CX Passive Capture Application. During replay, IBM Tealeaf can often infer which forms were filled out and can bind the Ajax responses to Ajax requests made during replay. However, without the UI Capture library, IBM Tealeaf has no visibility into the interactions between the web page application and the visitor when the interaction did not trigger data transmission from the web server.

How UI Capture captures interactions After the UI Capture library is added to the web page, the library code can detect UI events that occur on different elements in the page's Document Object Model (DOM). UI Capture can capture events from all frames or iframes that share the same domain as the parent page. For example, when the user enters text into a field, the library code sees each key press event for the field and the actual key value, such as the letter A. The library stores these events into a temporary JSON data structure for eventual transmission back to the web server. The library can be configured to send this captured data up to the web server according to the following conditions: v At predefined time intervals. Chapter 1. IBM Tealeaf CX UI CaptureJ2

3

v When a predefined number of events were captured. v At page unload time, usually defined as the minimum condition. Each time the UI Capture JavaScript software posts data to the web server, the IBM Tealeaf application on the web server acknowledges receipt of the data. This response is also captured by the IBM Tealeaf CX Passive Capture Application server, so the request/response pair can be accurately recorded.

Figure 2. Ajax and UI Capture transactions

This diagram shows the interactions of the example web page with the web server over time, including the web page Ajax transactions and the web pages added by UI Capture . In this sequence diagram, the web page application made two Ajax transactions followed by two IBM Tealeaf Ajax transactions. Time increases from top to bottom. Note: For each user action, the UI Capture solution submits a single message. For more information about web page interactions, see Chapter 2, “UI Capture installation and implementation,” on page 33.

How UI Capture replays captured interactions To replay a web page, the IBM Tealeaf replay software mimics the interactions between the browser and visitor and between the browser and the web server. These interactions are shown in the following diagram.

4

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Figure 3. Replay scenario

The IBM Tealeaf replay software loads the captured page. When the page requests the UI Capture JavaScript file, the replay software provides a different set of files, which are designed for replay. The replay software then directly updates the state of the different objects on the page that is based on the visitor's actions. The IBM Tealeaf user can see these updates that occur at replay speed. Updates can cause the JavaScript on the page to run, which results in the Ajax POSTs being sent to the server. This request is trapped and mapped to the previously captured request and response. The latter is sent to the browser, so the JavaScript running on the page can do the same actions that occurred at capture time. For replay to correctly map the new Ajax request to the previously captured one, a unique identifier for the post that is consistent between the captured instance and the replayed instance must be present. You can configure mapping rules so that request variables can be ignored or used to match to the captured request correctly.

Capture and Replay Features You can capture information in your application for replay. You can capture the gestures that a user makes on your page. You also have the option of using PCA or DOM to capture your pages.

Gestures configuration If you want to use gestures in your application, you include the gestures module in your application with the defaultconfiguration.js file and download and include hammer.js in your application. If you want, you can configure Options for your gestures.

Chapter 1. IBM Tealeaf CX UI CaptureJ2

5

hammer.js library UI Capture uses the hammer.js library to enable gesture capture. The hammer.js library is packaged with Tealeaf in the folder with the other 3rd party libraries that Tealeaf uses.You must include the hammer.js library.

hammer.js limitations hammer.js does not support Internet Explorer 8. If your customer base is using Internet Explorer 8, do not load hammer.js. hammer.js depends on touch events in the browser to work. Touch events are canceled in chrome = TMS. 3) From the Worldview tab, expand the twistie so that you can see all of the nodes in the server view. 4) Expand the Transport Service node. 5) Scroll to the Transport Service configuration and select it. The Config Info panel for the Transport service is displayed. 6) In the Config Actions section of the panel, select View/Edit. The Pipeline Editor - Transport Service Configuration window is displayed. 7) In the Available Session Agents panel, locate DOMCaptureVHit and select it. 8) With DOMCaptureVHit selected, drag it to the panel on the left and drop it between the Inflate and PrivacyEX session agents. The Edit Session Agent dialog is displayed. 9) In the Edit Session Agent dialog, select Add Config Items and select the DownStreamConfigSection check box. 10) Click OK. 11) Click OK again. You created and configured the DOM Capture Virtual Hit Session Agent by using the Tealeaf Management System (TMS). b. Enable the Replay server to play captured DOM data: 1) Log in to the Tealeaf Portal as an administrator. 2) From the menu bar, select Tealeaf > TMS. 3) From the Worldview tab, expand the twistie so that you can see all of the nodes in the server view. 4) Expand the Replay Server node and select the server on which to enable DOM capture. 5) In the Config Actions section of the panel, select View/Edit. The Replay Server Configuration window is displayed. 6) Locate the property that is named EnbableDomCapture and select it. 7) In the Edit Config Item window, set a value of 1 and click Apply You enabled the Replay of captured DOM or DOM Diff data on the server. c. Consider changing the byte size of the Canister Safety Limits [BB] Event. When DOM Capture is enabled, you will likely need to increase the byte size specified in the Bytes section of the Canister Safety Limits [BB] Event. The Canister Safety Limits [BB] event closes the session if the session is too long, too large, or has too many hits. Because DOM Capture can incur

20

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

additional processing and network transmission cost, you might need to increase the byte size to accommodate these costs and to prevent the session from splitting too early. The amount by which to increase the byte size varies depending on the website and on how DOM capture is utilized. Consult Tealeaf Professional Services for advice about increasing the byte size of the Canister Safety Limits [BB] Event. To increase the byte size specified in the Bytes section of the Canister Safety Limits [BB] Event: 1) From the Tealeaf Portal, select Configure > Event Manager 2) From the Filter Events panel, select Tealeaf Standard Events. 3) Sort the list of standard events by name to find the Canister Safety Limits [BB] event in the view area. 4) Right-click the Canister Safety Limits [BB] and select Edit Event. . . . The following figure shows the Canister Safety Limits [BB]. The text in bold indicates the value that needs to be increased if DOM Capture is enabled. Figure 4. Canister Safety Limits [BB] // Canister Safety Limits [BB] function PALI$E_SAFETY_LIMITS() { //Default: 2048 Hits if ($S.NumberOfHits > 2048) TLCloseSession.CloseForSafetyHits(); //Default: 5242880 Bytes (5MB) if (($S.TotalREQBytes + $S.TotalRSPBytes) > 5242880) TLCloseSession.CloseForSafetySize(); //Default: 3600 Seconds (60 minutes) if ($S.TotalTime> 3600) TLCloseSession.CloseForSafetyTime(); }

5) After increasing the default byte size, click Validate Javascript to ensure change is valid. 6) Click Save Draft. 7) Click on the Events tab and click Save Changes to commit the change. 3. Refine the DOM capture triggers on the client side, in your application: a. Use a specific page or control to trigger a DOM capture, for example, when the application user clicks on the Next button: 1) In the Configuration wizard in your application, go to the DOM Capture page. 2) Remove all of the triggers that you are no longer using. 3) Set the Event drop-down to Click. 4) Enter the ID for the control that you want to capture on a user click. 5) Enter the ID type for the control. 6) Enter a delay, in milliseconds, that you want the application to wait before it takes the DOM capture. b. Use a custom event to trigger a DOM capture, for example Login: 1) In the Configuration wizard in your application, go to the Module page. Chapter 1. IBM Tealeaf CX UI CaptureJ2

21

2) Select the Add a Custom Replay Event. 3) Enter the Event name. 4) Enter the Event Target.. 5) Enter the Event State. 6) Select Next to go to the DOM capture page. 7) Remove the triggers that you no longer want to use. 8) Select Add Trigger. 9) Select the custom Event that you created from the Event drop-down. 10) Enter the configuration information. c. Select Finish.

Hybrid application bridge for Android APIs An Android hybrid application is a native application that uses WebView control as part of the UI components. Tealeaf Android SDK provides JavaScript interface APIs integrated with CX UI Capture j2, which can be started from JavaScript functions to access native methods in hybrid application.

Tealeaf Android SDK APIs available to JavaScript When you develop hybrid applications, you embed WebView component within a larger Android application. You can access exposed Android native methods from the UI Capture j2 global JavaScript object called "TLT" with methods that you use in your JavaScript code. This table lists and gives examples of the methods that you can include in your JavaScript code:

22

Method

Example

Enable Tealeaf Framework

/** * Public API to enable Tealeaf framework. * @returns {void} */ enableTealeafFramework();

Disable Tealeaf Framework

/** * Public API to disable Tealeaf framework. * @returns {void} */ disableTealeafFramework();

Log Screen Capture

/** * Public API to add a screenshot capture. * @returns {void} */ logScreenCapture();

Start New Tealeaf Session

/** * Public API to start a new Tealeaf session. * @returns {void} */ startNewTLFSession();

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Method

Example

Current Session ID

/** * Public API to start get current Tealeaf session Id. * @returns {String} Current session Id */ currentSessionId();

Default Value for Configurable Item

/** * Public API to get default value of a configurable item in * TLFConfigurableItems.properties file. * @param {String} configItem This is the name of the configurable item. * @returns {String} The value for the item. */ defaultValueForConfigurableItem (configItem);

Value for Configurable Item

/** * Public API to get the value of a configurable item either from * TLFConfigurableItems.properties file * or in memory data structure. * @param {String} configItem This is the name of the configurable item. * @returns {String} The value for the item. */ valueForConfigurableItem(configItem);

Set Configurable Item

/** * Public API to set the value of a configurable item in TLFConfigurableItems.properties * file. * @param {String} configItem This is the name of the configurable item. * @param {String} value The value assign to the configItem. * @returns {boolean} Wether item was set. */ setConfigurableItem(configItem, value);

Add Additional HTTP Header

/** * Public API to add additional http header. * @param {String} key This is the key of the configurable item. * @param {String} value The value assign to the configItem. * @returns {boolean} Wether item was set. */ addAdditionalHttpHeader(key, value);

Chapter 1. IBM Tealeaf CX UI CaptureJ2

23

Method

Example

Log Custom Event Bridge

/** * Public API to log custom event. * @param {String} eventName A custom event name. * @param {String} jsonData JSON data string. * @param {int} logLevel Tealeaf library logging level for the event. * @returns {boolean} Wether item was set. */ logCustomEventBridge(eventName, jsonData, logLevel);

Example of how a native Android API is started This example shows how to start a native method to enable Tealeaf Framework on a UI Capture j2 "TLT" instance using JavaScript: // Example of calling the native API to enable Tealeaf Framework using Javascript TLT.enableTealeafFramework();

Sample test HTML file that starts supported native methods in JavaScript This example is an HTML file that starts supported native methods in JavaScript: test APIs Test page for Android bridge APIs in hybrid app Click on below buttons to run tests: Test native APIs output here: function htmlConsoleLog(textData, apiRetVal){ var para = document.createElement("p"); var node; if( apiRetVal !== undefined && apiRetVal !== null ) { node = document.createTextNode(textData + " returned: " + apiRetVal); } else { node = document.createTextNode(textData );

24

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

} para.appendChild(node); var element = document.getElementById("queueData"); element.appendChild(para); } function runBridgeNativeTealeafAPIs() { htmlConsoleLog( ’----- -------------------------------- -----’ ); htmlConsoleLog( ’----- Calling Tealeaf native APIs -----’ ); var apiRetVal = null; htmlConsoleLog( ’----- Calling enableTealeaf -----’ ); TLT.enableTealeafFramework(); apiRetVal = null; htmlConsoleLog( ’----- Calling currentSessionId -----’ ); apiRetVal = TLT.currentSessionId(); htmlConsoleLog( ’----- currentSessionId -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling disableTealeaf -----’ ); TLT.disableTealeafFramework(); var apiRetVal = null; htmlConsoleLog( ’----- Calling enableTealeaf -----’ ); TLT.enableTealeafFramework(); apiRetVal = null; htmlConsoleLog( ’----- Calling currentSessionId -----’ ); apiRetVal = TLT.currentSessionId(); htmlConsoleLog( ’----- currentSessionId -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling defaultValueForConfigurableItem (PostMessageUrl) -----’ ); var PostMessageUrlVal = TLT.defaultValueForConfigurableItem (’PostMessageUrl’); htmlConsoleLog( ’----- defaultValueForConfigurableItem -----’, PostMessageUrlVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling setConfigurableItem("PostMessageUrl", "aValidPostUrl") -----’ ); apiRetVal = TLT.setConfigurableItem(’PostMessageUrl’, ’aValidPostUrl’); htmlConsoleLog( ’----- setConfigurableItem -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling valueForConfigurableItem ("PostMessageUrl") -----’ ); apiRetVal = TLT.valueForConfigurableItem(’PostMessageUrl’); htmlConsoleLog( ’----- valueForConfigurableItem -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling setConfigurableItem(PostMessageUrl, ’ + PostMessageUrlVal + ’) -----’ ); apiRetVal = TLT.setConfigurableItem(’PostMessageUrl’, PostMessageUrlVal ); htmlConsoleLog( ’----- setConfigurableItem -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling valueForConfigurableItem ("PostMessageUrl") -----’ ); apiRetVal = TLT.valueForConfigurableItem(’PostMessageUrl’); htmlConsoleLog( ’----- valueForConfigurableItem -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling startNewTLFSession -----’ ); apiRetVal = TLT.startNewTLFSession(); Chapter 1. IBM Tealeaf CX UI CaptureJ2

25

htmlConsoleLog( ’----- startNewTLFSession -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling addAdditionalHttpHeader -----’ ); TLT.addAdditionalHttpHeader(’HeaderFromJavaScript’, ’HeaderValueFromJavaScript’); htmlConsoleLog( ’----- addAdditionalHttpHeader -----’ ); apiRetVal = null; htmlConsoleLog( ’----- Calling enableTealeaf again -----’ ); TLT.enableTealeafFramework(); apiRetVal = null; htmlConsoleLog( ’----- Calling currentSessionId -----’ ); apiRetVal = TLT.currentSessionId(); htmlConsoleLog( ’----- currentSessionId -----’, apiRetVal ); apiRetVal = null; var str = ’{\’key1AndroidBridge\’: \’value1AndroidBridge\’, \’key2AndroidBridge\’: \’value2AndroidBridge\’}’; htmlConsoleLog( ’----- Calling logCustomEvent("Test Android Bridge Custom Event",’ + str +’) -----’ ); apiRetVal = TLT.logCustomEventBridge(’Test Android Bridge Custom Event’, str, 0); htmlConsoleLog( ’----- logCustomEvent(Test Android Bridge Event, ’ + str +’ ) -----’, apiRetVal ); htmlConsoleLog( htmlConsoleLog( htmlConsoleLog( htmlConsoleLog(

’----’----’----’-----

Done Calling Tealeaf native APIs ----------------------------------------------------------------------------------------------

-----’ -----’ -----’ -----’

); ); ); );

}

Accessing native Android methods with JavaScript with Tealeaf customized WebView When you crate hybrid applications, you can access native Android methods with JavaScript, you use the Tealeaf customized WebView. Before you begin this task, you must: 1. Install the most recent Tealeaf Android SDK. 2. Implement the Android SDK following the instructions in the documentation. 3. Include the most recent UI Capture j2 JavaScript source file. 1. Add WebView to your application. Specify a length, height, weight, and ID that suits your application:

2. In your activity, locate the WebView and load your HTML file: public class MainActivity extends ActionBarActivity { private UICWebView mUICWebView; private String logicalPageName = "BridgeAppActivity"; @Override protected void onCreate(Bundle savedInstanceState) { // Initialize tealeaf with a reference to application

26

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Tealeaf tealeaf = new Tealeaf(this.getApplication()); super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); // Load HTML file from local resource in the UICWebview mUICWebView = (UICWebView) findViewById(R.id.uic_webview); // Modify the Url for your hybrid app mUICWebView.loadUrl("file:///android_asset/www/test.html"); WebSettings webSettings = mUICWebView.getSettings(); webSettings.setJavaScriptEnabled(true); }

3. Copy the application's HTML and JavaScript files to the /assets/www folder in your Android project.

Hybrid application bridge for iOS APIs For hybrid applications, applications that are both web applications and iOS applications, Tealeaf provides a hybrid bridge. The hybrid bridge is a series of APIs that allow JavaScript to call native iOS Tealeaf SDK APIs directly. With the hybrid bridge, you need to integrate only the Tealeaf UIC JavaScript SDK with your application.

TLFApplicationHelper iOS APIs available to JavaScript These TLFApplcationHelper iOS APIs are available to JavaScript developers: v -(void)enableTealeafFramework; v -(void)disableTealeafFramework; v -(void)requestManualServerPost; v -(BOOL)startNewTLFSession; v -(NSString*)currentSessionId; v -(BOOL)setConfigurableItem:(NSString*)configItem value: (id)value; v -(id)valueForConfigurableItem:(NSString*)configItem; v -(id)defaultValueForConfigurableItem:(NSString*)configItem; v -(void) addAdditionalHttpHeader:(NSString*)value forName: (NSString*)name; The TLFApplicationHelper shared instance is available as the tealeafNativeApplicationHelperSharedInstance

Example of how a TLFApplicationHelper iOS API is invoked This example shows how a native iOS API, - (void)enableTealeafFramework;, is invoked on a shared TLFApplicationHelper instance: tealeafNativeApplicationHelperSharedInstance.enableTealeafFramework();

TLFCustomEvent iOS APIs available to JavaScript These TLFCustomEvent iOS APIs are available to JavaScript developers: v - (BOOL)logEvent:(NSString*)eventName; v - (BOOL)logEvent:(NSString*)eventName values:(NSDictionary*)values; v - (BOOL)logPrintScreenEvent;

Chapter 1. IBM Tealeaf CX UI CaptureJ2

27

The TLFCustomEvent shared instance is available as the tealeafNativeCustomEventSharedInstance

Example of how a TLFCustomEvent iOS API is invoked This example shows how a native iOS API, (BOOL)logEvent:(NSString*)eventName, is invoked on a shared TLFCustomEvent instance: tealeafNativeCustomEventSharedInstance.logEvent(’Test iOS7 Bridge Event’);

Use iOS APIs with existing JavaScript APIs Two APIs that are part of the CX UI Capture j2 library are used in the hybrid bridge: v TLT.logScreenCapture instructs the underlying native functionality to take a screen capture. v TLT.registerBridgeCallbacks is used to register callback functions, which are invoked by the CX UI Capture j2 library in specific instances. This API supports messageRedirect, screenCapture, and addRequestHeaders callbacks. The messageRedirect callback can be registered to redirect and intercept messages from CX UI Capture j2. The screeCapture callback can be registered to enable a JavaScript API to allow a screen capture to be taken. The addRequestHeaders callback can be registered to enable a third-party JavaScript to return custom HTTP headers that need to be set on the UI Capture libraries POST request.

Example function call for all of the iOS native APIs This function in this example, function runiOS7BridgeNativeTealeafAPIs(), shows how to call all of the iOS native APIs: test APIs Test page for API Testing

28

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide



function register_ScreenShot_Enable_CallBack() { TLT.registerBridgeCallbacks([ { enabled: true, cbType: "screenCapture", cbFunction: myCbFunction1 }, { enabled: true, cbType: "messageRedirect", cbFunction: myCbFunction2 }, { enabled: true, cbType: "addRequestHeaders", cbFunction: myCbFunction3 }, ]); } function myCbFunction1() { alert("screen Capture by native"); } function myCbFunction2(dataSent) { var div = document.getElementById(’queueData’); div.innerHTML = div.innerHTML + dataSent + ’\n’; } function myCbFunction3() { alert("add headers to native"); } function htmlConsoleLog(textData, apiRetVal){ var para = document.createElement("p"); var node; if( apiRetVal !== undefined && apiRetVal !== null ) { node = document.createTextNode(textData + " returned: " + apiRetVal); } else { node = document.createTextNode(textData ); } para.appendChild(node); var element = document.getElementById("queueData"); element.appendChild(para); } function runiOS7BridgeNativeTealeafAPIs() { htmlConsoleLog( ’----- -------------------------------- -----’ ); htmlConsoleLog( ’----- Calling Tealeaf native APIs -----’ ); var apiRetVal = null; htmlConsoleLog( ’----- Calling enableTealeaf -----’ ); tealeafNativeApplicationHelperSharedInstance.enableTealeafFramework(); apiRetVal = null; htmlConsoleLog( ’----- Calling currentSessionId -----’ ); apiRetVal = tealeafNativeApplicationHelperSharedInstance.currentSessionId(); htmlConsoleLog( ’----- currentSessionId -----’, apiRetVal ); Chapter 1. IBM Tealeaf CX UI CaptureJ2

29

apiRetVal = null; htmlConsoleLog( ’----- Calling disableTealeaf -----’ ); tealeafNativeApplicationHelperSharedInstance.disableTealeafFramework(); apiRetVal = null; htmlConsoleLog( ’----- Calling defaultValueForConfigurableItem(PostMessageUrl) -----’ ); var PostMessageUrlVal = tealeafNativeApplicationHelperSharedInstance. defaultValueForConfigurableItem(’PostMessageUrl’); htmlConsoleLog( ’----- defaultValueForConfigurableItem -----’, PostMessageUrlVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling setConfigurableItemValue("PostMessageUrl", "blahblah") -----’ ); apiRetVal = tealeafNativeApplicationHelperSharedInstance. setConfigurableItemValue(’PostMessageUrl’, ’blahblah’); htmlConsoleLog( ’----- setConfigurableItemValue -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling valueForConfigurableItem("PostMessageUrl") -----’ ); apiRetVal = tealeafNativeApplicationHelperSharedInstance. valueForConfigurableItem(’PostMessageUrl’); htmlConsoleLog( ’----- valueForConfigurableItem -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling setConfigurableItemValue("PostMessageUrl", ’+ PostMessageUrlVal + ’) -----’ ); apiRetVal = tealeafNativeApplicationHelperSharedInstance. setConfigurableItemValue(’PostMessageUrl’, PostMessageUrlVal ); htmlConsoleLog( ’----- setConfigurableItemValue -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling valueForConfigurableItem("PostMessageUrl") -----’ ); apiRetVal = tealeafNativeApplicationHelperSharedInstance. valueForConfigurableItem(’PostMessageUrl’); htmlConsoleLog( ’----- valueForConfigurableItem -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling startNewTLFSession -----’ ); apiRetVal = tealeafNativeApplicationHelperSharedInstance. startNewTLFSession(); htmlConsoleLog( ’----- startNewTLFSession -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling enableTealeaf again -----’ ); tealeafNativeApplicationHelperSharedInstance.enableTealeafFramework(); apiRetVal = null; htmlConsoleLog( ’----- Calling currentSessionId -----’ ); apiRetVal = tealeafNativeApplicationHelperSharedInstance.currentSessionId(); htmlConsoleLog( ’----- currentSessionId -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling logPrintScreenEvent -----’ ); apiRetVal = tealeafNativeCustomEventSharedInstance.logPrintScreenEvent(); htmlConsoleLog( ’----- logPrintScreenEvent -----’, apiRetVal ); apiRetVal = null; htmlConsoleLog( ’----- Calling logEvent("Test iOS7 Bridge Event") -----’ ); apiRetVal = tealeafNativeCustomEventSharedInstance.logEvent(’Test iOS7 Bridge Event’); htmlConsoleLog( ’----- logEvent -----’, apiRetVal );

30

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

apiRetVal = null; htmlConsoleLog( ’----- Calling logEventValues("Test iOS7 Bridge Event", objDict) -----’ ); var objDict = {’key1iOS7Bridge’: ’value11iOS7Bridge’, ’key21iOS7Bridge’: ’value21iOS7Bridge’}; apiRetVal = tealeafNativeCustomEventSharedInstance.logEventValues(’Test iOS7 Bridge Event’, objDict); htmlConsoleLog( ’----- logEventValues(Test iOS7 Bridge Event, objDict ) -----’, apiRetVal ); htmlConsoleLog( htmlConsoleLog( htmlConsoleLog( htmlConsoleLog(

’----’----’----’-----

Done Calling Tealeaf native APIs ----------------------------------------------------------------------------------------------

-----’ -----’ -----’ -----’

); ); ); );

} //runiOS7BridgeNativeTealeafAPIs(); register_ScreenShot_Enable_CallBack();

Related documentation A number of guides and resources are available to support implementation of the IBM Tealeaf UI Capture solution. Table 8. UI Capture documentation resources Document

Description

IBM Tealeaf Client Framework Data Integration Guide

After you deploy your client framework, more configuration can be required. Reference for configuring data capture in IBM Tealeaf and to make data available for creating events, which enables search and reporting. This document aids your IBM Tealeaf administrators whenever you are implementing an IBM Tealeaf client framework.

IBM Tealeaf Android SDK Guide

Installation and implementation guide for the IBM Tealeaf Android SDK for Android-based mobile native applications. Deployment requires the IBM Tealeaf CX Mobile license.

IBM Tealeaf iOS SDK Guide

Installation and implementation guide for the IBM Tealeaf iOS SDK for iOS-based mobile native applications. Deployment requires the IBM Tealeaf CX Mobile license.

Chapter 1. IBM Tealeaf CX UI CaptureJ2

31

32

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Chapter 2. UI Capture installation and implementation Before you install and implement UI Capture , you must verify the software release that is used by your system. Before you begin installation and implementation, review the guidelines for use. See Chapter 4, “UI Capture usage guidelines,” on page 69.

Install version Before you begin to implement UI Capture , verify that you have the latest version of the software. You can access the installation package through IBM Passport Advantage® Online. This section contains details on how to implement of the IBM Tealeaf UI Capture library. Note: Depending on the complexity of your web application, an IBM Tealeaf UI Capture library implementation can requireIBM consulting services. For more information, contact IBM Professional Services.

Support for CX RealiTea Viewer The IBM Tealeaf CX RealiTea Viewer is a stand-alone desktop application that can be used to replay sessions captured by IBM Tealeaf, including client UI events. To replay sessions that include UI events, you must install CX RealiTea Viewer on your local desktop. Note: Replay of sessions that are captured by UI Capture is not fully supported in the CX RealiTea Viewer. v The JSON messages that contain UI events are not fully supported in the CX RealiTea Viewer. v For replay of JSON messages, use Browser Based Replay. See "CX Browser Based Replay" in the IBM Tealeaf cxImpact User Manual. Note: UI Capture is compatible with Release 8.6 and later. It is not compatible with earlier releases.

Support for mobile web application capture To capture data from mobile web applications, a license for IBM Tealeaf CX Mobile is required. See "Client Framework Versions" in the IBM Tealeaf Client Framework Data Integration Guide.

CX Passive Capture Application configuration By default, the IBM Tealeaf CX Passive Capture Application captures a number of the mimetypes that are posted by rich internet applications. Depending on the type of application you are deploying, you can enable the capture of more types. © Copyright IBM Corp. 1999, 2015

33

IBM Tealeaf UI Capture requires the CX Passive Capture Application to be configured to enable capture of JSON content in the request. You must also configure the CX Passive Capture Application to capture the wanted POST traffic. CX Passive Capture Application can be configured to include or exclude specific file extensions, mimetypes, and POST types. Note: Be sure to verify that your CX Passive Capture Application installation was configured to capture JSON mimetypes. See "PCA Web Console - Pipeline Tab" in the CX Passive Capture Application CX Passive Capture Application Manual. If dynamic JavaScript or CSS style sheets must be captured, the IBM Tealeaf CX Passive Capture Application must be configured to capture this content. Avoid capturing dynamic versions of content that is typically static. As an alternative, you can capture this content to a static archive. See "Managing Static Archives" in the IBM Tealeaf cxImpact Administration Manual. v For descriptions of the capture types to enable for various types of RIA applications, see "Installation" in the IBM Tealeaf CX Passive Capture Application Manual. v For more information about how to enable a capture type in the CX Passive Capture Application Web Console, see "PCA Web Console - Pipeline Tab" in the IBM Tealeaf CX Passive Capture Application Manual.

Installation and deployment plan UI Capture can be rapidly deployed in local environments for development and testing. When you resolve all issues that can be monitored outside of the IBM Tealeaf environment, the library can be ported to an IBM Tealeaf environment for further testing and tweaking.

Stage 1: Development environment In the development environment, the goals for UI Capture deployment are to integrate the required files into the web infrastructure and to establish basic connectivity between the web server, the client, and the CX Passive Capture Application for capture.

File to add to web pages The UI Capture JavaScript file must be included in each web page in the application that you want to monitor.

Server placement On your web server, place the UI Capture JavaScript file with the other static files served by your site.

Include location Every served page that requires client event tracking must have tags in it to load the UI Capture JavaScript file. In each page, the JavaScript file must be included as follows.

34

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

If you place the IBM Tealeaf UI Capture JavaScript file anywhere other than the root directory on your web server, you must adjust the src= parameter in the reference to point to the correct location. Note: You are not required to place the UI Capture JavaScript at the top of the page. See Chapter 1, “IBM Tealeaf CX UI CaptureJ2,” on page 1.

Installing UI Capture To install and deploy UI Capture , complete the following steps. 1. If you did not do so already, configure the JavaScript. 2. Deploy the IBM Tealeaf target page in the location where the library is configured to POST to it. See “IBM Tealeaf target page” on page 41. 3. Place the required JavaScript in the appropriate web server location. See “Server placement” on page 34. 4. Modify the served pages to reference the JavaScript. See “Include location” on page 34. 5. When the JavaScript is referenced in the served pages and can post to the target page, UI Capture is operational.

Verify Stage 1 To verify that UI Capture is working properly in your Development environment, you complete the following tests.

No JavaScript errors on the page Through your web browser, visit a sampling of the served pages. Verify that the included JavaScript is not generating JavaScript errors.

Verify client events are being posted Deploy a browser monitoring tool such as Fiddler, HTTPWatch, or Firebug to verify that client events are being posted to the target page. Note: Normal POSTs from UI Capture are asynchronous, with one exception. In the POST traffic stream, look for request headers that contain X-Tealeaf and a JSON message such as: {"messageVersion":"2.1.0.0","serialNumber":1,"sessions":...

The version number varies from release to release. Note: If UI Capture data is being forwarded to IBM Tealeaf, through the IBM Tealeaf Portal you can search for the IBM Tealeaf target page to see whether any sessions are retrieved. In the Testing and Production environments, use the Portal search test.

Stage 2: Testing environment In the Testing environment, the goals are to deploy UI Capture to verify correct operation and end-to-end monitoring of UI events, such that you can search for, replay, and report on client UI events.

Chapter 2. UI Capture installation and implementation

35

Requirements for the Testing environment Your Testing environment must meet certain requirements to complete end-to-end testing. v IBM Tealeaf CX Passive Capture Application The CX Passive Capture Application must be implemented, enabled, and functioning properly. CX Passive Capture Application must be configured to capture the appropriate content types. See "Client Framework Versions" in the IBM Tealeaf Client Framework Data Integration Guide. For more information about configuration, see "PCA Web Console - Pipeline Tab" in the IBM Tealeaf CX Passive Capture Application Manual. v Browser Based Replay To verify replay of UI events, use Browser Based Replay to verify that the UI events appear in the navigation pane. See “Replaying a captured session in BBR” on page 37. v Search You must be able to search for and retrieve specific client UI fields in the request. Details follow. Verify basic search capability beforehand in both the Portal and CX RealiTea Viewer. v Reporting Client UI events can appear in reports that are configured through the IBM Tealeaf Report Builder. See "Tealeaf Report Builder" in the IBM Tealeaf cxImpact Reporting Guide.

Installation in the Testing environment To install and deploy in the Testing environment, follow the same steps that are used in the Development environment, modifying the JavaScript as needed to work in Testing. v See “Installing UI Capture ” on page 35.

Verify Stage 2 To validate your UI Capture deployment in your Testing environment, complete the following tests. Generate a session with UI events in it: Using your web browser, visit the web application that is monitored by the IBM Tealeaf Testing environment. Requirements v Do not use Client-Side Capture for this test. Use IBM Tealeaf to capture and process the data. v Visit a series of pages that contain UI events. Trigger all test UI events so that they are included in your captured session. v Generate the session so that you have a uniquely identifiable way to locate the session through search. – As the session is being generated, you can use Fiddler or a similar tool to review the request data to locate the IBM Tealeaf session identifier. – You can also do browsing tricks such as inserting a unique string in a form field and then submitting it. v Be sure to close your session so that it can be indexed for search.

36

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Replaying a captured session in BBR: After you capture a session, you replay it through Browser Based Replay to confirm that client UI events are present. Based on your review of the replay, you can adjust configuration settings and develop replay rules, after which you can replay the session. Repeat this process until you secure a good quality replay of the captured session. Note: Replay of captured sessions in CX RealiTea Viewer is not fully supported for UI Capture , depending on your application. Beginning in Release 8.6 or later, you use Browser Based Replay for replay. 1. Locate the session through search. See "Searching Session Data" in the IBM Tealeaf cxImpact User Manual. 2. Replay the session in Browser Based Replay. 3. Switch to request view. 4. Step through the pages of the session. 5. At the top of the display panel, the following link displays. Click here to view Step Attributes

6. This link indicates that JSON data was captured as part of the session, which means that UI Capture is submitting it correctly. v You can click the link to review the JSON data in a readable form. v From this area, you can create IBM Tealeaf events and step attributes of the data. See “Create IBM Tealeaf events for client UI data.” v When the IBM Tealeaf events are created from the JSON data, those events are marked in subsequent sessions that are captured by IBM Tealeaf. Then, you can search for them using the Portal interface. See "Searching Session Data" in the IBM Tealeaf cxImpact User Manual. 7. To ensure a good replay experience, you can create replay rules or modify your existing ones to properly manage the replay of sessions that are captured by IBM Tealeaf UI Capture . See “Tweak replay rules” on page 38. 8. After IBM Tealeaf events are created, you can create reports in the IBM Tealeaf Report Builder with these events to begin tracking client-side events. See “Verify IBM Tealeaf Portal reporting” on page 38. Create IBM Tealeaf events for client UI data: After you implement UI Capture , you can test for the availability of data for eventing purposes through Browser Based Replay. Browser Based Replay enables the creation of attributes and events from the JSON steps that are submitted from the IBM Tealeaf client frameworks. Using this simple mechanism, you can quickly create the step attributes and events that are needed to capture traffic from the client interface, as submitted by UI Capture . See "Step-Based Eventing" in the IBM Tealeaf Event Manager Manual. Note: If you are upgrading from a UI Capture version from 2012.06.01.1 or earlier, the following request fields are not populated by this version of UI Capture: v TLT_CUI_URL v TLT_CUI_APPLICATION_NAME

Chapter 2. UI Capture installation and implementation

37

Any eventing, indexing, or search templates configured based on the presence of these request fields do not work for UI Capture . v For more information about events, see "TEM Events Tab" in the IBM Tealeaf Event Manager Manual. v For more information about indexing, see "Configuring CX Indexing" in the IBM Tealeaf CX Configuration Manual. v For more information about configuring search templates, see "Configuring Search Templates" in the IBM Tealeaf cxImpact Administration Manual. Tweak replay rules: Client UI events often require replay rules to manage proper display of them. A replay rule is an action that is applied to session data before replay for purposes of enhancing the replay experience. Note: Replay rules are stored in a user profile. When UI Capture is deployed in a Production environment, you make this profile available to all CX RealiTea Viewer and Browser Based Replay users. See “Deploy profile.” Replay rules can be applied through Browser Based Replay. See "BBR Replay Rules" in the IBM Tealeaf cxImpact User Manual. Repeat the tests: Repeat the tests in this section until you achieve a satisfactory replay. To iterate on the process, see “Replaying a captured session in BBR” on page 37. Verify IBM Tealeaf Portal reporting: You can review the following reports to verify that client UI events are being posted to IBM Tealeaf and submitted to the reporting databases. After you create an IBM Tealeaf event with Step-Based Eventing in Browser Based Replay, wait at least 1 hour for report data to gather. Then, you can create a simple report in the IBM Tealeaf Report Builder containing your event and constrained to the current date as the focus period. If data is present, then the reporting functions are working for UI Capture data. See "Tealeaf Report Builder" in the IBM Tealeaf cxImpact Reporting Guide.

Stage 3: Production environment After you complete all of the tests in your Testing environment, you can deploy the UI Capture solution to your Production environment.

Deploy profile If you develop profile rules or modify CX RealiTea Viewer settings in your Testing environment, make the changes available to all CX RealiTea Viewer and Browser Based Replay users who can access the Production environment. v For more information about sharing your CX RealiTea Viewer profile, see "RealiTea Viewer - Profile Options" in the IBM Tealeaf CX RealiTea Viewer User Manual.

38

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

v For Browser Based Replay, replay profile settings are configured for individual user groups for IBM Tealeaf cxImpact or IBM Tealeaf cxReveal users. – For more information, see the Browser Replay Profile in "CX User Administration" in the IBM Tealeaf cxImpact Administration Manual. – For more information, see the Browser Replay Profile in "cxReveal User Administration" in the IBM Tealeaf cxReveal Administration Manual.

Install in Production To install and deploy in the Production environment, follow the same steps that are used in the Development environment, modifying the JavaScript as needed to work in Production. v See “Installing UI Capture ” on page 35.

Verify Stage 3 Repeat all tests that you completed in Development and Testing in the Production environment. v “Verify Stage 1” on page 35 v “Verify Stage 2” on page 36

Configuring the JavaScript UI Capture JavaScript interactions with web application pages The IBM Tealeaf UI Capture JavaScript is able to monitor user interface events by attaching keyboard and mouse event listeners to HTML elements on the pages of your web application.

Overriding existing API In some cases, IBM Tealeaf overrides the existing browser API. Currently, this override behavior occurs for the following event.

window.onerror IBM Tealeaf overrides the default window.onerror event handler to track client-side error conditions that do not generate a transaction with the web server. The IBM Tealeaf UI Capture library performs this override only if there is no current listener for window.onerror.

Block sensitive data fields If required, sensitive information that is submitted by visitors into client-side forms can be blocked in the JSON data that is submitted to IBM Tealeaf. For example, if a visitor enters a social security number into a form field, you can configure field block rules to block the entered social security number (such as XXX-XX-XXXX). The following section describes how privacy works in IBM Tealeaf UI Capture . You implement your privacy configuration as part of your initial installation. For more information, contact IBM Professional Services.

Chapter 2. UI Capture installation and implementation

39

Installation on web pages When you plan the installation of the UI Capture library, consider that it does use system resources to process on the website and the IBM Tealeaf capture systems. Install the library only on the pages that you want to capture and replay. Installing the UI Capture library can cause the following effects. v Page load times can increase slightly during first download. IBM Tealeaf provides strategies for minimizing the effect on load times, including caching the JavaScript after initial download. v More data is posted by the web page to the server, but it is not processed. v IBM Tealeaf must process and store the additional data. IBM Tealeaf UI Capture is designed to minimize these burdens.

Unique HTML IDs To capture the client events for a Document Object Model object, each object or control available with which the visitor can interact must have a unique HTML ID. Without unique IDs, IBM Tealeaf cannot properly replay the UI events in the page. If you did not instrument your application to support unique IDs or unique names in the document object model, IBM Tealeaf UI Capture automatically generates paths to the node that support the requirement of uniqueness. IBM Tealeaf also supports the creation of ID black lists, which forces the use of Xpath or name attribute values as identifiers. See Chapter 5, “UI Capture reference,” on page 111.

Cookies The web session must use cookies for sessionization. Cookies allow the client events to send messages without having to understand the sessionization mechanism. For best results in capturing client UI events, deploy the IBM Tealeaf Cookie Injector in your web server environment. The IBM Tealeaf Cookie Injector provides unique session IDs regarding captured IBM Tealeaf session data. See "Installing and Configuring the Tealeaf Cookie Injector" in the IBM Tealeaf CX Cookie Injector Manual.

Installation on the web server The IBM Tealeaf UI Capture library consists of a single JavaScript file. You place this JavaScript file with the other static files served by your site.

References to the JavaScript file To track activity on a web page, you add a reference to the required UI Capture JavaScript file. Every served page that requires client event tracking must have tags in it to load the IBM Tealeaf UI Capture JavaScript:

40

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

If you place the UI Capture JavaScript in a place other than the root directory on your web server, adjust the src= parameter in the reference to point to the correct location. See "UI Capture j2 Overview".

IBM Tealeaf target page The IBM Tealeaf target page is a URL to which the UI Capture JavaScript is configured to send POST requests for capture by the IBM Tealeaf system. You place this dynamic page with the other dynamic page files for your web application.

How the target page is used The dynamic target web page must be posted or created to receive the information posted by the JavaScript, such as TealeafTarget.php, TealeafTarget.jsp, TealeafTarget.asp, or similar. The target page exists only to acknowledge the post. No data is saved. The web server returns a minimal valid response, such as the following message. Received 895 bytes in 0.1 ms

Sample target pages Sample targets for ASPX, JSP, and PHP environments are provided with the UI Capture distribution. You can modify the target page for your specific target environment. You can use these sample targets as the basis for creating target pages suitable for other environments.

Target page requirements A Tealeaf target page (TealeafTarget) must be added to your web server infrastructure in a location that the UI Capture JavaScript can access. For simplicity, you can place the dynamic page in the root directory. Your website administrator can provide you with the policies and procedures for your installation. The Tealeaf target page ensures the proper capture of UI events, and must have the following properties: v The page must be POSTable. v The page must be dynamically executable, for example, ASPX, PHP, or JSP. v The page must not be cached by Akamai or any cache service, device, or mechanism.

Target page modifications for DOM Capture The target page is configured by default to read in up to 20,000 bytes. DOM Capture deployments have varying POST sizes, depending on the size and frequency of the DOM snapshots. You update the target page to account for the increased POST data. Use the TLT_MAX_REQ_LENGTH field in the target page to a value that reflects the typical POST data size from the UI Capture SDK in your deployment. This setting ensures the correct capture of the UI Hits by the PCA. Chapter 2. UI Capture installation and implementation

41

Verifying the target page All of the provided IBM Tealeaf target pages are named so that the data they receive can be captured, processed, and integrated into replay by IBM Tealeaf. Note: The file name of the IBM Tealeaf target page must include TealeafTarget in it for easy identification. Do not change this file name after you configure IBM Tealeaf UI Capture . Complete the following steps to verify that there are no impediments to the capture and processing of the IBM Tealeaf target page in your system. 1. In the Web Console of the IBM Tealeaf CX Passive Capture Application, you configure file extensions to drop from capture. Verify that the file extension used for your IBM Tealeaf target page is not dropped from capture. See "PCA Web Console - Pipeline Tab" in the IBM Tealeaf CX Passive Capture Application Manual. 2. In the IBM Tealeaf CX RealiTea Viewer, some file extensions are treated as interpreted pages, which means that the pages are interpreted on the web server before they are delivered to CX RealiTea Viewer. Verify that the extension for your IBM Tealeaf target page file name does not appear in the list of possible interpreted pages in CX RealiTea Viewer. See "RealiTea Viewer Advanced Options Tabs" in the IBM Tealeaf CX RealiTea Viewer User Manual.

Target page installation The target page must be added to your web infrastructure in a location that can be accessed from the visitor's web browser. For simplicity, you can place these files in the root directory or in a central JavaScript directory. Your website administrator can provide you with the policies and procedures for your installation. In your web application's pages, references to the target page must be relative to the site root path. For www.example.com, to reference an IBM Tealeaf target page at www.example.com/scripts/TealeafTarget.aspx, you configure the IBM Tealeaf UI Capture to /scripts/TealeafTarget.aspx. The initial / makes it a site-root relative path.

Deployment guidelines Refer to these guidelines when you deploy the IBM Tealeaf target page. Typically, the IBM Tealeaf target page is deployed independently of the core application itself in logical and physical terms. Review these guidelines with your infrastructure staff. v Avoid deploying the IBM Tealeaf target page behind enterprise security features, such as SiteMinder. v If possible, deploy the IBM Tealeaf target page on a separate application server instance from the web application. While it is a lightweight deployment, it can compete for resources with the web application. If possible, deploy it on a dedicated application server instance. v Test the IBM Tealeaf target page thoroughly in a test environment before deployment to production.

References to the target page In your web application's pages, references to the IBM Tealeaf target page must be relative to the site root path.

42

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

For www.example.com, to reference an IBM Tealeaf target page at www.example.com/scripts/TealeafTarget.aspx, you configure the UI Capture library to POST to /scripts/TealeafTarget.aspx. The initial "/" makes it a site-root relative path. In the UI Capture JavaScript, the URL of the target page is configured as part of the initial implementation.

Unit tests of the target page To test that the target page is operating properly, you can run the following tests. v GET: Enter the URL of the target page in your browser. If you receive a blank page or non-404 error, the page is properly handling your request. v POST: You can use Fiddler or another traffic monitoring tool to generate a post to the page. Verify that the POST action resulted in a Status Code 200 message.

Configuration of UI Capture JavaScript To configure the JavaScript file for IBM Tealeaf UI Capture , you define settings for compression and caching.

Compression For optimal performance, compress the IBM Tealeaf JavaScript on your web server. v Configure the web server to perform compression encoding of the response data before it is sent back to the browser, which decompresses it for use on the client. v Apply compression encoding to static text content, including the IBM Tealeaf JavaScript file. Note: Since this behavior is negotiated between server and client, an HTTP 1.1-compliant web server must not use any compression encoding unless the client indicated support of it by a Request Header (Accept-Encoding). This form of compression further reduces the file sizes of minified IBM Tealeaf JavaScript by approximately 75% before delivery to the client.

Browser caching For browser caching configuration, follow these guidelines. v Set the TTL values for the Expires or Cache-Control headers for the IBM Tealeaf JavaScript to the same value as the rest of the scripts that are stored on the web server. v Take advantage of the conditional GET feature of HTTP 1.1 by configuring your web server to set the appropriate ETag or Last-Modified headers. When this feature is enabled, any change to the JavaScript resources is automatically propagated to the visitor's cache. For more information, see these industry resources. v http://developer.yahoo.com/performance/rules.html v http://code.google.com/speed/page-speed/docs/rules_intro.html

Chapter 2. UI Capture installation and implementation

43

IIS configuration On Windows Server 2003, put the IBM Tealeaf UI Capture files in a directory with the other JavaScript file to comply with the "Script source access" setting in the configuration. For more information about configuring IIS, see http://support.microsoft.com/ default.aspx?scid=kb;en-us;313075.

Non-IIS web server configuration For a non-IIS server, a dynamic web page must be created to accept the POST from the IBM Tealeaf UI Capture JavaScript. The contents of the web page vary based on the deployed technology. The contents of the returned UI Capture JavaScript POST requests are irrelevant. To minimize bandwidth, minimize the return contents.

Web page modifications Every served page that requires client event tracking must have a tag in it to load the IBM Tealeaf UI Capture JavaScript file. See “Include location” on page 34.

Change management for Document Object Model elements In certain instances, when your web application changes the Document Object Model, your page code must notify IBM Tealeaf of the location where the changes were made. For Ajax, DHTML, or JavaScript based updates that add or edit Document Object Model elements, the page in which the changes are made must call the following IBM Tealeaf API to register the node change, TLT.rebind. Note: This call must be made when new nodes are added for which capturing the user interaction is essential. Changes that remove nodes can be processed during normal cleanup when the page is unloaded. Example code: Rebind example ... /* AJAXUpdate will be called after the XMLHttpRequest returns * a successful response. */ function AJAXUpdate(responseMarkup){ var targetDiv = document.getElementById("target_div"); if (!targetDiv || !responseMarkup) { return; } targetDiv.innerHtml = responseMarkup; if (TLT && TLT.rebind) { // Notify Tealeaf of the DOM update. TLT.rebind(targetDiv); } }

44

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

... ... Placeholder where the AJAX response markup will be placed. ...

Upgrade UI Capture For information about upgrading to the latest version of IBM Tealeaf UI Capture , contact IBM Professional Services.

Support for legacy headers For customers that are upgrading from IBM Tealeaf CX UI Capture for AJAX to IBM Tealeaf UI Capture , support for some of the legacy headers submitted from CX UI Capture for AJAX is retained. Header Description X-TeaLeafType Type of client-side event set. Default value is GUI. X-TeaLeaf-Page-Url Full URL of the parent page. X-TeaLeaf-Page-Render Time in milliseconds for page to render. X-TeaLeaf-Page-Objects Number of objects (object tags) on page. X-TeaLeaf-Page-Img-Fail Number of bad images on the page. X-TeaLeaf-Page-Cui-Exceptions Number of exceptions on the page. X-TeaLeaf-Page-Dwell Dwell time on the page. X-TeaLeaf-Page-Last-Field ID of the last visited form field on the page. X-TeaLeaf-Visit-Order Visit order of the form fields on the page. Note: Other headers that are submitted through IBM Tealeaf CX UI Capture for AJAX are not supported. For more information about those headers, see "UI Capture for Ajax Sample Client Event Message" in the IBM Tealeaf CX UI Capture for AJAX Guide.

Chapter 2. UI Capture installation and implementation

45

Uninstalling UI Capture To uninstall UI Capture , apply the following changes in your Development environment. 1. Save a copy of the currently deployed UI Capture JavaScript. If you minified the JavaScript, save a version of the source JavaScript. 2. Remove the references to the UI Capture files from the pages of your web application. 3. Remove the UI Capture files from the area where they are installed on your web server. 4. Remove the IBM Tealeaf target page. 5. Push the changes to the server. 6. Verify that no browser errors are generated in visitor browsers when you visit your own web application. 7. Verify that IBM Tealeaf UI Capture events are no longer being captured and processed by IBM Tealeaf. 8. Disable any IBM Tealeaf event objects that reference UI events captured by IBM Tealeaf UI Capture . If the changes are applied successfully in your development environment, you can apply them in your Test and Production environments in succession.

46

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Chapter 3. Configure UI Capture basic settings 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: © Copyright IBM Corp. 1999, 2015

47

v v v v

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: Built 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 Chapter 5, “UI Capture reference,” on page 111

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.

48

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Configuration wizard controls When you use the UI Capture Configuration wizard, you complete different actions with these user interface controls. v To go to the next screen in the wizard, click Next. v To return to the previous screen, click Previous. v To complete the configuration, click Finish. v To reset the configuration to the defaults provided by Tealeaf, click Reset to defaults. v To define and test regular expressions for use in your configuration, click RegEx tester. See “RegEx Tester” on page 55. 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 recommneded 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 compatability. 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: v jQuery object - the path to the jQuery object. v 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. v 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. v 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: v Sizzle URL - the Sizzle URL. Sizzle is required for the correct operation of the library in legacy IE browsers when the W3C service is used. v Sizzle object - the path to the Sizzle object.

Chapter 3. Configure UI Capture basic settings

49

v 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. v 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. v 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>. v 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 }

Services 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 Service, 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 IBM 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 Target page - whether to check the Target page availability when the UIC initializes. 7. Target page timeout - the time, in milliseconds, that the UIC waits for a reply from the Target page before shutting down. This setting is used only when the UIC initializes and sends a test async request to the Target page.

50

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Queue Service optional configuration settings You can configure additional information for the Queue Service: 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 UI Capture SDK 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 SDK 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. See "Managing Data Privacy in Tealeaf CX" in the IBM Tealeaf CX Installation Manual. Click the Help icon in the Configuration wizard for more details on each setting. More details are available in the Reference section. See Chapter 5, “UI Capture reference,” on page 111.

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: v an ID v an IDTypes v a CSS Selector

Chapter 3. Configure UI Capture basic settings

51

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: v 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. v 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 IBM Tealeaf UI Capture solution. The UI Capture library is the data capture library for various Tealeaf components and features. You can prevent the collecting and transmitting of more 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.

52

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

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 message in the JSON data stream that is sent back to the Tealeaf capture server. For more information, go to http://www.w3c.org.

Performance data By default, Performance data is not captured because it can affect bandwidth. When you enable the Performance module, you automatically capture the render time information performance data. You can select more performance information to capture. When you enable the Performance module, you enable these settings and filters: v renderTimeThreshold - The render time for browsers that do not support W3C Navigation Timing v Filters for which data is not captured when you enable the Performance module: – 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.

Replay module The Replay module enables specific replay settings and defines custom replay events, which you can use to trigger a DOM Capture. When you enable the Replay module, you enable: v Mobile events - Capture mobile events Chapter 3. Configure UI Capture basic settings

53

v Screenviews from hashchange v Scroll and window size tracking During configuration, you can use the Replay events Advanced Options to disable any of these events and to define custom replay events. You need the Event Name and Event Target or State. For example, you can define an event that is called "Login" that has a state "detail'. You can then trigger DOM Capture from this custom event. If you are using DOM capture, and you want the capture to happen after all of the frames have loaded on a page, you use a combination of replay custom events and DOM capture triggers. You configure a custom "load" event in the Replay module called "loadWithFrames". Then you configure a a DOM capture "load" trigger for the "rootWithFrames" screenview. When Replay module "loadWithFrames" event is enabled, the UI Capture library monitors the frames and iframes on the page and posts a new screenview message with screenview name “rootWithFrames” after all the frames and iframes have loaded. You use "rootWithFrames" instead of the traditional "root".

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

DOM 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: v Threshold for snapshots. Any snapshots over this threshold are not sent to the server v Default events to trigger DOM Captures. v Custom events to trigger DOM Captures, if you defined the event to be captured by the replay module. If you are capturing a screenview after the frame load, you configure the Replay custom "load"event "loadWithFrames", and you configure the DOM capture "load" trigger for the "rootWithFrames" screenview. v Whether you want to capture child Frames or iFrames. v Whether you want to remove scripts from the captured snapshots. v Whether you want to enable DOM Diff. The default for this service is enabled. Note: This information pertains to functionality available in IBM Tealeaf UI Capture version 5.0.0. For information about the release, contact your IBM Tealeaf representative. The DOM Diff service captures and processes changes in a screenview that happen 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 the DOM Diff service enabled, the entire HTML content of the page would be captured.

54

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

However, depending on the application, there might be so many fields and differences to capture, that processing the differences into one capture affects performance. In this case, you would want to disable the DOM Diff service. You need to monitor the performance and adjust the settings for your situation.

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 "TLTSID" and the Tealeaf App Key. If you use Tealeaf cookies and the "TLTSID" cookie is not already set on the application domain, the UIC generates a random 32 length string and sets it as the "TLTSID" cookie value. The cookie value is also sent in the X-Tealeaf-SaaS-TLTSID header of the UIC post. 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. Chrome browser is deprecating the support for API getCurrentPosition() and watchPosition() on insecure origins (http url).

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 }

RegEx Tester In the RegEx Tester, you can specify regular expressions and test them against data that you provide. You can enter regular expressions in some sections of the Configuration wizard. You can use the RegEx tester to test and validate a regular then copy the regular expression into the configuration. This minimizes syntax errors. The RegEx tester can only validate and provide the right syntax. The user is still required to ensure the regular expression is semantically valid.

Chapter 3. Configure UI Capture basic settings

55

RegEx options This table lists and describes the RegEx Tester options: Option

Description

RegEx

Enter your regular expression to test. v By default, searches in the Test Sample data are case-sensitive. You can configure the test to do Case insensitive searches. v By default, the regular expression is matched against the first occurrence in the string. v To match the regular expression against all occurrences in the string, select the Global option. This option is not typically required.

Test Sample

Enter your sample data to apply in the test. Use data specific to your web application, such as a sample request.

Matches

If a match is found for the regular expression in the test sample data, this value is true.

RegEx (ready)

Whether the regular expression evaluates to true or false, the value that you can use to insert the regular expression into any Configuration wizard text box is shown in this field. Copy and paste it as needed. References to the case-insensitive or global flags are inserted. For example, the case-insensitive flag is added to the expression in the following manner: "flags": "i".

Specifying regular expressions for test data Use RegEx tester to specify regular expressions for test data. For more information about regular expression flags, see https:// developer.mozilla.org/en- US/docs/JavaScript/Reference/Global_Objects/RegExp. 1. Start the RegEx Tester. 2. Enter the regular expression to test. 3. Insert your sample data to apply in the test. Use data specific to your web application, such as a sample request. 4. Click Test. If a match is found for the regular expression in the test sample data, the Matches value is true. 5. Enter the value from the RegEx (read for copy & paste) box the Configuration wizard text box. Copy and paste this value as needed. 6. When you are finished testing, close the RegEx Tester.

56

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Configuring settings and features with the Configuration wizard You use the Configuration wizard to configure settings and features for CX UI Capture SDK. The configuration process is iterative. You start with one setting or feature, configure the properties that you want and then verify with the Replay team that everything is working. Then, move on to the next feature or setting. You configure Browser, Queue, Message, Serializer, and Encoder services that the SDK uses. Then, you configure the features that you want to use in your application, Performance, DOM Capture, and Geolocation. The Configuration wizard is in the installation package. You must download and install the package before you can run the wizard. The file for the Configuration wizard is configwizard.html As you complete each step, verify with the Replay team that the settings you entered work. You must know which options you want to configure and the modules and settings that you want to enable: To configure the...

You must know...

Browser service

The browser service that you want to use, either jQuery or W3C You also need to know whether you want to specify any additional options: v jQuery object (jQuery only) v Sizzle URL (W3C only) v Sizzle object (W3C only) v Blacklist elements v Custom attributes v Links to exclude

Queue service

The queue information: v Target page URL v Max Size of the queue, in messages v Timer interval to flush the queue irrespective of the number of messages. v Max Size (serialized queue length), for the length of the serialized queue, at which point the queue is flushed. v Whether to check the Target page availability when the UIC initializes. v If you are testing the Target page availability, the time, in milliseconds, to wait for a response from the Target page before the UIC shuts down. You also need to know whether you need to enable cross-domain POST messages or asynchronous XHR on page unload.

Chapter 3. Configure UI Capture basic settings

57

To configure the...

You must know...

Message service

The number and type of privacy masks that you want to configure. For each mask you need the: v MaskType v Target v ID v IDTypes

58

Serializer

Whether you want to use a built-in parser or serializer if none is available. You can add more than on serializer and more than 1 parser.

Encoder

Whether you want to enable the gzip encoder service.

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

To configure the...

You must know...

Modules

The modules for the features that you want to enable. For the Performance module, which provides data for the Performance reports, you need to know whether you want to: v Specify a render time threshold v Disable any of the performance data filters For the Replay module, which determines which events and messages are used by Replay, you need to know whether you want to: v Disable capturing Mobile events. v Disable screenview messages from hashchange v Disable scroll and window size tracking You also need to know whether you want to record a Custom Event. You can use a custom event to trigger a DOM capture. If you are configuring DOM capture to trigger after the frames on a page load, you configure a Replay custom "load" event called "loadWithFrames". Configuring the "loadWithFrames" event will cause the UIC to record a screenview load message with screenview name: "rootWithFrames" when the same-origin frames/iframes on the page have finished loading. The screenview "rootWithFrames" can be used as a trigger for performing a DOM Capture. To create a custom event, you need to know: 1. Name of the event 2. Target for the event 3. State for the event For SaaS applications, you need to know whether SaaS is using Tealeaf Cookies for sessionization. If the Tealeaf Cookies are used, enter a "TLTSID" as the cookie name and the Tealeaf App Key. Contact the Tealeaf SaaS administrator if you do not know the Tealeaf App Key.

Chapter 3. Configure UI Capture basic settings

59

To configure the...

You must know...

DOM Capture

For DOM Capture, you need to know whether: 1. You want to specify a Max Length threshold for snapshots and what the threshold is. 2. Frames are captured. 3. To remove scripts. 4. To use events to trigger DOM Capture. Remember if you want to capture a page after frames and iframes are loaded, configure a "load" trigger for the "rootWithFrames" screenview. This trigger works with the custom Replay event "loadWithFrames" that you created in the Replay module. 5. Whether you are going to use DOM Diff or full DOM Capture. Note: This information pertains to functionality available in IBM Tealeaf UI Capture version 5.0.0. For information about the release, contact your IBM Tealeaf representative. At replay time, the method of capture (DOM, DIFF, or Network) is listed in Capture field in the Page statistics banner of the BBR user interface.

Geolocation

Whether to enable collecting geographic location information. When you enable capturing geographic location information, the information is collected only if the device user gave the app permission to use location data.

Miscellaneous settings

For Miscellaneous settings you need to know whether: v You want to Blacklist frames and the names of the frames. v You want to share session data. v Cookies are used for sessionization. v Query Parameters are used for sessionization. v Value needs to be hashed to derive the Session ID.

1. Start either a Chrome or Firefox browser. 2. In the browser, open the configwizard.html file. 3. Configure the browser services on the Browser Service Configuration page: a. Navigate to the Browser Service Configuration page. b. Select the browser service that you want to use, either jQuery or W3C c. Enter information for any Advanced Options that you want to configure. d. Verify that the browser service that you configured is working. If the settings are not working, repeat the configuration steps and modify the information until the settings work.

60

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

4. Configure the queue services on the Queue Service Configuration page: a. Navigate to the Queue Service Configuration page. b. Enter the queue name. c. Enter the queue size, in messages. d. Enter the target page URL. e. Leave the Timer Interval set to 0. f. Enter the Max Size (serialized queue length), if you want the queue to be flushed when the serialized queue length meets or exceeds the specified size. Leave the Max Size set to 0 if you do not want to use this setting. g. Indicate whether to test the Target page availability when the UIC initializes. Default is enabled. h. If you are testing the Target page availability, enter the time to wait for a response from the Target page. i. Enter information for any Advanced Options that you want to configure. j. Click Finish. k. Verify that the Queue Services that you configured are working. If the settings are not working, repeat the configuration steps and modify the information until the settings work. 5. Configure the message service privacy masking on the Message Service Configuration page: a. Navigate to the Message Service Configuration page. b. Enter the HTML ID, XPath, or Custom Attribute ID ('attrName=attrValue') of the element that is masked. c. Enter the ID Type. d. Enter a single CSS selector string. e. Enter the Mask Type for how the value is transformed. f. Click Finish. g. Verify that the Message Services Privacy Masking that you configured is working. If the settings are not working, repeat the configuration steps and modify the information until the settings work. 6. Configure the serializers on the Serializer page: Navigate to the Serializer page. Leave the Use built-in parser/serializer if none available option selected. Enter the parser functions that the SDK uses. Enter the serializer functions that the SDK uses. Click Finish. Verify that the serializers and parsers that you configured are working. If the settings are not working, repeat the configuration steps and modify the information until the settings work. 7. Enable the encoder Service on the Encoder page: a. Navigate to the Encoder page. b. Select Enable to enable encoder services. c. Click Finish. d. Verify that the encoder services are working. If the settings are not working, repeat the configuration steps and modify the information until the settings work. 8. Configure the feature Modules that you want to use on the Modules page: a. Navigate to the Modules page. a. b. c. d. e. f.

Chapter 3. Configure UI Capture basic settings

61

b. Select the boxes for the modules that you want to enable. A checked box means that the module is enabled. c. Optional: For Performance Settings, use the Advanced Options to set how the Render Time is calculated for the Render Time reports, enter a renderTimeThreshold for excluding data outliers, and to turn off any predefined metrics that you do not want to capture. d. Optional: For the Replay module, use the advanced settings to: v Disable capturing Mobile events. v Disable screenviews from hashchange v Disable scroll and window size tracking If you want to create a custom event: 1) Define the event. 2) Define the trigger or state. To trigger a DOM capture after frames are loaded on a page, create a custom "load" event for "loadWithFrames". e. Indicate whether you are using the TLFCookie module. Enter the cookie name and Tealeaf App Key. f. Click Finish. g. Verify that the feature modules that you configured work. If the modules are not working, repeat the configuration steps and modify the information until the modules work. 9. Optional: On the DOM Capture page, enable DOM Capture and specify the capture options that you want: a. Navigate to the DOM Capture page. b. Indicate whether you want to enable DOM Capture. If you enable DOM Capture, use the advanced options to tune the DOM Capture feature: 1) Indicate whether you want to capture child Frames or iFrames. 2) Indicate whether you want to remove scripts from the captured snapshots. 3) Disable or enable the DOM diff service. Default is enabled. 4) Enter the Max Length threshold for snapshots 5) If you want to use events to trigger DOM Captures: a) Select the Event trigger. If you created a custom event in the Replay section, that event appears on the list of events. For example, to configure DOM captures to happen after frames are loaded, create a "load" trigger. b) Enter the screenview for the trigger. For example, to configure DOM captures to happen after frames are loaded, enter a "rootWithFrames" for the screenview. c) If you want to delay the capture for the triggered event, specify the delay time in milliseconds. c. Click Finish. d. Verify that the configuration you entered works. If DOM Capture is not working, repeat the configuration steps and modify the information until DOM Capture works. 10. Optional: Enable Geolocation logging on the Geolocation page: a. Navigate to the Geolocation page. b. Indicate whether you want to enable Geolocation. c. Click Finish.

62

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

d. Verify that the geolocation logging works. 11. Configure more settings on the Miscellaneous Settings page: a. Navigate to the Miscellaneous Settings page. b. Enter the CSS selectors of frames to exclude from data collection. c. Indicate whether session data is shared. d. Indicate whether cookies are used for sessionization. e. Indicate whether a query parameter is used for sessionization. f. If you are using cookies for sessionization, enter the cookie name. g. Indicate whether the cookie name needs to be hashed to derive the session ID. h. Click Finish. i. Verify that the miscellaneous settings are working. If the settings are not working, repeat the configuration steps and modify the information until the settings work. 12. When you are done configuring services, modules, and settings, exit the Configuration wizard.

Capturing gestures in your application To capture gestures in your application, you add the gesture library to the configuration file that you installed in the application that you are developing. You also add the hammer.js library to the application that you are developing. After you add the libraries to your application, you can use the default gesture events that are installed with Tealeaf. You can also customize the default gesture events by adding Options to the gesture events. If your customer base uses Internet Explorer 8, do not load hammer.js in your application. Hammer.js does not support Internet Explorer 8. The hammer.js library is not included in the Tealeaf installation package. Download the hammer.js library from the GitHub site. Tealeaf supports only hammer.js 1.1.x. 1. Configure gestures by adding the gestures module to the defaultconfiguration.js file. For example: "core": { "modules": { "gestures": { "events": [{ "name": "tap", "target": "window" }, { "name": "hold", "target": "window" }, { "name": "drag", "target": "window" }, { "name": "pinch", "target": "window" }, { "name": "release", "target": "window" }], } } }, "modules": { "gestures": { Chapter 3. Configure UI Capture basic settings

63

"options": { doubleTapInterval: 300 } } }

2. Install the hammer.js library in the application that you are developing. 3. Set the window.innerWidth for your page. For example, .

Configuring DOM Capture and Replay for Hybrid applications You complete the configuration of DOM capture for Hybrid applications by adding .domcapture to the events in your application that you want to be captured. Before you do this task you must: v Install the UIC library v Run the Configuration wizard and enable DOM Capture v Set the DOM Capture options that you want. You can specify targets for your events. This specification is the same as configuring the module events. The targets can be specified by their IDs (HTML, XPATH, or CUSTOM) or by a CSS selector. If no target is specified, DOM Capture is triggered on each event instance. For load and unload events, you can specify the screenview names. If no screenview name is specified, then the DOM Capture is triggered for each event occurrence. In all cases, you can optionally use the delay parameter to specify a delay in milliseconds after which the DOM snapshot is taken. 1. Locate the event that you want to capture. For example, click, change, load, or unload. 2. Optional: Specify a set of targets. 3. Optional: Specify screenview names if you are configuring a load or unload event. 4. Optional: Specify a delay in milliseconds for the DOM capture to wait the snapshot is taken. This example shows how to configure DOM Capture to trigger whenever the user clicks an element with id "xyz" or any element with CSS class "domcapture". Since delay is specified, the actual DOM snapshot will be taken ~500 milliseconds after the click event. { event: "click", targets: [ { id: "xyz", idType: -1 }, ".domcapture" ], delay: 500 }

This example specifies that a DOM snapshot is taken on each change event irrespective of the target element.

64

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

{ event: "change" }

This example specifies that a DOM snapshot is taken when there is a screenview load event for "root" or "payment" screenviews. The snapshot will be taken after ~500-millisecond delay. { event: "load", screenviews: [ "root", "payment" ], delay: 500 }

Configuring DOM Capture and Replay for Native Android applications that cannot use PCA You configure DOM capture for a Native iOS application that cannot use PCA by modifying the defaultconfiguration.js file. If the HTML page in the webview does not fire on page load or if the page changes dramatically, you need to fire DOM capture from within your Native Android application. Before you do this task you must install the UIC library in your native application. All of the modifications that you make are in your Native Android application. 1. Modify the defaultconfiguration.js file and set the DOM Capture options that you want to use: replay: { // DOM Capture configuration domCapture: { enabled: true, // Filter object for matching rules is 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. triggers: [ { event: "load" } ], // DOM Capture options options: { captureFrames: true, // Should child frames/iframes be captured removeScripts: true // Should script tags be removed from the captured snaphot } } }

2. If DOM Capture does not fire on load, set DOM Capture to fire from your application by adding this code to your Native Android application for the screenview that you want to capture: if (TLT === undefined) { console.log(’TLT is undefined!’); } else { if (TLT.logScreenviewLoad === undefined) { console.log(’Could not invoke TLT.logScreenviewLoad API!’); } else { TLT.logScreenviewLoad("root"); console.log(’logScreenviewLoad:’); } Chapter 3. Configure UI Capture basic settings

65

if (TLT.logDOMCapture === undefined) { console.log(’Could not invoke TLT.logDOMCapture API!’); } else { dcid = TLT.logDOMCapture(window.document, {}); console.log(’logDOMCapture:’ + dcid); } }

Configuring DOM Capture and Replay for Native iOS applications that cannot use PCA You configure DOM capture for a Native iOS application that cannot use PCA by modifying the defaultconfiguration.js file. If the HTML page in the webview does not fire on page load or if the page changes dramatically, you need to fire DOM capture from within your Native iOS application. Before you do this task you must install the UIC library in your native application. All of the modifications that you make are in your Native iOS application. 1. Implement these methods in the UIWebViewDelegate: (void)webViewDidFinishLoad:(UIWebView *)webView { [[TLFCustomEvent sharedInstance] logScreenLayoutWithViewController:self]; } - (BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest: (NSURLRequest *)request navigationType: (UIWebViewNavigationType)navigationType { return YES; }

2. Modify the defaultconfiguration.js file and set the DOM Capture options that you want to use: replay: { // DOM Capture configuration domCapture: { enabled: true, // Filter object for matching rules is 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. triggers: [ { event: "load" } ], // DOM Capture options options: { captureFrames: true, // Should child frames/iframes be captured removeScripts: true // Should script tags be removed from the captured snapshot } } }

3. If DOM Capture does not fire on load, set DOM Capture to fire from your application by adding this code to your native iOS application for the screenview that you want to capture:

66

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

if (TLT === undefined) { console.log(’TLT is undefined!’); } else { if (TLT.logScreenviewLoad === undefined) { console.log(’Could not invoke TLT.logScreenviewLoad API!’); } else { TLT.logScreenviewLoad("root"); console.log(’logScreenviewLoad:’); } if (TLT.logDOMCapture === undefined) { console.log(’Could not invoke TLT.logDOMCapture API!’); } else { dcid = TLT.logDOMCapture(window.document, {}); console.log(’logDOMCapture:’ + dcid); } }

4. Optional: If the webview has images that are slow to load, you can add a delay to the DOM Capture with this method: -(void)webViewDidFinishLoad:(UIWebView *)webView { [[TLFCustomEvent sharedInstance] logScreenLayoutWithViewController:self andDelay:0.2]; }

Chapter 3. Configure UI Capture basic settings

67

68

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Chapter 4. UI Capture usage guidelines This chapter provides guidelines for successful implementation and use of IBM Tealeaf UI Capture . In parallel with your process for developing the web application, plan to deploy IBM Tealeaf UI Capture as early as possible in the development process for the following reasons. v Early deployment limits the potential for issues that are discovered in a production environment. v Early deployment provides an opportunity to monitor application problems and help debug the application. These guidelines apply to all deployments of IBM Tealeaf UI Capture . Different options can apply to different web application types.

Application scope IBM Tealeaf UI Capture supports specific browsers, application types, and protocols. For a list of supported browsers, see Supported Browsers.

Supported application types In general, rich internet application (RIA) functionality must be limited to only the areas of your web application that require it. RIA requires more sophisticated monitoring techniques and can increase the volume of traffic that IBM Tealeaf must process. IBM Tealeaf supports the following rich internet application types: v Ajax Note: IBM Tealeaf continues to support existing customers who deployed Flash or Flex applications. IBM Tealeaf does not support new customers who use these technologies. Note: Currently, IBM Tealeaf does not support UI capture and replay of multiple Flex or Flash applications on the same page. This limitation does not include multimedia content applications that do not require IBM Tealeaf UI capture or replay. If your application requires multiple Flex or Flash RIAs on the same page, each of which must be captured for replay, contact IBM Professional Services. Note: IBM Tealeaf supports applications that use text-based data formats for communicating with the server. If your application uses binary data formats such as AMF, contact IBM Professional Services.

Supported protocols IBM Tealeaf supports HTTP and HTTPS for request and response communication between client and server.

© Copyright IBM Corp. 1999, 2015

69

Verify that all Ajax send and receive communications are managed by HTTP or HTTPS. The protocol of the client events is the same as the request that sent the page to the browser. If the client events must be sent by HTTPS, verify that the source page is delivered by HTTPS. Captured form field values are transmitted in the same protocol in which the form page is transmitted to the server. If your form page is transmitted by HTTPS, the form field values are encrypted, too. Note: IBM Tealeaf does not currently support any other protocols, such as HTTP streaming, HTTP push, or non-HTTP protocols such as RTMP. Verify that your application does not use non-HTTP/HTTPS protocols.

Before you begin development Before you begin your IBM Tealeaf UI Capture development initiatives, verify that the following information is available or was captured.

IBM Tealeaf access If possible, deploy the web application on a server that is accessible to IBM Tealeaf developers. To effectively debug issues, IBM Tealeaf developers must have access to the application.

Third-party content The following guidelines apply to third-party content.

Third-party domains IBM Tealeaf cannot capture content that is managed by third-party domains. In a typical deployment, most of this content is not integral to application performance and can be re-requested at replay time without impacting overall application replay. If capture of dynamic versions of this content is required, contact IBM Professional Services.

Third-party plug-ins Other than the Flash player, IBM Tealeaf does not currently support the replay of third-party plug-ins in Rich Internet Applications, such as Silverlight or Java™ applets.

Personnel Personnel in the following roles need to be available to IBM Tealeaf for the UI Capture deployment. Role

Description

Application architect During deployment, IBM Tealeaf can make requests to the web application architect to identify locations in the application for calls to the IBM Tealeaf API. This individual is also useful for answering technical questions. Business analyst From the business perspective, it is important to know which areas of the application require monitoring and to what degree. This knowledge

70

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

directly translates into which UI elements, events, clicks, and other aspects of the application must be captured by IBM Tealeaf. During development, this individual might be able to identify qualified use cases for IBM Tealeaf UI Capture .

External resources If application development is outsourced to a third-party, provide access to this team. IBM Tealeaf can work within any constraints for contracting external development teams.

Development considerations During the development process, keep in mind the following considerations.

Development cycle IBM Tealeaf assumes that the following basic production stages are in place. v Development v Testing v Production For more information about development goals during each of the stages, see Chapter 2, “UI Capture installation and implementation,” on page 33.

When to deploy UI Capture during development IBM Tealeaf recommends deploying IBM Tealeaf UI Capture as early as possible in your development process. In addition to curtailing the number of issues in a Production environment, UI Capture can be useful for debugging issues with the application development process itself. Your web application and UI Capture can work hand-in-hand to deliver a better overall result. For example, changes to the client-side application, such as changes to the element identifiers, additions or modifications of UI widgets can impact capture and replay of the client-side UI. Identifying these changes via IBM Tealeaf UI Capture in a Development environment facilitates faster resolution and a better replay experience once the application is deployed in the Production environment. You can also use IBM Tealeaf UI Capture privacy rules configuration to identify and protect sensitive client data before deployment to the live site. By including IBM Tealeaf as part of the main development effort for your web application, UI Capture can be integrated into the change management and scheduled maintenance processes for your enterprise.

Development and Test environments Where possible, configure all Development or Testing environments to mirror the Production environment. Apply the same web server settings and permissions that are configured in the Production server to the Development environment or Test environments. Note: Never deploy IBM Tealeaf UI Capture directly into a Production environment. Chapter 4. UI Capture usage guidelines

71

Performance management Integrate IBM Tealeaf UI Capture into the Performance Management test suite for your enterprise. Performance measurement of IBM Tealeaf UI Capture JavaScript can help in configuring the size and frequency of the UI Capture posts.

Application content When developing your web application, keep in mind the following considerations.

Unique identifiers All user interface elements of the web application must have unique identifiers. Where possible, implement the application with unique identifiers for each UI element. If unique identifiers are not available, IBM Tealeaf relies on XPath identifiers. However, this solution might not be 100% accurate, and use of XPaths can increase the size of each UI Capture message and the total cost of storing the data. Note: IBM Tealeaf UI Capture does not automatically check for uniqueness of identifiers. Non-unique identifiers must be blacklisted manually through the configuration.

Dynamically transmitted GUIDs If the application generates client-side dynamic GUIDs that are transmitted over the network, replay of captured sessions can be affected. Timestamps and changes in application behavior due to user agent, visitor locale, and other dynamic factors can have effects on replay. Depending on the variations, effective replay might require IBM Professional Services to develop complex rules to match the dynamically generated POST data, remap server hosts, and more. Note: Wherever possible, avoid client-side dynamically generated identifiers. While dynamic identifiers can be tracked by IBM Tealeaf, managing them is another layer of complexity in configuration.

Do not use Document Object Model keywords as form field names This requirement is best illustrated by example. The following is a specification of an HTML form that contains three input fields, the name of which uses the HTML and Document Object Model keywords action, type, and tagName.

When UI Capture attempts to report the standard properties (such as type, action, or tagName) of the form node on which a user event occurred, the value is typically

72

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

a defined string or an undefined or null value. In this case, the target is a form element, whose input field names are exported by the browser as properties of the form object. As a result, the form's action, type, and tagName properties refers to the respective input field, which is an object. Any JavaScript that attempts to access one of these native properties retrieves the input field object instead. Note: Do not use any reserved Document Object Model keyword as the name of a form field.

Application objects The following sections describe aspects of the application you are developing and how they might affect IBM Tealeaf UI Capture . In general, do not cancel JavaScript events in your application. Allow all events of child elements to bubble up to the document's root element.

Ajax v Where possible, do not use anchor tags as the value on which to change Ajax driven views, modals, or fly-out windows. v In Ajax calls, do not make the request parameters or response data difficult to review and analyze. Create a request body that clearly shows what is being requested and where it is placed in the root document. The same applies to the response. v For Ajax calls that result in updates to the page in the form of new user input elements such as drop-down lists or text boxes, IBM Tealeaf needs to be notified so that user interactions with these newly inserted elements can be captured. The UI Capture library provides a simple API for this purpose.

Custom UI controls Note: Capture and replay of custom UI controls might require a custom solution. For more information, contact IBM Professional Services.

HTTP cache control headers Depending on your visitors' browser settings, UI Capture JavaScript might be stored in the local cache for a lengthy period. If you deploy an updated version of UI Capture , your visitors' browsers might still pull the UI Capture JavaScript from the local cache, which can cause significant problems if configuration changes were required for UI Capture to work with your application. To manage this potential problem, use HTTP cache control headers for your web server and configuring the use of conditional HTTP requests through the standard Last-Modified HTTP header. Any updates to the UI Capture files on the server are automatically propagated by the HTTP caching mechanism. Note: HTTP caching requires more configuration and can cause issues if not configured properly. Consult with your IT staff before you enable these changes. Note: If you cannot make the configuration changes to your web server, you might be able to manage updates by placing a date stamp in the file name of the IBM Tealeaf UI Capture files, such as tealeaf_110310.js. However, these file name changes must be coordinated with your web development team and do not always trigger correct caching behavior. Chapter 4. UI Capture usage guidelines

73

References: v http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13 v http://httpd.apache.org/docs/2.1/caching.html

Private data IBM Tealeaf provides many options for managing data privacy throughout the capture, replay, and reporting functions. Data can be blocked or masked through UI Capture , at the point of capture in the CX Passive Capture Application, or by using the Privacy session agent in the pipeline on the Processing Server. Identify the data that requires privacy early in the development process and test your privacy configuration in the Development and Testing environments. Where possible, seek to minimize the volume of data that requires privacy management. Note: When UI Capture data is blocked or masked by using IBM Tealeaf privacy, replay can break if the web application is not designed to accept the altered content. v For more information about how IBM Tealeaf secures data, see "Managing Data Privacy in Tealeaf CX" in the IBM Tealeaf CX Installation Manual.

Frequency of posts IBM Tealeaf enables the configuration of the size and frequency of POSTs to the IBM Tealeaf target page. v During Development, you can send small and frequent POSTs so that you can monitor activities at a granular level. v In a Production environment, minimize the number of POSTs, each of which has a data overhead. Note: Ideally, the trigger for sending each POST in a Production environment is the maximum size of the post. The size and frequency of these posts can be configured by parameter to control: v The maximum allowed number of events in the buffer. If this maximum is exceeded, the queued events are posted. v A timer value for periodic flushing of the event queue, regardless of the buffer size

UI events overridden by UI Capture In some implementations, IBM Tealeaf can be configured to override specific user interface events. Verify that there is no conflict between the IBM Tealeaf overrides and events that are used or monitored by your application. See Chapter 2, “UI Capture installation and implementation,” on page 33.

74

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

UI Capture deployment Placement of UI Capture For best results, place the UI Capture configuration file at the beginning of the page in the HTML head section. Placement in other sections of the page is also supported. See Chapter 2, “UI Capture installation and implementation,” on page 33.

JavaScript The following guidelines apply to working with JavaScript.

Modifications Avoid changing any IBM Tealeaf configuration settings unless you are sure of the reasons for the change and its effects. Some options can have significant effects on performance.

Commenting Monitor any changes to the JavaScript files by adding detailed comments. Periodically, IBM Tealeaf provides updates to the JavaScript files, and integrating these changes with the changes for your company is easier with thorough commenting.

Special functions Verify that special page-level functions are not overwritten. These functions include onload, onunload, and onreadystatechange. If overwriting is required, then always "pass on" the call. For example: if( typeof document.onreadystatechange == "function" ) { document.originalReadyStateChange = document.onreadystatechange; } else { document.originalReadyStateChange = null; } document.onreadystatechange = function() { // Do my work here // Call the original ReadyStateChange if(document.originalReadyStateChange) { document.originalReadyStateChange(); } };

Create custom events By default, IBM Tealeaf UI Capture monitors user interactions with the application by capturing the standard Document Object Model events. IBM Tealeaf UI Capture can also be used to monitor specific aspects of the application such as client-side performance metrics, client-side input validation messages, and any other data relevant to the application.

Chapter 4. UI Capture usage guidelines

75

To capture these aspects and other client-side activity, the application developer can use a simple IBM Tealeaf API to notify the library of any data that must be included in the IBM Tealeaf POST. Custom events are best implemented in a centralized location where the application processes its input validation or performance metrics, for example. Note: Creating custom events to insert data in submissions to IBM Tealeaf increases the volume of data that is stored for each session. Create custom events only for business-critical data. Sending large volumes of UI data increases network traffic and storage requirements within IBM Tealeaf and might affect application performance. See Chapter 6, “UI Capture Public API Reference,” on page 129.

JSON message type schemas and examples JSON messages are categorized by type for processing. Tealeaf supports 12 JSON message types.

Message header properties All messages contain message header properties consisting of two properties that contain the message type and the time that is offset from the start of the session in milliseconds. All time measurements in the JSON object schema are in milliseconds.

Message list This table lists and describes the supported JSON message types: Table 9. Schema by Message Type

76

Type

Message Type

Description

1

“Client state (Type 1) messages” on page 78

Any object that shows the current state of client.

2

“ScreenView (Type 2) messages” on page 81

Any message that indicates changes in view on the "screen". The "screen" is the page, view, or activity where the visitor is in the application.

3

“Connections (Type 3) messages” on Any request or response that the page 83 application performs during capture.

4

“Control (Type 4) messages” on page User interface control that fires an 84 event to which Tealeaf listens for capture.

5

“Custom Event (Type 5) messages” on page 87

Any custom log event from any location in application.

6

“Exception (Type 6) messages” on page 88

Any exception that the application can throw.

7

“Performance (Type 7) messages” on Performance data from a browser. page 89

8

“Web Storage (Type 8) messages” on Any object that contains information page 90 about local storage information on the browser.

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Table 9. Schema by Message Type (continued) Type

Message Type

Description

9

“Overstat Hover Event (Type 9) messages” on page 91

Any object that contains information about mouse hover and hover-to-click activity.

10

“Layout (Type 10) messages” on page 91

Any message that shows the current display layout of a native page.

11

“Gesture (Type 11) messages” on page 94

Any message that shows a gesture that fires a higher touch event that Tealeaf listens to for capture.

12

“DOM Capture (Type 12) message example” on page 105

Any object that contains serialized HTML data (DOM snapshot) of the page.

13

“GeoLocation (Type 13) messages” on page 107

Messages that contain the geolocation information about the device.

Message header properties All messages contain message header properties consisting of two properties that contain the message type and the time that is offset from the start of the session in milliseconds. All time measurements in the JSON object schema are in milliseconds.

Message header properties schema This example shows the schema for the JSON message headers. "offset": { "title": "Milliseconds offset from start of stream", "type": "integer", "required": true },"screenViewOffset": { "title": "Milliseconds offset from start of ScreenView", "type": "integer", "required": true },"count": { "title": "The number of the message being sent", "type": "integer", "required": only used for UIC },"fromWeb": { "title": "Used to identify if it came from Web or Native application", "type": "boolean", "required": true },"webviewId": { "title": "Used to identify which webview it came from. This is only used when fromWeb is true and it is a hybrid application ", "type":"string", "required": true only when fromWeb is true and it is a hybrid application },"type": { "title": "Message header type", "type": [ { "enum": [1], description: "CLIENT_STATE" }, "enum": [2], description: "APPLICATION_CONTEXT" }], "enum": [3], description: "CONNECTION" }, Chapter 4. UI Capture usage guidelines

77

"enum": [4], description: "CONTROL" }, "enum": [5], description: "CUSTOM_EVENT" }], "enum": [6], description: "EXCEPTION" }], "required": true },

Message header properties schema This example shows the schema for the JSON message headers. "offset": { "title": "Milliseconds offset from start of stream", "type": "integer", "required": true },"screenViewOffset": { "title": "Milliseconds offset from start of ScreenView", "type": "integer", "required": true },"count": { "title": "The number of the message being sent", "type": "integer", "required": only used for UIC },"fromWeb": { "title": "Used to identify if it came from Web or Native application", "type": "boolean", "required": true },"webviewId": { "title": "Used to identify which webview it came from. This is only used when fromWeb is true and it is a hybrid application ", "type":"string", "required": true only when fromWeb is true and it is a hybrid application },"type": { "title": "Message header type", "type": [ { "enum": [1], description: "CLIENT_STATE" }, "enum": [2], description: "APPLICATION_CONTEXT" }], "enum": [3], description: "CONNECTION" }, "enum": [4], description: "CONTROL" }, "enum": [5], description: "CUSTOM_EVENT" }], "enum": [6], description: "EXCEPTION" }], "required": true },

Client state (Type 1) messages Client state messages are delivered on a schedule basis or on changes to the environment state on the client. These are Type 1 JSON messages.

78

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Note: Replay of client state messages is not supported, except for scroll events. Replay of scroll events that are captured from the client is supported for mobile sessions only in BBR only. See Search and Replay for Mobile Web.

Client State (Type 1) message schema This is the schema for the Client State (Type 1) messages. { "$ref" : "MessageHeader", "mobileState": { "description": "Logical page being loaded for iOS and Android", "type": "object", "properties": { "orientation": { "title": "Current orientation of the device", "type": "integer", "required": true }, "freeStorage": { "title": "Amount of available storage in Mbytes", "type": "number", "required": true }, "androidState": { "description": "Current state in an Android device", "type": "object", "properties": { "keyboardState": { "title": "Current keyboard state", "type": [ { "enum": [0], description: "Keyboard not hidden" }, "enum": [1], description: "Keyboard hidden" }, "enum": [2], description: "Undefined" }], "required": true }, } }, "battery": { "title": "Battery level from 0 to 100", "type": "number", "required": true }, "freeMemory": { "title": "Amount of available memory in Mbytes", "type": "number", "required": true }, "connectionType": { "title": "Current connection type", "type": "string", "required": true }, "carrier": { "title": "Carrier of device", "type": "string", "required": true }, "networkReachability": { "title": "Current network reachability", "type": [ { "enum": [0], Chapter 4. UI Capture usage guidelines

79

description: }, "enum": [1], description: }, "enum": [2], description: }, "enum": [3], description:

"Unknown" "NotReachable" "ReachableViaWIFI" "ReachableViaWWAN"

}], "required": true }, "ip": { "title": "Ip address of device", "type": "string", "required": true } }, "additionalProperties" : false "clientState": { "description": "Logical web page being loaded for UIC", "type": "object", "properties": { "pageWidth": { "title": "Width of the document of the web page", "type": "integer", "required": true }, "pageHeight": { "title": "Height of the document of the web page", "type": "integer", "required": true }, "viewPortWidth": { "title": "Width of viewport", "type": "integer", "required": true }, "viewPortHeight": { "title": "Height of viewport", "type": "integer", "required": true }, "viewPortX": { "title": "x position of scrollbar on viewport", "type": "integer", "required": true }, "viewPortY": { "title": "y position of scrollbar on viewport", "type": "integer", "required": true }, "event": { "title": "event that triggered the client state", "type": "string", "required": true }, "deviceScale": { "title": "scaling factor for fitting page into window for replay", "type": "integer", "required": true }, "viewTime": { "title": "time in milliseconds user was on the event triggered",

80

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

"type": "integer", "required": true }, "viewPortXStart": { "title": "initial start x position of scrollbar on viewport", "type": "integer", "required": only used in scroll events }, "viewPortYStart": { "title": "initial start y position of scrollbar on viewport", "type": "integer", "required": only used in scroll events }, }, "additionalProperties" : false } }

Client State (Type 1) message example This is an example of a Client State (Type 1) message. This example comes from an Android native application. { "offset": 667, "screenViewOffset": 4556, "type": 1, "mobileState": { "orientation": 0, "freeStorage": 33972224, "androidState": { "keyboardState": 0 }, "battery": 50, "freeMemory": 64630784, "connectionType": "UMTS", "carrier": "Android", "networkReachability": "ReachableViaWWAN", "ip": "0.0.0.0" } }

ScreenView (Type 2) messages ScreenView messages indicate steps in a visitor's experience with your application. These steps can be logical page views in a web application, screen changes in a mobile application, or steps in a business process. ScreenView messages are Type 2 JSON messages. In Release 8.5 and earlier, these messages were called Application Context messages.

ScreenView (Type 2) message schema This is the schema for the ScreenView (Type 2) JSON messages. { "$ref" : "MessageHeader", "dcid": { "title": "Unique identifier that is used to match the corresponding DOM Capture message associated with this message.", "type": "string", "required": false }, "screenview/context": { "description": "Logical page being loaded or unloaded", "type": "object", Chapter 4. UI Capture usage guidelines

81

"properties": { "type": { "title": "Type of application context - LOAD or UNLOAD", "type": "string", "required": true }, "name": { "title": "Name of the logical page. This is given by customer or it uses name of the class used by the page.", "type": "string", "required": true }, "url": { "title": "URL path of the logical page", "type": "string", "required": false only used in UIC }, "host": { "title": "URL Host of the logical page", "type": "string", "required": false only used in UIC }, "referrer": { "title": "Previous logical page loaded, only used in LOAD", "type": "string", "required": false }, "referrerUrl": { "title": "Url of the previous logical page loaded", "type": "string", "required": false, not used in UIC } }, "additionalProperties" : false, "required": false } }

ScreenView (Type 2) message example This is an example of a ScreenView (Type 2) message. This example contains three ScreenView messages, indicating page load and page unload events. { "offset": 124, "contextOffset": 4556, "type": 2, "context": { "type": "LOAD", "name": "PAGE 2", "referrer": "PAGE 1" } } { "type": 2, "offset": 19216 "context": { "type": "UNLOAD", "name": "PAGE 2" } } { "type": 2, "offset": 2144,

82

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

"contextOffset": 0, "count": 9, "fromWeb": true, "webviewId": "webview1", "screenview": { "type": "LOAD", "name": "Ford", "url": "/dynamic/ford.aspx", "host": "http://www.cartest.com", "referrer": "BMW", "referrerUrl": "/dynamic/bmw.aspx" } }

Connections (Type 3) messages Connection messages provide information about how requests or responses are managed by the client application. Connections messages are Type 3 JSON messages.

Connections (Type 3) messages schema This is the schema for Connections (Type 3) JSON messages. { "$ref" : "MessageHeader", "connection": { "description": "Connection in application", "type": "object", "properties": { "statusCode": { "title": "Status code of connection", "type": "integer", "required": true }, "responseDataSize": { "title": "Response data size", "type": "number", "required": true }, "initTime": { "title": "Initial time of connection", "type": "number", "required": true }, "responseTime": { "title": "Response time of connection", "type": "number", "required": true }, "url": { "title": "Url of connection", "type": "string", "required": true }, "loadTime": { "title": "Load time from connection", "type": "number", "required": true } }, "additionalProperties" : false } }

Chapter 4. UI Capture usage guidelines

83

Connections (Type 3) message example This example shows the Connections (Type 3) JSON message. { "offset": 03829, "type": 3, "screenViewOffset": 45560, "type": 3, "connection": { "statusCode": 200, "responseDataSize": 0272, "initTime": 01333669478556, "responseTime": 02237, "url": "http://google.com", "url": "/store/js/tealeaf/ TeaLeafTarget.php??width=540&height=960&orientation=0", "loadTime": 0 } }

Control (Type 4) messages Control messages are used to log user action and behavior. These messages consist of a control identifier and a value that is returned by the identified control. Control messages are Type 4 JSON messages. The control identifiers are mapped to specific controls for the submitting client framework. The value can be a number, a text string, or structured data.

Control (Type 4) message schema This is the schema for Control (Type 4) messages. The X and Y properties are not present in the UI Capture frameworks. { "$ref" : "MessageHeader", "offset": { "title": "Milliseconds offset from offset for when focusIn of text fields occur", "type": "integer", "required": true }, "target": { "description": "Control being logged", "type": "object", "properties": { "position": { "description": "Position of control being logged", "type": "object", "properties": { "x": { "title": "X of the control", "type": "integer", "required": true }, "y": { "title": "Y of the control", "type": "integer", "required": true }, "height": { "title": "height of control", "type": "integer", "required": true }, "width": {

84

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

"title": "width of control", "type": "integer", "required": true }, "relXY": { "title": "relative X & Y ratio that can be from 0 to 1 with a default value of 0.5", "type": "string", "required": true for click events }, }, "additionalProperties" : false } "id": { "title": "Id/Name/Tag of control", "type": "string", "required": true }, idType": { "title": "Indicates what id is based on: Native id (e.g. HTML ’id’ attribute): -1, xPath: -2, or Custom attribute for UIC and Hashcode value for Native: -3, or xPath for Native iOS/Android: -4", "type": "integer", "required": true }, "dwell": { "title": "Dwell time of control", "type": "integer value that is in milliseconds", "required": false }, "visitedCount": { "title": "Number of times a form control has been visited to be filled by user.", "type": "integer", "required": false }, "isParentLink": { "title": "To indicate if control a A type tag", "type": "boolean", "required": false only in UIC for usability }, "name": { "title": "Name of control", "type": "string", "required": true in UIC }, "type": { "title": "Type of control", "type": "string", "required": true }, "subType": { "title": "SubType of control", "type": "string", "required": true }, "tlType": { "title": "tlType of control that normalizes the control type for eventing", "type": "string", "required": true }, "prevState": { "title": "Previous state of control", "type": "object", Chapter 4. UI Capture usage guidelines

85

"required": true, "properties": { "?": { // Could be any variable name given by developer "title": "Additional data in string format", "type": "string", "required": false } }, "currState": { "title": "Current state of control", "type": "object", "required": true, "properties": { "?": { // Could be any variable name given by developer "title": "Additional data in string format", "type": "string", "required": false } } }, "additionalProperties" : false } "event": { "description": "Event from control", "type": "object", "properties": { "tlEvent": { "title": "Tealeaf type of event", "type": "string", "required": true }, "type": { "title": "Type of event", "type": "string", "required": true }, "subType": { "title": "Subtype of event", "type": "string", "required": true } }, "additionalProperties" : false } }

Control (Type 4) message example This is an example of a Control (Type 4) message. This example shows a control with an idType of XPATH, which means no id was assigned to the control in the application so Tealeaf traversed the layout and created an XPATH id for the control:, { "screenviewOffset":380, "target":{ "id":"[KV,0]", "position":{ "y":331, "x":0, "width":320, "height":202 }, "idType":"-4", "currState":{ "y":"0",

86

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

"x":"0" }, "style":{ "paddingTop":2, "textBGAlphaColor":255, "bgAlphaColor":255, "paddingBottom":0, "paddingLeft":0, "hidden":false, "paddingRight":0 }, "subType":"View", "type":"KeyboardView", "tlType":"keyboard" }, "type":4, "offset":728, "count":3, "fromWeb":false, "event":{ "type":"UIKeyboardDidShowNotification", "tlEvent": "kbDisplayed" } },

Custom Event (Type 5) messages The Custom Event messages are used to custom log any event from any place in the application. Custom Event messages are Type 5 JSON messages.

Custom Event (Type 5) message schema This is the schema for the Custom Event (Type 5) messages. The only required field is the name of the custom event (name value). Application-specific code must be created to process this logged message type. { "$ref" : "MessageHeader", "customEvent": { "description": "Custom event message", "type": "object", "properties": { "name": { "title": "Exception name/type", "type": "string", "required": true }, "data": "Additional properties given by developer", "type": "object", "required": truefalse, "properties": { "?": { // Could be any variable name given by developer "title": "Additional data in string format", "type": "string", "required": false } }, }, "additionalProperties" : false } }

Chapter 4. UI Capture usage guidelines

87

Custom Event (Type 5) message example This is an example of a Custom Event (Type 5) message. This custom event message provides the name of the custom event (MyEvent_1) and several custom properties in the data section. { "type": 5, "offset": 17981, "screenViewOffset": 4556, "customEvent": { "name": "MyEvent_1", "data": { "Foo": "Bar", "validationError": "Invalid zipcode.", "ajaxPerformance": 56734 } } }

Exception (Type 6) messages The exceptions messages type records the name and description of an exception occurring on the client application. Exception messages are Type 6 JSON messages.

Exception (Type 6) message schema This is the schema for the Exception (Type 6) messages. { "$ref" : "MessageHeader", "exception": { "description": "Exception description message", "type": "object", "properties": { "description": { "title": "Exception message from api call", "type": "string", "required": true }, "name": { "title": "Exception name/type", "type": "string", "required": true, not for UIC }, "stackTrace": { "title": "Exception stacktrace given by framework", "type": "string", "required": true, not for UIC }, "url": { "title": "Url where exception ocurred", "type": "string", "required": true for UIC }, "fileName": { "title": "File name where exception ocurred", "type": "string", "required": true for iOS, not for UIC }, "line": { "title": "Line number where eception occurred.", "type": "string", "required": true for UIC and iOS }, "unhandled": { "title": "Whether exception had a try catch around it.", "type": "boolean", "required": true, not for UIC

88

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

}, "data": { "title": "User defined data being passed with user info from system", "type": "object", "required": true for iOS, not for UIC "properties": { "userInfo": { "type": "object", "title": "OS information from error or exception", "required": iOS optional (data is JSON serializable or not) }, "message": { "type": "string", "title":"User supplied message on error event", "required":iOS optional (not on exceptions required on error) } }, }, }, "additionalProperties" : false } }

Exception (Type 6) message example This is an example of an Exception (Type 6) message. This example exception indicates an attempt to read a property named 'type' of a variable or value which is undefined. { "type" : 6, "offset" : 4606, "screenviewOffset" : 4603, "count" : 3, "fromWeb" : true, "exception" : { "description" : "Uncaught TypeError: Cannot read property ’type’ of undefined", "url" : "http://www.xyz.com/js/badscript.js", "line" : 258 } }

Performance (Type 7) messages Performance messages show performance data from a browser. Performance messages are Type 7 JSON messages.

Performance (Type 7) message schema This is the schema for Performance (Type 7) messages. { "$ref" : "MessageHeader", "performance": { "description": "Performance message", "type": "object", "properties": {

Chapter 4. UI Capture usage guidelines

89

}, "additionalProperties" : false } }

Performance (Type 7) message example This is an example of a Performance (Type 7) message. { "type": 7, "offset": 9182, "screenviewOffset": 9181, "count": 3, "fromWeb": true, "performance": { "timing": { "redirectEnd": 0, "secureConnectionStart": 0, "domainLookupStart": 159, "domContentLoadedEventStart": 2531, "domainLookupEnd": 159, "domContentLoadedEventEnd": 2551, "fetchStart": 159, "connectEnd": 166, "responseEnd": 1774, "domComplete": 2760, "responseStart": 728, "requestStart": 166, "redirectStart": 0, "unloadEventEnd": 0, "domInteractive": 2531, "connectStart": 165, "unloadEventStart": 0, "domLoading": 1769, "loadEventStart": 2760, "navigationStart": 0, "loadEventEnd": 2780, "renderTime": 986 }, "navigation": { "type": "NAVIGATE", "redirectCount": 0 } } }

Web Storage (Type 8) messages Web Storage messages are any objects that contain information about local storage information on the browser. Web Storage messages are Type 8 JSON messages.

Web Storage (Type 8) message schema This is the schema for the Web Storage (Type 8) messages. "$ref" : "MessageHeader", webStorage: { key : “string”, value: “string”, }

Web Storage (Type 8) message example This is an example of a Web Storage (Type 8) message. { type: 8, offset: 25, screenviewOffset: 23,

90

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

count: 2, fromWeb: true, webStorage: { key: "vistCount" value: "5" } }

Overstat Hover Event (Type 9) messages Overstat Hover Event messages are any object containing information about mouse hover and hover-to-click activity. Overstat Hover Event messages are Type 9 JSON messages.

Overstat Hover Event (Type 9) message schema This is the schema for Overstat Hover Event (Type 9) messages "$ref" : "MessageHeader", event: { xPath: "string", hoverDuration: int, hoverToClick: boolean, gridPosition: { x: int, y: int } }

Overstat Hover Event (Type 9) message example This is an example of a Overstat Hover Event (Type 9) message. { type: 9, offset: 25, screenviewOffset: 23, count: 2, fromWeb: true, event: { xPath: "[\"ii\"]", hoverDuration: 5457, hoverToClick: false, gridPosition: { x: 3, y: 2 } }

Layout (Type 10) messages Layout messages show the current display layout of a native page. Layout messages are Type 10 JSON messages.

Layout (Type 10) message schema This is the schema for Layout (Type 10) messages. "$ref" : "MessageHeader", "version": { "description": "Message Version, must be in x.x format", "type": "string", "required": true }, "layoutControl": { "description": "Control on application page", "type": "object", "properties": { "position": { Chapter 4. UI Capture usage guidelines

91

"description": "Position of control", "type": "object", "properties": { "x": { "title": "X of the control", "type": "integer", "required": true }, "y": { "title": "Y of the control", "type": "integer", "required": true }, "height": { "title": "height of control", "type": "integer", "required": true }, "width": { "title": "width of control", "type": "integer", "required": true } }, "additionalProperties" : false } "id": { "title": "Id/Name/Tag of control", "type": "string", "required": true }, "type": { "title": "Type of control", "type": "string", "required": true }, "subType": { "title": "SubType of control", "type": "string", "required": true }, "tlType": { "title": "tlType of control that normalizes the control type for eventing", "type": "string", "required": true }, "currState": { "title": "Current state of control", "type": "object", "required": true, "properties": { "?": { // Could be any variable name given by developer "title": "Additional data in string format", "type": "string", "required": false } } }, "style" : { "title": "Style of the control", "type": "object", "required": true, "properties": { "textColor": { "title": "Text color", "type": "string", "required": true

92

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

}, "textAlphaColor": { "title": "Text alpha color", "type": "string", "required": true }, "textBGColor": { "title": "Text background color", "type": "string", "required": true }, "textBGAlphaColor": { "title": "Text background alpha color", "type": "string", "required": true }, "bgColor": { "title": "Background color", "type": "string", "required": true }, "bgAlphaColor": { "title": "Background alpha color", "type": "string", "required": true } } } }, "additionalProperties" : false }

Layout (Type 10) message example This is an example of a Layout (Type 10 ) message. { "offset": 27004, "screenviewOffset": 4706, "count": 16, "fromWeb": false, "type": 10, "version" : "1.0", "orientation" : 0, "deviceHeight": 592, "deviceWidth": 360, "layout": { "name": "loginPage", "class": "loginPageActivty", "controls": [ { "position": { "y": 38, "height": 96, "width": 720, "x": 0 }, "id": "com.tl.uiwidget:id\/userNameLabel", "idType": -1, "type": "UILabel", "subType": "UIView", "tlType": "label", "currState": { "text": "User name*" }, "style": { "textColor": 16777215, Chapter 4. UI Capture usage guidelines

93

"textAlphaColor": 1, "textBGColor": 0, "textBGAlphaColor": 0, "bgColor": 0, "bgAlphaColor": 0 } }, {...}, {...} ] } }

Gesture (Type 11) messages Gesture messages are used to log user action and behavior. A Gesture message consists of a control identifier and a the value returned by that control. The control identifiers are mapped to specific controls on the client logging platform. The value can be a number, a text string or structured data. Gesture messages are Type 12 JSON messages.

Gesture (Type 11) message schema This is the schema for Gesture (Type 11) messages.

Touch events This is a JSON object that represents a gesture finger that is linked to control underneath the finger. It is reused in targets property of gesture type 11.This is the schema for touch events: { "$ref" : "MessageHeader", "focusInOffset": { "title": "Milliseconds offset from offset for when focusIn of text fields occur", "type": "integer", "required": false }, "target": { "description": "Control being logged", "type": "object", "properties": { "position": { "description": "Position of control being logged", "type": "object", "properties": { "x": { "title": "X of the control", "type": "integer", "required": true }, "y": { "title": "Y of the control", "type": "integer", "required": true }, "height": { "title": "height of control", "type": "integer", "required": true }, "width": { "title": "width of control", "type": "integer", "required": true

94

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

}, "relXY": { "title": "relative X & Y ratio that can be from 0 to 1 with a default value of 0.5", "type": "string", "required": true for click events }, "scrollX": { "title": "scroll X of the page", "type": "integer", "required": true }, "scrollY": { "title": "scroll Y of the page", "type": "integer", "required": true }, }, "additionalProperties" : false } "id": { "title": "Id/Name/Tag of control", "type": "string", "required": true }, "idType":{ "title": "Indicates what id is based on: Native id (e.g. HTML ’id’ attribute): -1, xPath: -2, or Custom attribute for UIC and Hashcode value for Native: -3, or xPath for Native iOS/Android: -4", "type": "integer", "required": true }, "dwell": { "title": "Dwell time of control", "type": "integer value that is in milliseconds", "required": false }, "focusInOffset": { "title": "Offset when control got focus", "type": "integer value that is in milliseconds", "required": true in UIC }, "visitedCount": { "title": "Number of times a form control has been visited to be filled by user.", "type": "integer", "required": false }, "isParentLink": { "title": "To indicate if control a A type tag", "type": "boolean", "required": false only in UIC for usability }, "name": { "title": "Name of control", "type": "string", "required": true in UIC }, "type": { "title": "Type of control", "type": "string", "required": true }, "subType": { Chapter 4. UI Capture usage guidelines

95

"title": "SubType of control", "type": "string", "required": true }, "tlType": { "title": "tlType of control that normalizes the control type for eventing", "type": "string", "required": true }, "prevState": { "title": "Previous state of control", "type": "object", "required": false, "properties": { "?": { // Could be any variable name given by developer "title": "Additional data in string format", "type": "string", "required": false } } }, "currState": { "title": "Current state of control", "type": "object", "required": true, "properties": { "?": { // Could be any variable name given by developer "title": "Additional data in string format", "type": "string", "required": false } } } }, "additionalProperties" : false } "event": { "description": "Event from control", "type": "object", "properties": { "tlEvent": { "title": "Tealeaf type of event", "type": "string", "required": true }, "type": { "title": "Type of event", "type": "string", "required": false }, "subType": { "title": "Subtype of event", "type": "string", "required": false } }, "additionalProperties" : false }}

Tap event schema This contains only one touch object. This is the schema for tap events: { "$ref" : "MessageHeader", "event": {

96

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

"description": "Event from control", "type": "object", "properties": { "tlEvent": { "title": "Tealeaf type of event", "type": "string", "required": true }, "type": { "title": "Type of event framework reports", "type": "string", "required": false } } }, "touches": { "description": "Gestures touch objects per finger.", "type": "array", "required": true "items": { "description": "Touch objects per finger starting with intial and ends with last object when finger is lifted from device.", "type": "array", "required": true, "$ref": "Touch" } } } }

Swipe event schema The swipe event contains only one touch object which will be the initial location with its corresponding direction and velocity. This is the schema for swipe events: { "$ref" : "MessageHeader", "event": { "description": "Event from control", "type": "object", "properties": { "tlEvent": { "title": "Tealeaf type of event", "type": "string", "required": true }, "type": { "title": "Type of event framework reports", "type": "string", "required": false } } }, "touches": { "description": "Gestures touch objects per finger.", "type": "array", "required": true "items": { "description": "Touch objects per finger starting with intial and ends with last object when finger is lifted from device.", "type": "array", "required": true, "$ref": "Touch" } } }, "direction": { Chapter 4. UI Capture usage guidelines

97

"title": "The direction of the swipe which can be up, down. left or right.", "type": "string", "required": true }, "velocityX": { "title": "The velocity of this measured in pixels per second along the x axis", "type": "float", "required": true }, "velocityY": { "title": "The velocity of this measured in pixels per second along the y axis", "type": "float", "required": false } }

Pinch events The pinch event contains only an initial touch object per finger and the last touch object per finger, with the corresponding direction. This is the schema for pinch events: { "$ref" : "MessageHeader", "event": { "description": "Event from control", "type": "object", "properties": { "tlEvent": { "title": "Tealeaf type of event", "type": "string", "required": true }, "type": { "title": "Type of event framework reports", "type": "string", "required": false } } }, "touches": { "description": "Gestures touch objects per finger.", "type": "array", "required": true "items": { "description": "Touch objects per finger starting with intial and ends with last object when finger is lifted from device.", "type": "array", "required": true, "$ref": "Touch" } } }, "direction": { "title": "Direction of pinch which can be open or close", "type": "string", "required": true } }

Gesture (Type 11) message example These are examples of UIC SDK Gesture (Type 11) messages.

98

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Tap events This example is a gesture message for a tap event: { "fromWeb": false, "type": 11, "offset": 46788, "screenviewOffset": 42208, "count": 14, "event": { "type": "ACTION_DOWN", "tlEvent": "tap" }, "touches": [ [ { "position": { "x": 179, "y": 543 }, "control": { "position": { "height": 184, "width": 1080, "relXY": "0.17,0.93" "scrollX": 10 "scrollY": 15 }, "id": "[RL,0]", "idType": -4, "type": "RelativeLayout", "subType": "ViewGroup", "tlType": "canvas" } } ] ] }

Double tap events This example is a gesture message for a double tap event: { "fromWeb": false, "type": 11, "offset": 49585, "screenviewOffset": 45005, "count": 15, "event": { "type": "ACTION_DOWN", "tlEvent": "doubleTap" }, "touches": [ [ { "position": { "x": 182, "y": 520 }, "control": { "position": { "height": 184, "width": 1080, "relXY": "0.17,0.8" "scrollX": 10 Chapter 4. UI Capture usage guidelines

99

"scrollY": 15 }, "id": "[RL,0]", "idType": -4, "type": "RelativeLayout", "subType": "ViewGroup", "tlType": "canvas" } } ] ] }

Tap hold events This example is a gesture message for a tap hold event: { "fromWeb": false, "type": 11, "offset": 52389, "screenviewOffset": 47809, "count": 16, "event": { "type": "ACTION_DOWN", "tlEvent": "tapHold" }, "touches": [ [ { "position": { "x": 182, "y": 536 }, "control": { "position": { "height": 184, "width": 1080, "relXY": "0.17,0.89" "scrollX": 10 "scrollY": 15 }, "id": "[RL,0]", "idType": -4, "type": "RelativeLayout", "subType": "ViewGroup", "tlType": "canvas" } } ] ] }

Swipe event example The swipe event contains only one touch object which will be the initial location with its corresponding direction and velocity. This example is a message for a swipe event: { "fromWeb": false, "type": 11, "offset": 54409, "screenviewOffset": 49829, "count": 17, "event": {

100

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

"type": "ACTION_DOWN", "tlEvent": "swipe" }, "direction": "right", "velocityX": 7762.8466796875, "velocityY": 127.47991943359375, "touches": [ [ { "position": { "x": 75, "y": 538 }, "control": { "position": { "height": 184, "width": 1080, "relXY": "0.07,0.9" "scrollX": 10 "scrollY": 15 }, "id": "[RL,0]", "type": "RelativeLayout", "subType": "ViewGroup", "tlType": "canvas" } }, { "position": { "x": 212, "y": 526 }, "control": { "position": { "height": 184, "width": 1080, "relXY": "0.2,0.84" "scrollX": 10 "scrollY": 15 }, "id": "[RL,0]", "idType": -4, "type": "RelativeLayout", "subType": "ViewGroup", "tlType": "canvas" } } ] ] }

Pinch events The pinch event contains only an initial touch object per finger and the last touch object per finger, with the corresponding direction. This example is a message for a pinch event: { "type": 11, "offset": 2220, "screenviewOffset": 2022, "count": 6, "fromWeb": false, "event": { "tlEvent": "pinch", "type": "onScale" }, Chapter 4. UI Capture usage guidelines

101

"touches": [ [ { "position": { "y": 388, "x": 0 }, "control": { "position": { "height": 100, "width": 100, "relXY": "0.6,0.8" "scrollX": 10 "scrollY": 15 }, "id": "com.tl.uic.appDarkHolo:id/imageView1", "idType": -1, "type": "ImageView", "subType": "View", "tlType": "image" } }, { "position": { "y": 388, "x": 400 }, "control": { "position": { "height": 100, "width": 100, "relXY": "0.4,0.7" "scrollX": 10 "scrollY": 15 }, "id": "com.tl.uic.appDarkHolo:id/imageView1", "idType": -1, "type": "ImageView", "subType": "View", "tlType": "image" } } ], [ { "position": { "y": 388, "x": 800 }, "control": { "position": { "height": 100, "width": 100, "relXY": "0.6,0.8" "scrollX": 10 "scrollY": 15 }, "id": "com.tl.uic.appDarkHolo:id/imageView1", "idType": -1, "type": "ImageView", "subType": "View", "tlType": "image" } }, { "position": { "y": 388,

102

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

"x": 500 }, "control": { "position": { "height": 100, "width": 100, "relXY": "0.4,0.7" "scrollX": 10 "scrollY": 15 }, "id": "com.tl.uic.appDarkHolo:id/imageView1", "idType": -1, "type": "ImageView", "subType": "View", "tlType": "image" } } ] ], "direction": "close" }

DOM Capture (Type 12) messages DOM Capture messages are objects that contain serialized HTML data (DOM snapshot) of the page. DOM Capture Messages are Type 12 JSON messages.

DOM Capture (Type 12) message schema This is the schema for the DOM Capture (Type 12) messages. "$ref" : "MessageHeader", "domCapture": { "description": "Serialized HTML snapshot of the document.", "type": "object", "properties": { "dcid": { "title": "Unique identifier of this DOM snapshot.", "type": "string", "required": true } "fullDOM": { "title": "Flag indicating if the contents of this message contain a full DOM or a DOM diff.", "type": "boolean", "required": false }, "charset": { "title": "Browser reported charset of the document.", "type": "string", "required": false }, "root": { "title": "Serialized HTML of the document.", "type": "string", "required": false }, "diffs": { "title": "List of DOM diff entries. Each entry can contain a HTML Diff or an attribute diff.", "type": "array", "required": false, "Item": { "title": "An object containing the DOM diff. The diff can be a HTML diff or an attribute diff.", "type": "object", "required": false, "properties": { Chapter 4. UI Capture usage guidelines

103

"xpath": { "title": "The xpath of the node.", "type": "string", "required": true }, "root": { "title": "Serialized HTML of the node referred by the xpath. Presence of this property constitutes a HTML diff.", "type": "string", "required": false }, "attributes": { "title": "List of attribute diff entries. Each entry contains a single attribute diff corresponding to the node referred by the xpath. Presence of this property constitutes an attribute diff.", "type": "array", "required": false, "Item": { "title": "An object containing the attribute diff.", "type": "object", "required": true, "properties": { "name": { "title": "The attribute name.", "type": "string", "required": true }, "value": { "title": "The attribute value.", "type": "string", "required": true } } } } } } }, "eventOn": { "title": "Flag indicating if Tealeaf eventing should be enabled for this DOM Capture snapshot.", "type": "boolean", "required": false }, "url": { "title": "URL path of the snapshot document", "type": "string", "required": false }, "host": { "title": "URL Host of the snapshot document", "type": "string", "required": false }, "error": { "title": "Error message", "type": "string", "required": false }, "errorCode": { "title": "Error code corresponding to the error message.", "type": "integer", "required": false }, "frames": {

104

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

"title": "Serialized HTML of any child frames of the document", "type": "array", "required": false, "Item": { "title": "An object containing serialized HTML of the frame", "type": "object", "required": false, "properties": { "tltid": { "title": "Unique identifier for this frame. Same tltid is added to the serialized HTML source of the parent." "type": "string", "required": true }, "charset": { "title": "Browser reported charset of the document.", "type": "string", "required": true }, "url": { "title": "URL path of the snapshot document", "type": "string", "required": true }, "host": { "title": "URL Host of the snapshot document", "type": "string", "required": true }, "root": { "title": "Serialized HTML of the document.", "type": "string", "required": true } } } }, "canvas" : { "title": "Serialized data of the canvas snapshot.", "type": "array", "required": false, } }, "additionalProperties" : false }

DOM Capture (Type 12) message example This is an example of a DOM Capture (Type 12) message. This example shows a DOM message with full DOM capture enabled: { // DOM Capture messages use type 12 "type": 12, // The standard UIC message properties "offset": 16821, "screenviewOffset": 16817, "count": 5, "fromWeb": true,

Chapter 4. UI Capture usage guidelines

105

"domCapture": { "dcid": "dcid-3" "fullDOM":true "charset": "ISO-8859-1", "root": " ", "host": "http://www.uictest.com", "url": "/h4/dcTest.html", "eventOn": true, "frames": [ { "tltid": "tlt-4", "root": "Hello, World!", "charset": "ISO-8859-1", "host": "http://www.uictest.com", "url": "/h4/greeting.html" } ], "canvas": [] } }

This example shows a DOM capture message with DOM diff enabled: { "type": 12, "offset": 13874, "screenviewOffset": 13861, "count": 6, "fromWeb": true, "domCapture": { "fullDOM": false, "diffs": [ { "xpath": "[[\"html\",0],[\"body\",0],[\"div\",1]]", "root": "Input 1" } ], "dcid": "dcid-3.1437256358764", "eventOn": false } }

DOM Diff (with HTML and attribute diff): { "type": 12, "offset": 5794, "screenviewOffset": 5777, "count": 8, "fromWeb": true, "domCapture": { "fullDOM": false, "diffs": [ { "xpath": "[[\"html\",0],[\"body\",0],[\"div\",2],[\"div\",1]]", "root": "Select List:12 3" }, { "xpath": "[[\"cb1\"]]", "attributes": [ {

106

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

"name": "style", "value": "height: 13px; width: 13px; visibility: hidden;" } ] }, { "xpath": "[[\"container_1\"],[\"table\",0],[\"tbody\",0], [\"tr\",2],[\"td\",1],[\"select\",0]]", "attributes": [ { "name": "style", "value": "visibility: hidden;" } ] } ], "dcid": "dcid-3.1437256879815", "eventOn": false } }

This example shows the error message when the captured DOM message length exceeds the configured threshold: { // DOM Capture messages use type 12 "type": 12, // The standard UIC message properties "offset": 16821, "screenviewOffset": 16817, "count": 5, "fromWeb": true, // The DOM Capture data is namespaced in the domCapture object "domCapture": { // The "error" contains the verbose error message explaining why the DOM Capture couldn’t be performed. "error": "Captured length (18045) exceeded limit (10000).", // The "errorCode" contains the numeric code for this error message. Currently, there is only 1 error message. "errorCode": 101, // The "dcid" property contains the unique string identifying this DOM Capture within the page instance. "dcid": "dcid-1.1414088027401" } }

GeoLocation (Type 13) messages A GeoLocation message logs a user's location information. The message consists of a control identifier and a GeoLocation value. If the user has given the permission to use location data, GeoLocation returns latitude, longitude, accuracy values. If the user has not given permission to use location data, GeoLocation returns an error code and error string.

GeoLocation (Type 13) message schemas This is the schema for the GeoLocation (Type 13) JSON messages: This is the schema for messages from a device that the user has given permission to use location data:

Chapter 4. UI Capture usage guidelines

107

"$ref" : "MessageHeader", "geolocation": { "lat": double, "long": double, "accuracy": float }

This is the schema for messages from a device that the user has not given permission to use location data: "$ref" : "MessageHeader", "geolocation": { "errorCode": int, "error": "string", }

GeoLocation (Type 13) message examples This is an example of the GeoLocation (Type 13) JSON message. This is an example of a message from a device that the user has given permission to use location data: {

"type": 13, "geolocation": { "lat": 37.5680, "long": -122.3292, "accuracy": 65 }

}

This is an example of a message from a device that the user has not given permission to use location data: {

"type": 13, "geolocation": { "errorCode": 201, "error": "permission denied", }

}

Examples this example shows a session that contains two messages, a Screenview (Type 2) and a Custom Event (Type 5). { "serialNumber": 0, "messageVersion": "0.0.0.1", "sessions": [ { "startTime": 1328311295574, "id": "945202AC4E93104E05EDADE1F6059B97", "messages": [ { "offset": 124, "screenViewOffset": 4556, "type": 2, "logicalPageName": "HomeActivity" }, { "offset": 667, "screenViewOffset": 66778, "type": 1, "mobileState": { "orientation": 0, "freeStorage": 33972224, "androidState": {

108

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

"keyboardState": 0 }, "battery": 50, "freeMemory": 64630784, "connectionType": "UMTS", "carrier": "Android", "networkReachability": "ReachableViaWWAN", "ip": "0.0.0.0" } }, { "customEvent": { "name": "Screenshot Taken for file: HomeActivity_1328311296341.jpg" }, "offset": 855, "screenViewOffset": 4556, "type": 5 } ] } ], "clientEnvironment": { "mobileEnvironment": { "android": { "keyboardType": "QWERTY", "brand": "generic", "fingerPrint": "generic/sdk/generic/ :2.2/FRF91/43546:eng/test-keys" }, "totalMemory": 63422464, "totalStorage": 12288, "orientationType": "PORTRAIT", "appVersion": "1.0.5", "manufacturer": "unknown", "userId": "android-build", "locale": "English (United States)", "deviceModel": "sdk", "language": "English" }, "width": 0, "height": 0, "osVersion": "2.2" } }

Next steps For extra information about specific practices to apply to your web application development and IBM Tealeaf UI Capture implementation, contact IBM Professional Services.

Chapter 4. UI Capture usage guidelines

109

110

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Chapter 5. UI Capture reference The IBM 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. v Core configuration object: Contains configuration information about Document Object Model events to which the library listens. See “Core configuration.” v 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” on page 117. v Modules configuration object: Contains configuration information about the modules that are enabled in the library. See “Modules configuration object” on page 124. 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 IBM Tealeaf UI Capture library listens. TLT.init({ /** * Base configuration for the core. * It specifies which modules should listen to which events and the * moduleBase to dynamically load additional modules * @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 */ ieExcludedLinks: ["a.ignore"], /** * 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 } ] }, © Copyright IBM Corp. 1999, 2015

111

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 */ /**

112

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

* Set the sessionDataEnabled flag to true only if it’s 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 IBM Tealeaf. For more information, contact IBM Professional Services.

Internet Explorer links 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.

Chapter 5. UI Capture reference

113

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 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.ignore", "a.foo span"],

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: v name identifies the W3C name of the user interface event. v 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 IBM 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.

114

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Replay The replay module provides the underlying data in form of JSON messages that enable features such as: v Rich Internet Application (RIA) Replay: Browser Based Replay and CX RealiTea Viewer. v IBM Tealeaf cxOverstat usability functionality; heatmaps, form analytics, and attention maps. See "cxOverstat User Manual" in the IBM Tealeaf cxOverstat User Manual. v Step-based eventing. See "Step-Based Eventing" in the IBM Tealeaf Event Manager Manual. 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.

Chapter 5. UI Capture reference

115

Property

Description

"hashchange"

When enabled, this option generates screen view events when a hash change was identified in the URL of the page. v A screenview is defined as a change in state for the overall page. For example, if a page has multiple tabs, each tab can be defined as a separate screen view for the page. v When this option is enabled, a screen view event is inserted in the session data, and UI events that are captured by UI Capture can be organized beneath the screen view on which they occurred. v See Tealeaf JSON Object Schema Reference. v If your web application does not use screen views, disable this option.

"resize"

Resize events on the client. See Tealeaf JSON Object Schema Reference.

"scroll"

Scroll events on the client. See Tealeaf JSON Object Schema Reference. 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. See Search and Replay for Mobile Web.

"orientationchange"

Orientation change events for mobile devices. See Tealeaf JSON Object Schema Reference. These events are replayed only if you licensed IBM Tealeaf CX Mobile. For more information, contact your IBM Tealeaf representative.

"touchend"

Touch end events for mobile devices. See Tealeaf JSON Object Schema Reference. These events are replayed only if you licensed IBM Tealeaf CX Mobile. For more information, contact your IBM Tealeaf representative. Pinch and zoom gestures can be captured on the iOS platform only. They cannot be captured on the Android platform.

Support for all of these replay events is provided in Browser-Based Replay only. See "CX Browser Based Replay" in the IBM Tealeaf cxImpact User Manual.

116

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

A subset of replay events might work in the CX RealiTea Viewer. See "RealiTea Viewer - Replay View" in the IBM Tealeaf CX RealiTea Viewer User Manual.

Services configuration The Services configuration object contains options that are used by the individual services that are part of the IBM 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" } },

Chapter 5. UI Capture reference

117

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. Note: 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 IBM 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 IBM 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 interval in milliseconds at which event queues are flushed automatically. If this option is not present or is set to 0, the timer is disabled. Note: Keep this setting disabled, unless a more immediate flushing of data is required, such as when IBM Tealeaf users are shadow-browsing a visitor's session.

Browser service configuration Through the Browser service configuration, you can specify browser objects and elements that have dynamic or duplicate HTML IDs. browser: { /** * sizzleURL is an URL to the sizzle.js file that contains the * Sizzle library. It is used in some older browsers to get * elements via a CSS selector. * * In such cases, the w3c browserService will conditionally load * this file. * * 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 or * Sizzle is not defined on the window)

118

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

*/ sizzleURL: "/scripts/legacyIESupport/sizzle.js", /** * sizzleObject is the location of the Sizzle object * this setting is not specified, it is assumed that * will be in the global scope. i.e. window.Sizzle * * This setting is only valid when the W3C flavor of * service is selected. * * @type {String} * @optional (only needed for W3C browserService and * is not defined) */ sizzleObject: "My.location.Sizzle",

on the page. If the Sizzle object the browser

if jQuery

/** * 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" ] }, The Sizzle JS engine is required for correct operation of the W3C flavor of the library in legacy browsers (e.g. IE 7) that do not have native support for CSS selector based querys. Sizzle is included in jQuery by default so if the application has a newer version of jQuery, the separate include of Sizzle may not required. The library has multiple ways to specify the location of the Sizzle engine. In order of preference these are: sizzleURL - If specified, this will be used and subsequent mechanisms for locating Sizzle will be ignored. sizzleObject - If specified, this will be used instead of window.Sizzle window.Sizzle jQueryObject - If specified, this will be used instead of window.jQuery window.jQuery

Property Description sizzleURL You can use this configuration item to specify the URL to the sizzle.js file that contains the Sizzle library. This library is used by IBM Tealeaf UI Capture to evaluate CSS selectors on older browsers. Chapter 5. UI Capture reference

119

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. v The Sizzle library is required for some older browsers to acquire document elements that use a CSS selector. If the client browser is one of the affected versions, the W3C browser service can automatically load this file from your web server. v The list of object can be specified as comma-separated values, which can be fixed strings or regular expressions. These values are evaluated against the node ID. 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.

Message service configuration You use the Message service configuration to define options such as privacy rules applied to the JSON messages submitted to the IBM 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"

120

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

* 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 IBM Tealeaf UI Capture enables the blocking and masking of sensitive information within the client browser, before the data is forwarded to IBM 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 IBM Tealeaf, which ensures that your customer's interactions are secure in UI Capture . v UI Capture enables the blocking of user input data by element ID, name, or xpath. v Masks can be expressed as explicit strings, replacements for character types, or custom functions. v For more information about how data privacy is managed throughout the IBM Tealeaf system, see "Managing Data Privacy in Tealeaf CX" in the IBM Tealeaf CX Installation Manual. Note: If you have questions about implementing data privacy in UI Capture , contact IBM Tealeaf Professional Services. To specify a privacy rule, you must define: v The type of identifier. v The targets to which the rule applies. v 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: [ { Chapter 5. UI Capture reference

121

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. v -1 - HTML ID v -2 - xpath identifier v -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 } ] }

122

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Specifying mask type IBM Tealeaf UI Capture supports the following mask types (maskType values): Table 10. Privacy configuration for UI Capture j2 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"

"HelloWorld123

Depends on the defined function

v a lowercase letter is replaced by x. v an uppercase letter is replaced by X. v a numeral is replaced by 9. v a non-alphanumeric value is replaced by @. 4

Custom function Note: A masking function must be defined as maskFunction.

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. Note: 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: Chapter 5. UI Capture reference

123

* { * 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 IBM Tealeaf UI Capture library. These options correspond to the available options of the W3C navigation timing specification. See http://www.w3.org/TR/navigation-timing/#sec-navigation-timing-interface

Performance This code shows the portion of the defaultproperties.js file related to the Performance module options set with the Configuration wizard: 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, requestStart: true, responseStart: true, responseEnd: true, domLoading: true, domInteractive: true, domContentLoadedEventStart: true, domContentLoadedEventEnd: true, domComplete: true, loadEventStart: true, loadEventEnd: true } },

Replay events This code shows the portion of the defaultproperties.js file related to the Replay options set with the Configuration wizard:

124

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

replay: { // Geolocation configuration geolocation: { enabled: false, triggers: [ { event: "load" } ] }, // 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" } ], // DOM Capture options options: { maxLength: 1000000, // If this threshold is exceeded, the snapshot will not be sent captureFrames: true, // Should child frames/iframes be captured removeScripts: true // Should script tags be removed from the captured snapshot } } }

Chapter 5. UI Capture reference

125

Overstat This code shows the portion of the defaultproperties.js file related to the Overstat module options set with the Configuration wizard: overstat: { hoverThreshold: 1000 },

Performance In the Performance section, you configure the client interface events that are tracked for performance metrics.

Filter Using the filters available in the Performance section, you 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 data is not captured, as it can have a significant impact on bandwidth. As a result, the default configuration filters all performance data (performance metric: true). 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.

localStorage configuration Many browsers support localStorage, which is faster and results in larger amount of data stored locally on the user browser. To capture data, you use the UI Capture SDK with localStorage capture to define the keys to be captured. The data is stored in key-value pairs, and a web page can access only data that is stored by itself. The localStorage object stores the data with no expiration date. The data is not deleted when the browser is closed, and is available the next day, week, or year. The IBM Tealeaf UI Capture localStorage captures only white list data. Note: localStorage is not available in the general UI Capture SDK. For localStorage capture, you need a UI Capture SDK with localStorage capture. To configure localStorage, you define a key to be captured. This key is added to the UI Capture configuration. Nothing is captured if no keys are defined. UI Capture only captures keys if you use the getItem() API (for example, localStorage.getItem("xyz")). If you use dot notation nothing is captured (for example. localStorage.xyz). Example:

126

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

modules: { performance: { filter: { } }, replay: { storageKeys: ["x", "y"] } }

IBM Tealeaf UI Capture only captures the keys that you define and their values. UI Capture captures localStorage items when they are accessed (for example, at getItem() call). UI Capture produces a type 8 event. It is then sent the JSON messages back to the server as is. An example of type 8 capture follows. For this example, the localStorage configuration is set to only capture the key usrname. count: 9 fromWeb: true offset: 10585 screenviewOffset: 10585 type: 8 webStorage:{ key: "usrname" value: "ssingh" }

Chapter 5. UI Capture reference

127

128

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Chapter 6. UI Capture Public API Reference The IBM Tealeaf UI Capture library supports the public interfaces that are listed here. In the development builds of the library, several APIs throw exceptions and log the exception to the console when the library is not initiated for API calls that depend on the library. In production builds of the library, the API call fails silently if the library was not initialized. The following APIs throw this exception in development builds. v getSessionData v v v v

logCustomEvent logExceptionEvent logScreenviewLoad logScreenviewUnload

v logScreenCapture

TLT.init(object configObject, /*optional*/ function callbackFunction) This API initializes the IBM Tealeaf UI Capture library with the specified configuration object. init execution occurs after the Document Object Model is loaded. The init call is asynchronous in nature as the library only initializes after the Document Object Model is loaded. The calling code can choose to provide a callback function as a second parameter to this API. The library will invoke the callback function after it initializes. v For static deployments, the call to init can be included as part of the static JavaScript resource. v For dynamic deployments, the call to init can be made from within the customer application.

Example function initializeTealeaf(configObject) { if (TLT && !TLT.isInitialized()) { TLT.init(configObject); } }

TLT.IsInitialized() This API returns true if the UIC library is initialized. Otherwise, it returns false.

Example function logToTealeaf(msg) { if (TLT && TLT.isInitialized()) { TLT.logCustomEvent("customMsg", msg); } /* Else take some other action such as queuing the message for future after Tealeaf is initialized */ }

© Copyright IBM Corp. 1999, 2015

129

TLT.rebind(/*optional*/ DOMElement root) Rebind causes the IBM Tealeaf UI Capture library to reprocess its event listeners. The application can use this API to notify the IBM Tealeaf UI Capture library after the application made a dynamic update that added new user input elements to the Document Object Model. The application can specify an optional root element from which the reprocessing occurs. If not specified, the reprocessing occurs from the document element. In a large and complex Document Object Model, specifying the exact subset that was updated with new user input elements improves efficiency.

Example function callrebind() { TLT.rebind(); }

TLT.flushAll(void) This API causes the buffered data that is gathered by the IBM Tealeaf UI Capture library to be flushed to its configured endpoint URL. Typically, flush is used in combination with the setAutoFlush API call to gain precise control over network usage behavior in highly tuned mobile apps.

Example function callflushAll() { TLT.flushAll(); }

TLT.setAutoFlush(AutoFlushFlag flag) This API is used to enable or disable the automatic flushing behavior of the library. Automatic flushing is enabled by default and is controlled by the configurable queue length. To disable automatic flushing: TLT.setAutoFlush(false)

To enable automatic flushing: TLT.setAutoFlush(true)

Note: When automatic flushing is disabled, it is the application's responsibility to ensure the data that is buffered by the library is flushed out at appropriate intervals by starting the flushAll() API.

TLT.processDOMEvent(DOMEvent event) This API is used to explicitly inform the IBM Tealeaf UI Capture library of any Document Object Model event that the library was configured to listen to but is actively blocked by the application from bubbling.

130

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

In this case, the application or site can make an explicit API call. The argument is the DOMEvent object that is passed by the browser to the event handler. It also applies to similar actions that prevent the UI Capture library from automatically processing the event.

Example $(document).ready(function(){ $( ".disable" ).click(function( event ) { event.preventDefault(); event.stopPropagation(); // Notify Tealeaf if (TLT && TLT.processDOMEvent) { TLT.processDOMEvent(event); } $( "" ).append( "default " + event.type + " prevented" ). appendTo( "#log" ); }); });

TLT.logCustomEvent(DOMString name, object customMsgObj) The application can use this API to log a custom message in to the UI Capture library's message stream. The customMsgObj parameter to this function specifies the object to be serialized and passed as a custom message. The custom message can be processed on the back-end for step-based eventing and reporting. v See "Step-Based Eventing" in the IBM Tealeaf CX Event Manager Manual. v See "Tealeaf Report Builder" in the IBM Tealeaf cxImpact Reporting Guide.

Example function calllogCustomEvent(){ TLT.logCustomEvent("logCustomEvent name", "This is to test the logCustomEvent API"); }

TLT.logExceptionEvent(DOMString msg, /*optional*/ DOMString url, /*optional*/ long line) The application can use this API to log an error or exception message in to the IBM Tealeaf UI Capture library's message stream. Specifying the URL and line number of the error message is optional.

Example function calllogExceptionEventh() { TLT.logExceptionEvent("This is to test the TLT.logExceptionEvent()","/ APITesting/testRebind.html",101); }

Chapter 6. UI Capture Public API Reference

131

TLT.logScreenviewLoad(DOMString name, /*optional*/ DOMString referrerName, /*optional*/ DOMElement root) The application can use this API to log a screen view load message in to the IBM Tealeaf UI Capture library's message stream. Specifying the referring screen view name and the root element for this view is optional.

Example function calllogScreenviewLoad(){ TLT.logScreenviewLoad("logScreenviewLoad name", "This is to test referrerName for logScreenviewLoad", document.getElementById("logScreenviewLoad")); }

TLT.logScreenviewUnload(DOMString name) The application can use this API to log a screen view unload message into the IBM Tealeaf UI Capture library's message stream.

Example function calllogScreenviewUnload(){ TLT.logScreenviewUnload("logScreenviewUnload name"); }

TLT.getSessionData() This API returns an IBM Tealeaf session data object. The IBM Tealeaf session ID information is included in this data. An optional flag indicates if the session ID must be derived by hashing the session value in the object. An example of a returned value follows. { tltSCN: "PHPSESSID", tltSCV: "joese2pun5nus50p45j38hrak5", tltSCVNeedsHashing: true

// Optional

}

To enable this API, the library must be configured with the appropriate configuration settings. These settings inform the library from where the session ID information is to be derived. If the API is not enabled in the configuration or the specified data cannot be read, then null is returned.

Example function getSessionData() { var _sessionData = TLT.getSessionData(); var sessionId = _sessionData.tltSCN; var sessionVal = _sessionData.tltSCV;

132

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

verifySessionData(sessionId, sessionVal) }

TLT.registerBridgeCallbacks This API can be used to register callback functions, which are invoked by the UI Capture library in specific instances. Note: This is an advanced API, which can result in incorrect operation or loss of data if misused. This API should not be used in a hybrid application as the IBM Tealeaf native logging frameworks register and make use of the appropriate bridge callbacks. Currently, three callback types are supported: messageRedirect, screenCapture, and addRequestHeaders.

Example to register a callback TLT.registerBridgeCallbacks([ {enabled: true, cbType: ’screenCapture’, cbFunction: function (){tlBridge.screenCapture();}}, {enabled: true, cbType: ’messageRedirect’, cbFunction: function (data){tlBridge.addMessage(data);}} ])

Where messageRedirectFunc , screenCaptureFunc, andaddRequestHeadersFunc are the callback functions.

messageRedirect This callback can be registered to redirect and intercept messages from the UI Capture. When this callback is registered, the UI Capture library starts the callback function for each message before adding it to the queue. The callback function is passed two parameters: the serialized JSON message and the same message as a JavaScript object. The callback function can consume the message entirely and return null or undefined. In this case, the UI Capture library discards the message. The callback function can also modify the JavaScript object or return it unchanged. In this case, the UI Capture library queues the returned object in its internal queue. This API must not be used in a hybrid application as the IBM Tealeaf native logging frameworks registers and makes use of this bridge callback.

Example of messageRedirectFunc function messageRedirectFunc(msgStr, msg) { // Modify the mousedown type to a click if (msg.type === 4 && msg.event.type === "mousedown") { msg.event.type = "click"; } return msg; }

Chapter 6. UI Capture Public API Reference

133

screenCapture This callback function can be registered to enable a JavaScript API (see logScreenCapture) to allow a screen capture to be taken. The UI Capture library starts the callback function when the logScreenCapture API is started. This API must not be used in a hybrid application as the IBM Tealeaf native logging frameworks registers and makes use of this bridge callback.

Example of screenCapture function register_ScreenShot_Enable_CallBack() { TLT.registerBridgeCallbacks([ { enabled: true, cbType: "screenCapture", cbFunction: myCbFunction } ]); }

addRequestHeaders This callback function can be registered to enable a third party JavaScript to return custom HTTP headers that need to be set on the UI Capture libraries POST request.

Example of addReqHeadersFunc count = 1; function addReqHeadersFunc() { var headers = [ { name: "X-Counter", value: count } ]; if (count === 1) { // Add a recurring header the 1st time. headers.push({ name: "X-Custom-Id, value: customId, recurring: true }); } count++; return headers; }

TLT.logDOMCapture(/*optional*/ DOMElement root, /*optional*/ object configOptions) Use this API for the UI Capture library to log a DOM Capture message. If the root element is not specified, the DOM Capture is performed taking the document as the root. The supported options for this API are: v captureFrames - Whether to capture frames or iframes. Values are true or false. v removeScript - Whether to remove script tags from the capture.

134

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

The API returns a string that serves as the unique id associated with this DOM Capture message. If the DOM Capture feature is disabled or the capture could not be performed for any reason, the API returns null. This example shows how to capture anything within the document body and to remove scripts: // In the following example, the root parameter is the HTML body element. The capture will not // contain anything outside the document body and will also remove any script tags occurring // within the body element. if (TLT && TLT.isInitialized()) { captureId = TLT.logDOMCapture(document.body, { removeScript: true }); }

This example shows how to capture anything within the document body, any iframes, and to remove scripts: // In the following example, the root parameter is left as null which will cause the API to use // the document as the default root. The capture will also include any iframes that are part of the // document and do not violate the same-origin policy of the browser. The capture will remove // any script tags occurring within the document. if (TLT && TLT.isInitialized()) { captureId = TLT.logDOMCapture(null, { captureFrames: true, removeScript: true }); }

TLT.logScreenCapture This API instructs the underlying native functionality to take a screen capture. This functionality is only available when a screenCapture callback is registered with the UI Capture library by the native code.

Example if (TLT && TLT.isInitialized()) { TLT.logScreenCapture(); }

TLT.logGeolocation Use this API to log the Type 13 geolocation messages. The supported options for this API are: This example shows how to call this API to have the UIC request the geolocation information using the W3C Geolocation API and log the result.: if (TLT && TLT.isInitialized()) { TLT.logGeolocation(); }

Or if (TLT && TLT.isInitialized()) { TLT.logGeolocation(position); }

Chapter 6. UI Capture Public API Reference

135

Where position is a object obtained from using W3C Geolocation API getCurrentPosition() function. Refer to the Position interface described in the specification for more information. If the API is called without the standard Position object then the API gets the location using the W3C geolocation interface (if supported by the browser). This API logs a Type 13 JSON GeoLocation message when the device user gives permission to use location data: {

type: 13, geolocation: { lat: 37.788497, long: -122.399935, accuracy: 63 }

}

This API logs a Type 13 JSON GeoLocation message when the device user does not give permission to use location data: {

type: 13, geolocation: { errorCode: 201, error: "Permission denied." }

}

136

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Chapter 7. UI Capture FAQ This section includes frequently asked questions about how to acquire, implement, and use the IBM Tealeaf UI Capture library that is provided by UI Capture . Note: Except as noted, questions and answers in this section apply to IBM Tealeaf UI Capture only.

Getting started What is UI Capture ? UI Capture is a JavaScript library, an example server-side application, and documentation. You use UI Capture to capture the visitor's interactions with the web page (mouse clicks, keyboard input, scroll, and touch interactions, and so on), browser environment (window dimensions, and so on), and performance information (for example, render times). UI Capture collects this information and builds a message that is later posted to a target page on the application server. The target page does not perform any processing and returns an HTTP 200 status. Posting can occur on unload, after a pre-defined time interval, or after the message queue reaches a pre-defined size. Since the IBM Tealeaf core product captures all request and response interactions between the browser and the server, the posted UI Capture data can be used to replay and report on the user interaction occurring within the page.

What versions of UI Capture are available? UI Capture is available in two versions. Beginning in Release 8.6, IBM Tealeaf introduced IBM Tealeaf UI Capture . UI Capture submits data in an updated JSON schema. IBM Tealeaf UI Capture is required for IBM Tealeaf cxOverstat.

Why do I need UI Capture ? UI Capture captures user interactions with an application. Some user experience data only exists in the browser and is never transmitted back to the server. This data includes render times, order of form field entry, form abandonment, and more. Replay of Ajax web applications requires the inclusion of the UI Capture JavaScript to capture the UI events generated as a result of the user interaction with the application. These captured UI events are used to stimulate the application during replay to match the Ajax requests/responses.

How do I implement UI Capture ? The following steps describe the basic process to implement the IBM Tealeaf UI Capture . © Copyright IBM Corp. 1999, 2015

137

1. Determine which pages must be instrumented. Typically, these pages include JavaScript based functionality of interest. For more information, contact http://support.tealeaf.com. 2. Obtain the library from your software distribution. For more information on downloading IBM Tealeaf, see IBM Passport Advantage Online. v For the latest version information, see the Release Notes published on https://community.tealeaf.com/display/public. v You can access IBM Tealeaf Online Help through the Help menu in your IBM Tealeaf Portal. If you know your company login, use the URL above. 3. Review the documentation online or in the PDF supplied with the library. The online documentation is the most up-to-date. 4. Determine the capture options that are required for your web application. These options can vary for different pages on the website. 5. Based on the options you select, modify the JavaScript configuration files that are provided in the library. Note: IBM Tealeaf UI Capture includes a GUI utility to help the configuration of your UI Capture solution. This Configuration Wizard performs data validation and configures the IBM Tealeaf JavaScript depending on your selections. 6. Modify the JavaServer page (.jsp) provided by IBM Tealeaf to meet your requirements. Or, you can choose to replicate it in a different server language, such as ASP or PHP. This page accepts the posts from the IBM Tealeaf JavaScript running on the browser and returns a success code. It does not evaluate or manipulate the received data, which is forwarded to and processed by your IBM Tealeaf system. 7. Modify the pages that call the UI Capture library to include the IBM Tealeaf JavaScript. 8. In a test environment or on a non-production page on your production site, publish the IBM Tealeaf target page, the configured IBM Tealeaf JavaScript, and the modified pages. Note: This environment must be captured by IBM Tealeaf as a separate test environment instance or the production instance that is configured to keep the test traffic separate from your production traffic. 9. Test the web pages to ensure that the addition of the IBM Tealeaf JavaScript interacts correctly with the page. 10. Test the captured traffic on your IBM Tealeaf instance to verify that the UI traffic was captured. In some cases, you modify the replay rules to correctly replay these sessions. If you have any problems, review the documentation or contact http://support.tealeaf.com. 11. After you verify that all instrumented UI elements are being properly captured and processed by IBM Tealeaf, publish the changes to your production environment with your normal publishing and change control processes.

What is the size of UI Capture ? When the UI Capture JavaScript is turned into a production version that is minified and compressed, it is approximately 22K.

138

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Can I bundle the UI Capture library with other JavaScripts? No. Do not combine the UI Capture library with other JavaScripts. IBM Tealeaf recognizes that some customers bundle their JavaScript resources into a single file to simplify deployment of static content. However, due to the following risks and costs that are associated with bundling JavaScripts, IBM Tealeaf does not support bundling.

Risks v The IBM Tealeaf library is mutually independent of any other code that runs in the context of your web application. Maintain this separation as a general policy. v The browser treats each JavaScript include tag as a single unit of execution. When you bundle JavaScripts, a dependency is created between independent libraries. An error in one of the bundled scripts can prevent the other libraries from running. In the worst case scenario, an error in a peripheral script such as IBM Tealeaf can result in an application outage. v If bundling is unavoidable, the customer is responsible for performing risk mitigation through exhaustive testing of the bundled package to verify that no problems are being introduced.

Other costs of bundling v The bundled library needs to be tested concerning the application, as well as any required testing for individual libraries. The IBM Tealeaf JavaScripts can require configuration updates and multiple iterations to verify. v Individual script changes or library upgrades require an entirely new bundle to be versioned, tested, and deployed.

Potential problems Debugging problems in a bundled script is more complicated. Individual libraries cannot be easily enabled or disabled by using proxy tools such as Fiddler. Note: If separating the IBM Tealeaf JavaScript from your bundled scripts is not an option, then in most situations the IBM Tealeaf JavaScript should be the last component of the bundle. Consult with IBM Professional Services to ensure effective management of the development and deployment of the bundle.

Will UI Capture impact the performance or behavior of my website? The library is designed to minimize the load on the web server and the web page running in the browser. As part of the above implementation steps, the downloaded JavaScript is minimized and is cached by the browser. Web server optimizations can further improve performance through server-side compression and caching settings. See Chapter 2, “UI Capture installation and implementation,” on page 33. The server application accepting the posts is very simple and does nothing with the data.

Chapter 7. UI Capture FAQ

139

The library posts add an extra hit or two to every page being captured by IBM Tealeaf. The size of the hit is small, normally increasing IBM Tealeaf storage requirements by less than 10%. By design, the IBM Tealeaf system does not mix these hits with normal page hits in the page count reports. With the library, your IBM Tealeaf solution may need to be configured with new replay rules to obtain replay fidelity.

Where can I get latest version of UI Capture ? To obtain latest version of the UI Capture JavaScript code, go to IBM Passport Advantage Online.

What is being captured by UI Capture ? Depending on how you configure the library, UI Capture can capture render times, browser dimensions, UI events (click, text input, scroll information, and so on) and more. See Chapter 1, “IBM Tealeaf CX UI CaptureJ2,” on page 1.

I am having trouble with UI Capture implementation. Where do I get support or help? To contact Customer Support, visit the IBM Support Portal or connect through your Salesforce account.

Using UI Capture How do I configure what is captured by UI Capture ? Currently, the IBM Tealeaf UI Capture solution does not support dynamic or configurable capture levels. UI Capture monitors a predefined set of user interface events and properties, submitting messages for those that are detected and captured. See "Tealeaf JSON Properties" in the IBM Tealeaf Client Framework Data Integration Guide. You can configure UI Capture to capture custom events specific to your web application. See "UI Capture j2 Public API Reference".

What is captured from mobile web sessions? Mobile web sessions are captured by using the same JSON schema that is used for desktop sessions, with some exceptions. See "Tealeaf JSON Object Schema Reference" in the IBM Tealeaf Client Framework Data Integration Guide.

What if I find a bug with UI Capture ? If you find a bug, access the IBM Support Portal to report it. Be prepared to provide the following information: v UI Capture version (found in tealeaf.js or tealeaf.min.js as @version 2.0.0.664)

140

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

v IBM Tealeaf Portal build number (at bottom of each Portal page) v CX RealiTea Viewer version (if used) v An IBM Tealeaf session not containing any sensitive information

How can I create events from UI Capture data? IBM Tealeaf UI Capture submits data in JSON format. You can create events and step attributes from this data through the Browser-Based Replay interface, using step-based eventing. These event objects can be modified in the Event Manager as needed. v See "Tealeaf JSON Properties" in the IBM Tealeaf Client Framework Data Integration Guide. v See "Step-Based Eventing" in the IBM Tealeaf CX Event Manager Manual. v See "Tealeaf Event Manager" in the IBM Tealeaf CX Event Manager Manual.

How can I search for UI Capture data? JSON-based data is indexed and available for search. Additionally, you can search for UI Capture data if you created events and attributes to track and capture the data. v See "Searching Session Data" in the IBM Tealeaf cxImpact User Manual. v See "Step-Based Eventing" in the IBM Tealeaf CX Event Manager Manual.

How do I capture only mouseover events on menu? IBM Tealeaf UI Capture does not support capture of mouseover events.

How do I capture keyup events? The JSON version of IBM Tealeaf CX UI Capture for AJAX does not capture keyup events from the client. Instead, monitor the change events for the same objects.

How do I report on client-side validation/error messages? IBM Tealeaf captures data that is exchanged between the browser and web server. To capture data that is not exchanged between the browser and web server, such as client-side validation, you create custom events. As such, any validation or error condition that is detected on the server and communicated to the client is recorded in the IBM Tealeaf session. Client-side validation is normally done by a JavaScript running on the user's browser. This validation does not result in a data exchange between the browser and web server. While client-side validation messages can be seen during replay of the session by virtue of replaying the same user input events that lead to the validation failures, they cannot be detected by IBM Tealeaf events that operate on the network traffic. One solution is to make the client-side validation triggers part of the network traffic. Using an API provided with UI Capture , you can create a custom UI event in the browser by the same code that detects and triggers the validation message. In the following example, a client-side validation function checks to verify that an input field is not empty. Chapter 7. UI Capture FAQ

141

function Validation_Check(user_input_element) { if (!user_input_element.value) { // Input is empty, validation failed return FAILURE; } return SUCCESS; }

To capture this validation trigger in an IBM Tealeaf session, you must create a custom event by using the TLT.logCustomEvent() method. The generated output can be captured from JSON format.

How do I force the sending of queued events? By default, IBM Tealeaf queues captured UI events for transmission that is based on predefined thresholds. In some cases, it is necessary to force the sending of a set of queued events to the web server for capture by IBM Tealeaf. For example, if a UI element such as a Submit button triggers the onbeforeunload event, the execution of that code can empty the queue of events before the onclick chain of events were properly submitted the queued events. In such a case, the onclick event that arrives after the completion of the site's event handler is lost. To handle these situations, the library enables the forced flushing of the event queue during the unload phase. To manually start this API in your code call TLT.flushAll()

For the first phase, the only desired metric is the Page Render time. Are there configuration settings that limit POSTs to just that event? You can configure the UI Capture Configuration Wizard so that only performance data is submitted. In the UI Capture Configuration Wizard, enable the Performance module only. Disable the Replay module. This configuration forces IBM Tealeaf UI Capture to submit only performance data, which includes the Page Render time metric. See "UI Capture j2 Configuration Wizard".

I use DHTML on my checkout form. Is UI Capture going to capture the dynamically rendered DOM elements? DHTML is managed by calling to TLT.rebind() to attach event handlers to your dynamically created input elements.

How do I get render times from UI Capture ? You can configure the UI Capture Configuration Wizard so that only performance data is submitted. In the UI Capture Configuration Wizard, enable the Performance module only. Disable the Replay module. This configuration forces IBM Tealeaf UI Capture to submit only performance data.

142

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

For all modern browsers that implement the W3C Navigation Timing specification, render times are reported through the Performance module. See "UI Capture j2 Configuration Wizard".

Do I need to have IDs assigned to my DOM elements that I would like to capture? If possible, assign unique IDs to the HTML elements that must be tracked. If doing so is not an option, assign unique IDs to the nearest ancestor HTML element. In the absence of an ID, IBM Tealeaf UI Capture builds an XPath like Document Object Model (DOM) path, which ends on the nearest ancestor with a valid HTML ID.

Can I customize UI Capture JavaScripts? No. IBM Tealeaf UI Capture provides configurable libraries for capturing user interface events for visitors to your j2 application, including many configuration options for tailoring the events to be captured and the methods by which they are captured. These options are indicated in the product documentation and in the UI Capture scripts. IBM Tealeaf is disabled during Replay by setting Tealeaf and its objects to empty objects. This allow us to block Tealeaf from running during Replay. In the specific case where you added custom code, and did not disable it during Replay, while the rest of Tealeaf is disabled during replay through ReplaySplice JS, you may encounter JavaScript errors during replay, which causes replay to appear broken. If you add any custom code, you must make sure it is disabled in ReplaySpliceJS on the Replay Server. Note: Modifications other than configuration changes to the JavaScript code of IBM Tealeaf UI Capture that are not implemented by IBM Tealeaf according to an IBM Professional Services engagement voids the warranty concerning the software, and such modified code is not supported under the IBM Tealeaf Maintenance and Support program. For more information, contact IBM Professional Services.

How come I get cross-domain error messages in my browsers debug console related to iFrames on my site? When the UI Capture solution is initialized on any page of your web application, it tries to attach to any frame elements on the page. However, if these frame elements are not in the same domain as the web application, most browsers register this action as cross-domain access and forbid the execution of the UI Capture script. There is no means of anticipating the browser denying access due to this security restriction. UI Capture continues to function normally. However, actions that are executed in the iFrame cannot be monitored. Some browsers record an error message in the console. For purposes of UI Capture functions that are described above, this message can be ignored and does not adversely impact either UI Capture or your application. Chapter 7. UI Capture FAQ

143

Upgrading the library How do I determine which version of the library I am using? For IBM Tealeaf UI Capture , library version information is provided in the X-Tealeaf header. See "UI Capture j2 Overview".

How do I determine which version of the TealeafTarget.jsp file I am using? Through the browser, navigate to the TealeafTarget.jsp file on your website by using the version query parameter. The following URL is an example. http://mydomain.com/mySite/TealeafTarget.jsp?version

Note: If this URL does not return the version information, you do not have the latest version.

When do I upgrade? Whenever possible, use the latest version of IBM Tealeaf UI Capture . If you are experiencing UI capture issues, you must upgrade to the latest version of IBM Tealeaf UI Capture since it contains the most recent improvements. You can integrate the UI Capture upgrade into the existing maintenance and deployment processes for your application. Note: Before you upgrade, review the IBM Tealeaf UI Capture Release Notes to assess its suitability for your web application.

How do I find out about available updates? 1. Acquire the version number for your current installation of IBM Tealeaf UI Capture . See “How do I determine which version of the library I am using?.” 2. Compare the above number to the latest available version. For more information on downloading IBM Tealeaf, see IBM Passport Advantage Online. Version information is also published in the general Release Notes in the IBM Tealeaf Online Help.

144

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Chapter 8. IBM Tealeaf documentation and help IBM Tealeaf provides documentation and help for users, developers, and administrators.

Viewing product documentation All IBM Tealeaf product documentation is available at the following website: https://tealeaf.support.ibmcloud.com/ Use the information in the following table to view the product documentation for IBM Tealeaf: Table 11. Getting help To view...

Do this...

Product documentation

On the IBM Tealeaf portal, go to ? > Product Documentation.

IBM Tealeaf Knowledge Center

On the IBM Tealeaf portal, go to ? > Product Documentation and select IBM Tealeaf Customer Experience in the ExperienceOne Knowledge Center.

Help for a page on the IBM Tealeaf Portal

On the IBM Tealeaf portal, go to ? > Help for This Page.

Help for IBM Tealeaf CX PCA

On the IBM Tealeaf CX PCA web interface, select Guide to access the IBM Tealeaf CX PCA Manual.

Available documents for IBM Tealeaf products The following table is a list of available documents for all IBM Tealeaf products: Table 12. Available documentation for IBM Tealeaf products. IBM Tealeaf products

Available documents

IBM Tealeaf CX

v IBM Tealeaf Customer Experience Overview Guide v IBM Tealeaf CX Client Framework Data Integration Guide v IBM Tealeaf CX Configuration Manual v IBM Tealeaf CX Cookie Injector Manual v IBM Tealeaf CX Databases Guide v IBM Tealeaf CX Event Manager Manual v IBM Tealeaf CX Glossary v IBM Tealeaf CX Installation Manual v IBM Tealeaf CX PCA Manual v IBM Tealeaf CX PCA Release Notes

© Copyright IBM Corp. 1999, 2015

145

Table 12. Available documentation for IBM Tealeaf products (continued). IBM Tealeaf products

Available documents

IBM Tealeaf CX

v IBM Tealeaf CX RealiTea Viewer Client Side Capture Manual v IBM Tealeaf CX RealiTea Viewer User Manual v IBM Tealeaf CX Release Notes v IBM Tealeaf CX Release Upgrade Manual v IBM Tealeaf CX Support Troubleshooting FAQ v IBM Tealeaf CX Troubleshooting Guide v IBM Tealeaf CX UI Capture j2 Guide v IBM Tealeaf CX UI Capture j2 Release Notes

IBM Tealeaf cxImpact

v IBM Tealeaf cxImpact Administration Manual v IBM Tealeaf cxImpact User Manual v IBM Tealeaf cxImpact Reporting Guide

IBM Tealeaf cxConnect

v IBM Tealeaf cxConnect for Data Analysis Administration Manual v IBM Tealeaf cxConnect for Voice of Customer Administration Manual v IBM Tealeaf cxConnect for Web Analytics Administration Manual

IBM Tealeaf cxOverstat

IBM Tealeaf cxOverstat User Manual

IBM Tealeaf cxReveal

v IBM Tealeaf cxReveal Administration Manual v IBM Tealeaf cxReveal API Guide v IBM Tealeaf cxReveal User Manual

IBM Tealeaf cxVerify

v IBM Tealeaf cxVerify Installation Guide v IBM Tealeaf cxVerify User's Guide

IBM Tealeaf cxView

IBM Tealeaf cxView User's Guide

IBM Tealeaf CX Mobile

v IBM Tealeaf CX Mobile Android Logging Framework Guide v IBM Tealeaf Android Logging Framework Release Notes v IBM Tealeaf CX Mobile Administration Manual v IBM Tealeaf CX Mobile User Manual v IBM Tealeaf CX Mobile iOS Logging Framework Guide v IBM Tealeaf iOS Logging Framework Release Notes

146

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Appendix A. Cross-domain communication In normal operation, UI Capture POSTs the captured data to the configured URL using the protocol (for example, http or https), domain (www.website.com), and port of the parent page. This is the preferred method of deployment. In some cases, it may be required to send the UI Capture POST request to a different server than the parent page. For example, the site may have deployed with a dedicated server to host the target page that has its own subdomain (tealeaf.website.com). This can be visualized as follows:

To perform this type of POST, the website must be configured as follows. 1. Deploy the following to the cross-domain server. v IBM Tealeaf target page. v Tealeaf cross-domain JavaScript from the UI Capture package. v A minimal html source to include the JS and set the document domain to enable cross-domain communication. An example of the html (xdomainFrame.html) is provided below. // Ensure the document domain is set to the sub-domain. document.domain = "website.com"; © Copyright IBM Corp. 1999, 2015

147

2. Add an iframe element to the pages and set the document domain to the subdomain to enable cross-domain communication. Mark the iframe element with a CSS style of display: none so it does not impact the rendered output of the page. // Ensure the document domain is set to the sub-domain. document.domain = "website.com";

3. Configure the main UI Capture library to set the crossDomainEnabled to true and specify the crossDomainFrameSelector to correspond to the hidden iframe added in step 2.

148

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Appendix B. Variations between jQuery and W3c flavors of UI Capture There are several variations between the jQuery and W3C flavors of UI Capture .

Change event In legacy Internet Explorer, the change event does not bubble. However, jQuery normalizes this behavior and causes the change to bubble on all versions of Internet Explorer. Therefore, when using the jQuery flavor, the change event listener does not need to be configured to attach to individual elements. For the same reason, on pages with frames or iframes, the change event cannot be tracked on elements contained within these frame elements (in legacy Internet Explorer) when using the W3C flavor of UI Capture . A workaround for this type of situation is to include the W3C flavor of the UI Capture library in the frame page itself.

Event delegation support in the jQuery flavor of UI Capture The jQuery flavor of the UI Capture supports delegate targets as implemented by the jQuery library. This is not supported by the W3C flavor. Specifying a delegate target works for the events that bubble from the innermost element in the document where they occur all the way up to the body and the document element. In Internet Explorer 8 and lower, a few events such as change and submit do not natively bubble but jQuery patches these to bubble and create consistent cross-browser behavior. To use event delegation, the delegateTarget property should be added to the event entry as follows. { name: "change", delegateTarget: "document", target: "input.selected" }

The delegateTarget points to the document or a selector that resolves to a single target element. The event is not registered when it occurs directly on the delegate target element, but only for descendants (inner elements) that match the target selector. For example, consider the following markup.

Without event delegation, you would have to specify the focus and blur event handlers as follows. { name: "focus", target: "input" } { name: "blur", target: "input" }

This results in event handlers being attached to each input element. With event delegation, one can specify the same as the following.

© Copyright IBM Corp. 1999, 2015

149

{ name: "focusin", delegateTarget: "#container", target: "input" } { name: "focusout", delegateTarget: "#container", target: "input" }

This would result in attaching a single event handler to the delegateTarget element, which is the container div. Note: Since focus & blur do not bubble, they need to be replaced with focusin and focusout, which are synthetic events that are provided by jQuery that do bubble. As another example, consider the following markup. Item

1 2 3 4 5

To monitor mouseover events on the menu items one could specify the following configuration. { name: "mouseover", target: "div#menu > a" }

This would attach an event handler to each menu item. With event delegation, one can achieve a similar result by specifying the following. { name: "mouseover", delegateTarget: "#menu", target: "a" }

This would attach a single event handler to the delegateTarget element, which is the div. Delegated events have the advantage that they can process events from descendant elements that are added to the document later. By picking an element that is guaranteed to be present at the time the delegated event handler is attached. You can use delegated events to avoid the need to frequently attach and remove event handlers. This element could be the container element of a view in a Model-View-Controller design, for example, or document if the event handler wants to monitor all bubbling events in the document. In addition to their ability to handle events on descendant elements that are not yet created, another advantage of delegated events is their potential for much lower overhead when many elements must be monitored. On a data table with thousands of elements, a delegated-events approach attaches an event handler to only one element, the container, and the event only needs to bubble up one or two levels at the most. This results in improved performance.

150

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: Intellectual Property Licensing Legal and Intellectual Property Law IBM Japan, Ltd. 19-21, Nihonbashi-Hakozakicho, Chuo-ku Tokyo 103-8510, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: © Copyright IBM Corp. 1999, 2015

151

IBM Bay Area Lab 1001 E Hillsdale Boulevard Foster City, California 94404 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample programs.

Trademarks IBM, the IBM logo, and ibm.com® are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at “Copyright and trademark information” at www.ibm.com/legal/copytrade.shtml.

152

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

Privacy Policy Considerations IBM Software products, including software as a service solutions, ("Software Offerings") may use cookies or other technologies to collect product usage information, to help improve the end user experience, to tailor interactions with the end user or for other purposes. A cookie is a piece of data that a web site can send to your browser, which may then be stored on your computer as a tag that identifies your computer. In many cases, no personal information is collected by these cookies. If a Software Offering you are using enables you to collect personal information through cookies and similar technologies, we inform you about the specifics below. Depending upon the configurations deployed, this Software Offering may use session and persistent cookies that collect each user's user name, and other personal information for purposes of session management, enhanced user usability, or other usage tracking or functional purposes. These cookies can be disabled, but disabling them will also eliminate the functionality they enable. Various jurisdictions regulate the collection of personal information through cookies and similar technologies. If the configurations deployed for this Software Offering provide you as customer the ability to collect personal information from end users via cookies and other technologies, you should seek your own legal advice about any laws applicable to such data collection, including any requirements for providing notice and consent where appropriate. IBM requires that Clients (1) provide a clear and conspicuous link to Customer's website terms of use (e.g. privacy policy) which includes a link to IBM's and Client's data collection and use practices, (2) notify that cookies and clear gifs/web beacons are being placed on the visitor's computer by IBM on the Client's behalf along with an explanation of the purpose of such technology, and (3) to the extent required by law, obtain consent from website visitors prior to the placement of cookies and clear gifs/web beacons placed by Client or IBM on Client's behalf on website visitor's devices For more information about the use of various technologies, including cookies, for these purposes, See IBM's Online Privacy Statement at: http://www.ibm.com/ privacy/details/us/en section entitled "Cookies, Web Beacons and Other Technologies."

Notices

153

154

IBM Tealeaf UI Capture : IBM Tealeaf UI Capture Guide

IBM®

Printed in USA

Suggest Documents