Configuring IBM Tealeaf DOM capture and replay

Implementing DOM capture involves configuring your application to be "DOM-enabled" and configuring IBM® Tealeaf® to process and replay sessions of visitors that use the DOM-enabled application.

Before you begin

Before you enable DOM capture and replay:
  • Understand the pros and cons of using DOM capture
  • Get classic capture to work first for your application

About this task

This task describes the end-to-end configuration procedure for an IBM Tealeaf DOM capture and replay solution. The procedure includes steps for configuring DOM capture on the client side and for enabling the replay of DOM captured data on the server side.

Enabling DOM capture on the client side involves configuring the UIC by:
Action Description
Enabling DOM Capture You can log full DOM captures or DOM Diffs. DOM Diff is an enhancement to the DOM capture feature. The default setting for DOM Diffs is enabled.
Note: DOM Diff functionality is not supported within hybrid mobile apps. ScreenViews and DOM snapshots are used to replay sessions from hybrid mobile apps.
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.

DOM capture is enabled for an individual page by adding a DOM-capture trigger event to the page. The classic Capture process is used to capture any page that is not configured with a DOM-Capture trigger event.
Adding triggers for page load, page unload, click, and change A trigger tells the UIC when to do a DOM Capture. For initial setup and testing, you want to perform a DOM capture on every page load and unload, on every click, and on every change event. After you test your setup and verify that DOM capture is working, you want to tune the trigger events to capture only specific data.

After you verify that the DOM capture feature is enabled and working in replay, you determine if DOM Diff is affecting performance and fine-tune triggers for capture. Depending on the application, there may be so many DOM Diffs to process that the performance is affected. In that case, you may want to disable DOM Diff and use a full DOM capture.

In a production environment, to capture every screenview load and unload and every click or change on a control would be such a large amount of data that it would cause performance issues. You might need to limit the captures to specific clicks and changes. You can create custom triggers to limit the DOM capture to specific user actions.

You can trigger DOM captures on specific events to capture the data that is critical to your application:
  • Pre-defined event triggers - The click, load, unload, change - you can trigger a DOM capture on the click of a specific button or the load of a specific screenview. After you assign an event to a specific control or screenview event, the system stops capturing a DOM snapshot for every event of that type. For example, defining a trigger as click without specifying a control means that a DOM capture is triggered on every click event. Specifying a control for the click, such as the Next button, means that DOM captures are only triggered when the user clicks a Next button.
  • Custom event triggers - You can define a custom event in the replay module configuration and use that event to trigger a DOM capture. For example, you can create a custom event that is called Login and use the Login event to trigger a DOM capture.

Configuring DOM capture on the server-side involves enabling DOM Capture on the Replay server, increasing the byte size specified in the Canister Safety Limits [BB] Event, and adding a DOM Capture Virtual Session Agent to the pipeline.

The DOM Capture Virtual Session Agent processes data by:
  • Extracting DOM or DOM Diff from type 12 message.
  • Creating a virtual hit with extracted DOM or DOM Diff being the response.
  • Inserting the newly created virtual hit into the session.
  • Sending the processed data to the Canister.

At replay time, the Replay Server pulls the session that contains virtual hits.

Additionally, the DOM Capture Virtual Session Agent ensures the seamless integration of the DOM or DOM Diff with existing Tealeaf features, such as search index and privacy.

Note: The DOM Diff feature applies to IBM Tealeaf Version 9.0.2, fix pack 1 and later. For information about fix pack 1, contact your IBM Tealeaf support representative.

Procedure

  1. Configure DOM Capture on the client side:
    1. Start the configuration wizard for the application that you are using with Tealeaf.
    2. On the DOM Capture page, select Enable DOM Capture.
    3. If you want to use Hybrid Mobile replay, remove the DOM Diff selection from the DOM Capture page.
    4. Add four triggers, one each for load, unload, click, and change:
      1. Select Add trigger. Leave the Event drop-down at Load, and the Screenview and Delay fields blank.
      2. Select Add trigger. Change the Event drop-down to Unload. Leave the Screenview and Delay fields blank.
      3. Select Add trigger. Change the Event drop-down to Click. Leave the ID, ID Type, CSS Selector, and Delay fields blank.
      4. Select Add trigger. Change the Event drop-down to Change. Leave the ID, ID Type, CSS Selector, and Delay fields blank.
    5. Select Finish.
  2. Configure the Replay server session agent for DOM captured data:
    1. Use TMS to add the DOM Capture Virtual Session Agent.
      1. Log on to the IBM 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 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).
    2. 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.
    3. 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 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 1. 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:
    1. 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.
        Note:
      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.
    2. 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.
      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.
    3. Select Finish.