Playback Time JavaScript API

This article describes the functionality of the ClickTale Playback Time JavaScript API. This relates to the functions, variables and objects that are made available in a page to customers while the page is rendered in the ClickTale account (reports or recordings). The main goal of this API is to assist in proper rendering of the page for playback and reports. Calls to this API are performed at report render time.

ClickTaleExcludeBlock
A method to declare areas in your page's HTML as areas that should be excluded from rendering inside the ClickTale system. At the same time, this is a method to declare areas that should be included.

Effectively you can add an area of HTML to your page and declare it in such a way that it will not run when your page is rendered to visitors, but will run when your page is rendered in the ClickTale system. See ClickTaleExcludeBlock

ClickTaleIsPlayback
A deprecated method to detect whether the page is currently rendered inside the ClickTale system. See JavaScript_API.

Recording context
A recording context is an object that represents information about a single recording. You can query for this context when your page is rendered in a context of one specific recording, such as the case with Visitor Playback. You can also query for this object in the case of an aggregated report, as with a Mouse Move Heatmap, in which case your context will contain information of one of the recordings in the aggregation.

To receive the context, call the 'ClickTaleContext.getRecordingContextAsync([version], [callback])' function. [version] is a version of the context, where "1" and "1.1" are available at the moment. Version "1" doesn't implement recording context in aggregated reports. [callback] is a function reference to a function that accepts one parameter.

Call example
The callback will receive a "context" object containing the following fields:

Aggregation context
An aggregation context is an object that you can query for when your page is rendered in a context of an aggregated report, such as the case with a Mouse Move Heatmap.

To receive the context, call the ClickTaleContext.getAggregationContextAsync([version], [callback]) function. [version] is a version of the context, where only "1beta" is available at the moment. [callback] is a function reference to a function that accepts one parameter.

Call example
The callback will receive a "context" object containing the following fields:

Example - Open Hidden Elements in Heatmaps and Form Analytics
Let's assume you have a multiple step form, consisting of a few hidden  s, two of which are:

You would like these  's to be visible in the MouseMove and Clicks Heatmaps as well as in Form Analytics. To enable this simply put the following code on the HTML of your page:

Advanced Example - Running Code Based On Event Selection
Let's assume you have a hidden  :

You want this  to be visible in MouseMove and Click Heatmaps as well as Form Analytics. You also want this to be visible only when you generate the report in question by selecting the Event "show li" instead of generating it based on URL (this option is available at the top of the report generation page).

To solve this simply put the following code on the HTML of the page:

Another Example Based on a Segmentation Filter
If you have Event segmentation filters available you can use Events more extensively. Below is an example of the same code to display the element, but the condition for it to run is based on filtering using the Visitor Events filter.

Stopping and Starting Aggregation
You can hold automatic aggregation of data until a certain criteria is met. At that point, you can start aggregation manually.

Use the following functions:


 * ClickTaleContext.dontAutoAggregate - Hold aggregation


 * ClickTaleContext.aggregateNow - Start aggregation

Example

Aggregation by Content in Heatmaps
You can create a content drop-down list for a Heatmap, with parameters. This allows the user to see aggregated data for specific elements on the page.

Use the function ClickTaleContext.registerAggregatedContentSwitch

For more information, read the Displaying Overlapping Elements on Heatmaps article.

Example

context.Location vs. context.location
context.location (found in getRecordingContextAsync) holds the individual URL of the recording (whether shown in playback or aggregated reports). context.Location (found in getAggregationContextAsync) holds the location parameter used to generate the report in question.

For example: If a Heatmap for www.example.com is generated for all pages beginning with http://www.exa, calling getRecordingContextAsync might give a context.location value of http://www.example.com while getAggregationContextAsync's context.Location will equal http://www.exa. It follows that when generating an aggregated report based on a ClickTale Event rather than a URL or part of it, that context.Location is empty, and indeed it results in an empty string in those cases.

Therefore, when generating code which is dependent on URL, getRecordingContextAsync should be employed in order to retrieve context.location (note that in those cases you can check context.inSingleRecordingScope to verify that the code is running in a report rather than in playback).