Documentation
Help CenterCommunityDevelopersAcademyStatus

Ajax Listener module

Suggest Edits

The Web SDK provides the Ajax Listener module to log application and user data to a Tealeaf session. You can use this module when a Tealeaf session cannot capture the XHR data in certain deployments. It logs the XMLHttpRequest (XHR) and Fetch request and response data. A proxy is set for setRequestHeader and send methods, and the native XHR prototype object's open method is overridden.

📘

Note:

Automatic logging of Fetch request and response data is supported starting with Ajax Listener module version 1.2.0.

The module only logs XHR data. It does not listen to other forms of network communication such as sendBeacon. You can also log custom messages using the TLT.logCustomEvent API method.

The Ajax Listener module supports native browser implementations of XMLHttpRequest and Fetch. Check if your application is overriding these browser APIs by examining the output of window.XMLHttpRequest and window.fetch in the debug console. If the result does not indicate native code, your application may be overriding these native APIs and may not use the Ajax Listener module.

📘

Note:

Using this module with XMLHttpRequest polyfills or Fetch polyfills is not recommended.

Before you begin

Install the Tealeaf Web SDK.

Install the module

  1. Copy the module script ajaxListener.min.js into your Web SDK JavaScript file.
  2. Place the script file after the SDK source and before the configuration/initialization section.
  3. The Web SDK JavaScript file should be structured as follows:
    • pako JS – gzip encoder
    • tealeaf JS – W3C or jQuery flavor of the Web SDK
    • Optional modules – Ajax Listener or other custom modules
    • Configuration – Web SDK configuration
    • Initialization – configuration to start the TLT.init API

Configure the Tealeaf Web SDK

To enable the Ajax Listener module, add the following code snippet to the core configuration section the defaultconfiguration.js file:

ajaxListener: {
        enabled: true,
        events: [
            { name: "load", target: window},
            { name: "unload", target: window}
        ]
    }

Log XHR data

Once you enable the Ajax Listener module in the core configuration, it starts to monitor the XHR calls on the page after the Web SDK starts.

The following information is logged in the Tealeaf session for each XHR call:

  • requestURL (Required) – the request URL host and path
  • method (Required) – HTTP request method e.g. GET, POST
  • status (Required) – the HTTP response status code
  • statusText(Required) – the HTTP response status text e.g. OK
  • async (Required) – Boolean flag indicating if the request was asynchronous. True for an asynchronous request
  • ajaxResponseTime (Required) – milliseconds from request send to complete (readyState == 4)
  • locationHref (Required) – document.location.href value when the request is sent

Configure selective XHR logging

The Ajax Listener module can also be configured to selectively log XHR requests and responses by adding URL block rules and filter rules to the Web SDK modules configuration.

ajaxListener: {
        urlBlocklist: [
            { regex: "brilliantcollector\\.com" },
            { regex: "tealeaftarget", flags: "i" }
        ],
        filters: [
            {
                method: { regex: "GET", flags: "i" },
                url: { regex: "api", flags: "i" },
                status: { regex: "4\\d\\d", flags: "" },
                log: {
                    requestHeaders: true,
                    requestData: false,
                    responseHeaders: false,
                    responseData: true
                }
            }
        ]
    }

urlBlocklist rule

urlBlocklist is an optional array containing one or more URL block rules. Each rule specifies a RegEx pattern which prevents the matching request from being logged.

filters rule

filters is an optional array that can contain one or more filter rules. Each rule can optionally specify any combination of the following filter properties in RegEx format:

  • url – the RegEx to match the request URL
  • method – the RegEx to match the HTTP request method
  • status – the RegEx to match the HTTP response status

Specify data logging criteria for filter rules

You can specify which XHR data should be logged and fine-tune the XHR data log. You can log the following additional data for each XHR request:

  • requestHeaders (Optional) – Object containing name-value pairs of HTTP headers that are set using the setRequestHeader() method.
  • requestData (Optional) – String containing the request data. If this is valid JSON data, it is parsed into a JSON object.
  • responseHeaders (Optional) – Object containing name-value pairs of HTTP headers sent with the response.
  • responseData (Optional) – String containing the response data. If this is valid JSON, it is parsed into a JSON object.

