The 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.

  • getSessionData
  • logCustomEvent
  • logExceptionEvent
  • logScreenviewLoad
  • logScreenviewUnload
  • logScreenCapture

TLT.getLibraryVersion()

TLT.getLibraryVersion() returns the version number of the UI Capture library. It is recommended to use the latest version.

Example

version = TLT.getLibraryVersion();

For example, if version 5.1.0 of the UI Capture library is installed, the API returns 5.1.0.


TLT.init(object configObject, /*optional*/ function callbackFunction)

This API initializes the 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.

  • For static deployments, the call to init can be included as part of the static JavaScript resource.
  • 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 */
}

TLT.rebind(/*optional*/ DOMElement root)

Rebind causes the Tealeaf UI Capture library to reprocess its event listeners. The application can use this API to notify the 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 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 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.

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);
     }

     $( "<div>" ).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.

Note: There is a max. limit of 300 custom messages per page.

For more information, see Step-Based Eventing and Tealeaf Report Builder.

Example

if (TLT.isInitialized()) {
    TLT.logCustomEvent("apiMetrics", {
        url: "/v1.0/getAccountInfo",
        status: 200,
        retries: 0,
        errorCode: 0
    });
}

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 Tealeaf UI Capture library's message stream.

Specifying the URL and line number of the error message is optional.

Note: There is a max. limit of 400 exception messages per page.

Example

function calllogExceptionEventh() {

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

TLT.logScreenviewLoad(DOMString screenviewName, /*optional*/ DOMString referrerName, /*optional*/ DOMElement root) and TLT.logScreenviewUnload(DOMString screenviewName)

Applications can use the UI Capture API to log a screen view load message in to the Tealeaf UI Capture library's message stream.

The UI Capture library tracks URL path and URL hash changes and automatically logs Screenview messages. The application can choose to disable the automatic Screenview logging and log the messages by using the TLT.logScreenviewLoad API call. It is a recommended practice to use TLT.logScreenviewLoad and TLT.logScreenviewUnload to capture the screenviews for use with Replay and analytics.

As an example, a typical checkout flow would have a payment screen where the visitor can enter their payment information. When the payment screen is displayed, the application can log the screenview LOAD message using the following snippet.

TLT.logScreenviewLoad("payment");

When the visitor exits the payment screen, the application can log the screenview UNLOAD message using the following snippet.

TLT.logScreenviewUnload("payment");

Note: The load and unload API call requires that the screenview name is the same for both calls.

You can use the referrerName parameter to log nested screenviews. For example, if the payment screen has a nested screen for credit card payments and another screen for direct payment from the bank, you can subcategorize the screenviews into creditcard and directpayment.

The following example shows how you can log the nested screenview for a payment screen that has two nested screenviews to accept credit card payments and direct payments.

TLT.logScreenviewLoad("payment");
TLT.logScreenviewLoad("creditcard", "payment");

If the user switches from entering a credit card payment to entering direct payment information, the following snippet is used to stop logging the credit card screenview and log the screenview for the direct payment.

TLT.logScreenviewUnload("creditcard");
TLT.logScreenviewLoad("directpayment", "payment");

As the user exits the payment section, the application uses the following snippet to end the screen logging.

TLT.logScreenviewUnload("directpayment");
TLT.logScreenviewUnload("payment");

TLT.getSessionData()

This API returns an Tealeaf session data object. The 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;

  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.

Warning: 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 Tealeaf native logging frameworks register and uses 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,
     order: 1,
     cbType: 'messageRedirect',
     cbFunction: function (msgStr, msg){
       tlBridge.addMessage(msg);
     }
   }
]);

When you register a messageRedirect callback function an optional "order" property can be specified. This property specifies the numerical order that multiple messageRedirect callback functions are invoked.

messageRedirect

This callback can be registered to redirect and intercept messages from the UI Capture library. When this callback is registered, the UI Capture library invokes the callback function for each message before you add 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 Tealeaf native logging frameworks registers and uses 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;
}

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 Tealeaf native logging frameworks registers and uses 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:

  • captureFrames – Whether to capture frames or iframes. Values are true or false.
  • removeScript – Whether to remove script tags from the capture.

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.logFormCompletion(/*boolean*/ submitted, /*[OPTIONAL] boolean*/ valid)

Use this API for cxOverstat to produce the Form Completion report.

This API creates and adds a form completion message. Form completion indicates whether the user submitted a form (or a form equivalent) and whether the form was validated. The UI Capture library should be able to post these types of messages for pages which have forms on them – they will indicate whether the user has submitted a form or not, and optionally whether the form was valid or not.

The API accepts two parameters:

  • submitted: Boolean flag indicates whether the form (or form equivalent) was submitted (true) or not (false)
  • valid: Optional boolean flag indicates whether any validation was performed on the form input and if the validation check passed (true) or failed (false)

Note: For a standard HTML form element, the submission is when the submit event is triggered. For applications that use AJAX, a submission is defined as per the business logic.

Example Form Completion JSON message

{
   type: 15,
   formCompletion: {
     submitted: true/false
     valid: true/false/null
   }
}

Note: This feature requires {name:"submit", recurseFrames: true } configuration setting for cxOverstat.

Example Default Configuration for the cxOverstat module

overstat: {
    events: [
        { name: "click", recurseFrames: true },
        { name: "mousemove", recurseFrames: true },
        { name: "mouseout", recurseFrames: true },
        { name: "submit", recurseFrames: 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.

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

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 returns without logging the message.

Example of a Type 13 JSON GeoLocation message logged by this API:

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

 


Join The Discussion

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