This section provides guidelines for successful implementation and use of Acoustic Experience Analytics (Tealeaf) UI Capture.

In parallel with your process for developing the web application, plan to deploy Acoustic Experience Analytics (Tealeaf) UI Capture as early as possible in the development process for the following reasons.

  • Early deployment limits the potential for issues that are discovered in a production environment.
  • Early deployment provides an opportunity to monitor application problems and help debug the application.

These guidelines apply to all deployments of Acoustic Experience Analytics (Tealeaf) UI Capture. Different options can apply to different web application types.

Application scope

Acoustic Experience Analytics (Tealeaf) UI Capture supports specific browsers, application types, and protocols.

For a list of supported browsers, see System prerequisites and supported browsers for Acoustic Tealeaf UI Capture.

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 Acoustic Experience Analytics (Tealeaf) must process.

Acoustic Experience Analytics (Tealeaf) supports the following rich internet application types:

  • Ajax

Note: Acoustic Experience Analytics (Tealeaf) continues to support existing customers who deployed Flash or Flex applications. Acoustic Experience Analytics (Tealeaf) does not support new customers who use these technologies.

Note: Currently, Acoustic Experience Analytics (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 Acoustic Experience Analytics (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 Acoustic Professional Services.

Note: Acoustic Experience Analytics (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 Acoustic Professional Services.

Supported protocols

Acoustic Experience Analytics (Tealeaf) supports HTTP and HTTPS for request and response communication between client and server.

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: Acoustic Experience Analytics (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 Acoustic Experience Analytics (Tealeaf) UI Capture development initiatives, verify that the following information is available or was captured.

Acoustic Experience Analytics (Tealeaf) access

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

Third-party content

The following guidelines apply to third-party content.

Third-party domains

Acoustic Experience Analytics (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 Acoustic Professional Services.

Third-party plug-ins

Other than the Flash player, Acoustic Experience Analytics (Tealeaf) does not currently support the replay of third-party plug-ins in Rich Internet Applications, such as Silverlight or Java applets.


Personnel in the following roles need to be available to Acoustic Experience Analytics (Tealeaf) for the UI Capture deployment.

Application architect
During deployment, Acoustic Experience Analytics (Tealeaf) can make requests to the web application architect to identify locations in the application for calls to the Acoustic Experience Analytics (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 directly translates into which UI elements, events, clicks, and other aspects of the application must be captured by Acoustic Experience Analytics (Tealeaf). During development, this individual might be able to identify qualified use cases for Acoustic Experience Analytics (Tealeaf) UI Capture.

External resources

If application development is outsourced to a third-party, provide access to this team. Acoustic Experience Analytics (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

Acoustic Experience Analytics (Tealeaf) assumes that the following basic production stages are in place.

  • Development
  • Testing
  • Production

For more information about development goals during each of the stages, see UI Capture installation and implementation.

When to deploy UI Capture during development

Acoustic Experience Analytics (Tealeaf) recommends deploying Acoustic Experience Analytics (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 Acoustic Experience Analytics (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 Acoustic Experience Analytics (Tealeaf) UI Capture privacy rules configuration to identify and protect sensitive client data before deployment to the live site.

By including Acoustic Experience Analytics (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 Acoustic Experience Analytics (Tealeaf) UI Capture directly into a Production environment.

Performance management

Integrate Acoustic Experience Analytics (Tealeaf) UI Capture into the Performance Management test suite for your enterprise.

Performance measurement of Acoustic Experience Analytics (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, Acoustic Experience Analytics (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: Acoustic Experience Analytics (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 Acoustic 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 Acoustic Experience Analytics (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.

<form id="my_form" method="get" action="submit.php">
  <input type="text" name="action" value="hotel" />
  <input type="text" name="type" />
  <input type="text" name="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 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 Acoustic Experience Analytics (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.


  • Where possible, do not use anchor tags as the value on which to change Ajax driven views, modals, or fly-out windows.
  • 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.
  • 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, Acoustic Experience Analytics (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

Capture and replay of custom UI controls might require a custom solution. For more information, contact Acoustic 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 Acoustic Experience Analytics (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.

For more information, see and

Private data

Acoustic Experience Analytics (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 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 Acoustic Experience Analytics (Tealeaf) privacy, replay can break if the web application is not designed to accept the altered content.

Frequency of posts

Acoustic Experience Analytics (Tealeaf) enables the configuration of the size and frequency of POSTs to the Acoustic Experience Analytics (Tealeaf) target page.

  • During Development, you can send small and frequent POSTs so that you can monitor activities at a granular level.
  • 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:

  • The maximum allowed number of events in the buffer. If this maximum is exceeded, the queued events are posted.
  • A timer value for periodic flushing of the event queue, regardless of the buffer size.

UI events overridden by UI Capture

In some implementations, Acoustic Experience Analytics (Tealeaf) can be configured to override specific user interface events.

Verify that there is no conflict between the Acoustic Experience Analytics (Tealeaf) overrides and events that are used or monitored by your application.

See UI Capture installation and implementation.

In your HTML code, do not set the window.parent property to null

If window.parent property is set to null, Replay Server cannot navigate through the HTML to find the correct parent.

Setting window.parent to null causes Browser Based Replay to throw the following error message:

Cannot call method 'getElementsByTagName' of undefined at

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 UI Capture installation and implementation.


The following guidelines apply to working with JavaScript.


Avoid changing any Acoustic Experience Analytics (Tealeaf) configuration settings unless you are sure of the reasons for the change and its effects. Some options can have significant effects on performance.


Monitor any changes to the JavaScript files by adding detailed comments. Periodically, Acoustic Experience Analytics (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) {

Create custom events

By default, Acoustic Experience Analytics (Tealeaf) UI Capture monitors user interactions with the application by capturing the standard Document Object Model events. Acoustic Experience Analytics (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.

To capture these aspects and other client-side activity, the application developer can use a simple Acoustic Experience Analytics (Tealeaf) API to notify the library of any data that must be included in the Acoustic Experience Analytics (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 Acoustic Experience Analytics (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 Acoustic Experience Analytics (Tealeaf) and might affect application performance.

See UI Capture Public API Reference for more information.

Join The Discussion

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