📘

Tip:

When you specify multiple filter rules, place the more restrictive/specific rules before the more generic rules. The module uses the first filter that matches a given XHR request.

Example filtering rule for logging the request headers of all XHR requests:

{
	log: {
		requestHeaders: true
	}
}

Example filtering rule for logging the response of all XHR GET requests:

{
	method: {
		regex: "GET",
		flags: "i"
	},
	log: {
		responseData: true
	}
}

Example filtering rule for logging all XHR data for requests containing a specific query parameter debug=on and default data for all XHR requests:

{
	url: {
		regex: "debug=on(&|$)"
	},
	log: {
		requestHeaders: true,
		requestData: true,
		responseHeaders: true,
		responseData: true
	}
}, {
	// Empty rule to match all XHR requests and log default data
}

Example filtering rule for logging XHR request data when HTTP status is 4xx and default data for all other requests:

{
	status: {
		regex: "^4\\d\\d$"
	},
	log: {
		requestHeaders: true,
		requestData: true
	}
}, {
	// Empty rule to match all XHR requests and log default data
}

Example filtering rule for logging all XHR data for requests to /api/getAccountDetails and request header data for all XHR requests:

{
	url: {
		regex: "\/api\/getAccountDetails"
	},
	log: {
		requestHeaders: true,
		requestData: true,
		responseHeaders: true,
		responseData: true
	}
}, {
	log: {
		requestHeaders: true
	}
}

Log Fetch data

Automatic logging of Fetch request and response data is supported starting with Ajax Listener module version 1.2.0. Fetch data is captured by default and is automatically turned off in browsers that do not support Fetch API. You can use the same XHR filter configurations for fetch requests.

📘

Note:

Disable the fetch data capture if your application is using polyfills.

Disable data logging

To disable Fetch or XHR data capture and logging, set the corresponding flags to false in the module configuration as follows:

ajaxListener: {
		xhrEnabled: false,
		fetchEnabled: false,
		filters: [
			...
		}

Bypass safety check implementation

The Ajax listener module implements a safety check that automatically disables logging if it detects that the native API is unavailable or overridden by 3rd party script.
You can bypass this safety check by setting skipSafetyCheck to true in the module configuration.

ajaxListener: {
		skipSafetyCheck: true,
		xhrEnabled: true,
		fetchEnabled: true,
		filters: [
			...
		}

Following is an example of the XHR data that is logged by the Ajax Listener in the Tealeaf session:

{
  "type": 5,
  "offset": 9182,
  "screenviewOffset": 9171,
  "count": 4,
  "fromWeb": true,
  "customEvent": {
    "name": "ajaxListener",
    "data": {
      "requestURL": "www.acoustic.com/api/getAccountDetails",
      "method": "GET",
      "status": 200,
      "statusText": "OK",
      "async": true,
      "ajaxResponseTime": 285,
      "locationHref": "https://www.acoustic.com/support/login",
      "requestHeaders": {
        "X-Requested-With": "XMLHttpRequest",
        "X-CustomerId": "D295024"
      },
      "responseHeaders": {
        "date": "Thu, 22 Feb 2020 01:38:07 GMT",
        "cache-control": "private",
        "server": "Microsoft-IIS/10.0",
        "x-powered-by": "ASP.NET",
        "content-length": "318",
        "content-type": "application/json"
      },
      "response": {
        "accountDetails": {
          "id": "D295024",
          "memberSince": "15 July 2012",
          "customerType": "G",
          "electronicDelivery": false,
          "currencyUnit": "USD"
        }
      }
    }
  }
}

🚧

Important

Test your application and validate the data that is being captured before deploying this module into a production setting.

Additional resources

Updated 5 months ago