Documentation
Help CenterCommunityDevelopersAcademyStatus

Configuration options for Tealeaf On-Premise

Suggest Edits

Tealeaf On-Premise is the predecessor of Tealeaf SaaS and also uses the Tealeaf Web SDK. Tealeaf SaaS provides cloud endpoints to consume Web SDK data. Tealeaf On-Premise requires customers to set up their own endpoint, or target page.

When using Tealeaf On-Premise, do not specify an appKey in the Tealeaf Web SDK configuration, as appKeys are only relevant to Tealeaf SaaS.

📘

Note

Primary Tealeaf On-Premises documentation resides in our support portal at help.goacoustic.com

Target page

The Tealeaf target page is the endpoint to which the Web SDK JavaScript is configured to send POST requests for capture by Tealeaf On-Premise. You place this dynamic page with your web application's other dynamic page files.

How the target page is used

The dynamic target web page receives the information captured by the Web SDK JavaScript. It must be a dynamic page, such as TealeafTarget.php, TealeafTarget.jsp, TealeafTarget.asp, or similar, to ensure that responses are sent only when the full payloads sent by the Web SDK have been received. Static HTML target pages are not supported.

The target page exists only to acknowledge the post, not to ingest the data. Instead, the data is captured at the network level, by the Passive Capture Application server (PCA).

The web server returns a minimal valid response, such as the following message.

<html>
  <head></head>
  <body>Received 895 bytes in 0.1 ms</body>
</html>

Sample target pages

The Web SDK distribution provides sample targets for ASPX, JSP, and PHP environments. You can modify the target page for your specific target environment. You can use these sample targets to create target pages suitable for other environments.

Target page requirements

The target page must be added to your web server infrastructure in a location that the Web SDK 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:

  • The page must be POSTable.
  • The page must be dynamically executable, for example, ASPX, PHP, or JSP.
  • The page must not be cached by Akamai or any cache service, device, or mechanism.
  • For a non-IIS server, a dynamic web page must be created to accept the POST from the Tealeaf Web SDK JavaScript. The contents of the web page vary based on the deployed technology. The contents of the returned Web SDK JavaScript POST requests are irrelevant. To minimize bandwidth, minimize the return contents.

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 Web SDK in your deployment. This setting ensures the correct capture of the UI Hits by the CX PCA.

Deployment guidelines

Refer to these guidelines when you deploy the Tealeaf target page.

Typically, the Tealeaf target page is deployed independently of the core application itself in logical and physical terms. Review these guidelines with your infrastructure staff.

  • Avoid deploying the Tealeaf target page behind enterprise security features, such as SiteMinder.
  • If possible, deploy the 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.
  • In your web application's pages, references to the target page must be relative to the site's root path. For www.example.com, to reference a Tealeaf target page at www.example.com/scripts/TealeafTarget.aspx, you configure the Tealeaf Web SDK to /scripts/TealeafTarget.aspx. The initial / makes it a site-root relative path.
  • Test the Tealeaf target page thoroughly in a test environment before deployment to production.
  • In the Web SDK JavaScript file, the URL of the target page is configured as part of the initial implementation.

Browser caching for the Tealeaf Web SDK

For browser caching configuration, follow these guidelines.

  • Set the TTL values for the Expires or Cache-Control headers for the Tealeaf JavaScript to the same value as the rest of the scripts that are stored on the web server.
  • 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:

Unit tests of the target page

To test that the target page is operating properly, you can run the following tests.

  • GET: Enter the URL of the target page in your browser. If you receive a blank page or a non-404 error, the page is properly handling your request.
  • 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.

Verify the target page

All of the provided Acoustic Tealeaf target pages are named so that the data they receive can be captured, processed, and integrated into replay by Acoustic Tealeaf.

📘

Note:

The file name of the Acoustic Tealeaf target page must include TealeafTarget in it for easy identification. Do not change this file name after you configure Acoustic Tealeaf Web SDK.

Complete the following steps to verify that there are no impediments to capturing and processing the Acoustic Tealeaf target page in your system.

  1. In the Web Console of the Acoustic Tealeaf Passive Capture Application, you configure file extensions to drop from capture. Verify that the file extension used for your Acoustic Tealeaf target page is not dropped from capture.
  2. In the Acoustic Tealeaf 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 RealiTea Viewer. Verify that the extension for your Acoustic Tealeaf target page file name does not appear in the list of possible interpreted pages in RealiTea Viewer.

Tealeaf Cookie Injector

For best results in capturing client UI events, deploy the Tealeaf Cookie Injector in your web server environment. The Tealeaf Cookie Injector provides unique session IDs regarding captured Tealeaf session data. For instructions, see Configuring the PCA pipeline in our support center.

Tealeaf RealiTea Viewer

The Tealeaf RealiTea Viewer is a stand-alone desktop application that can be used to replay sessions captured by Tealeaf, including client UI events. You must install RealiTea Viewer on your local desktop to replay sessions that include UI events. For instructions, see Setting up RealiTea Viewer on your local computer.

📘

Note

Replay of sessions that are captured by Web SDK is not fully supported in the RealiTea Viewer.

  • The JSON messages that contain UI events are not fully supported in the RealiTea Viewer.
  • For replay of JSON messages, use Browser-Based Replay.

Passive Capture Application

By default, the Tealeaf 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.

Tealeaf Web SDK requires the Passive Capture Application to be configured to enable the capture of JSON content in the request.

You must also configure the Passive Capture Application to capture the wanted POST traffic. Passive Capture Application can be configured to include or exclude specific file extensions, mimetypes, and POST types.

📘

Note

Ensure that your Passive Capture Application installation was configured to capture JSON mimetypes.

If dynamic JavaScript or CSS style sheets must be captured, the Tealeaf 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.

Updated 4 months ago