Help talk:JavaScript API

This article describes the functionality of the ClickTale Recording JavaScript API. It lists the functions, variables and objects that are made available to customers by the inclusion of the tracking code. The main goal of this API is to assist in the collection of information during recordings to allow for proper playback and reports. Calls to this API are performed during the recording time.

For an API that you can use to affect your page while it is rendered in the ClickTale account (reports or playback), please see the Playback Time JavaScript API.

For APIs dealing with Dynamic Content, please see the ActivePlayback API, ClickTaleExec and JavaScript Integration articles.

Functionality Set 1 - The Main Set
A main set of functions and variables is available right after the inclusion of ClickTale's main script which is part of the ClickTale Bottom part (it looks similar to this):

You can start running these functions when the main tracking code is loaded.

ClickTaleOnReady
Usage: ClickTaleOnReady This function notifies when ClickTale's main script has been loaded, after which you can run the API functions.

ClickTale
Usage: ClickTale(ProjectID,RecordingRatio[,PartitionID]) This is the main function used by ClickTale and it is part of the auto-generated tracking code. ClickTale initiates a process of recording a visitor by checking for a supported browser and deciding if the visitor should be recorded based on the "recording ratio" parameter passed. Once all tests are successful, this method will load additional code to perform the recording itself. PartitionID is an internal ClickTale value determining where data will be stored. Similarly to ProjectID, PartitionID should match the value that is generated for you by our tracking code generator.

ClickTaleGetVersion
Usage: ClickTaleGetVersion Since version: 12.5 The  function returns the version number of the ClickTale tracking code included in your page. Alternatively, this can be found in the debug information by appending  to the url. See ClickTale URL API

ClickTaleIsPlayback
Usage: ClickTaleIsPlayback This function returns 'true' when the page is in 'Playback mode' You may want to detect this condition and branch your code accordingly if some parts of your in-page JavaScript code are incompatible with the playback mechanism. If you are using this function, please don't check against "false". Use "!ClickTaleIsPlayback" instead. Also see ClickTaleExcludeBlock and JavaScript_API

ClickTaleTag
Usage: ClickTaleTag(Tag) This function allows you to add a ClickTale Event (a.k.a. Tag) to the current recording. Events allow you to identify recordings when browsing for them on your ClickTale account.

ClickTaleEvent
Usage: ClickTaleEvent(EventName) Since version: 12.0 This function allows you to add a ClickTale Event to the current recording. Events allow you to identify recordings when browsing for them on your ClickTale account. Synonymous with ClickTaleTag.



ClickTaleNote
Usage: ClickTaleNote(Note) This function allows you to add a note to the current recording. Notes are strings of text that will appear during the playback of the recording.

ClickTaleField
Usage: ClickTaleField(Field,Value) This function allows you to add a Field-Value pair to a recording. This pair will be available during the playback of the recording.

//to add field in recording //to access field in playback

Examples of use
//in recording

//in playback

//Playback Mode

ClickTaleIgnore
Usage: ClickTaleIgnore(Days) This function allows you to mark the current visitor as not-to-record for at least a period of 'Days' days. This will not affect existing or in-progress recordings (see ClickTaleStop ).

WRUID cookie
ClickTale will store the visitor's id in this cookie. A value of 0 means 'don't record' and any other value is an identification of the visitor. Lack of this cookie means that the visitor has not yet been classified by ClickTale or that they are using an unsupported browser.

ClickTaleCookieDomain
Usage: ClickTaleCookieDomain = "example.com" This variable contains the domain name on which the visitor-id cookie will be stored. By default the value is the current domain (minus the www. if present). If you want to aggregate monitoring of several sub-domains (such as  blog.example.com ,  example.com  and  www.example.com ), set this variable to be your domain name (example.com) before the call to the ClickTale function. Please Note: If you had a tracking code on a domain prior to adding the ClickTaleCookieDomain setting, please delete all cookies named/containing WRUID which are listed for this domain and any sub-domain it has, otherwise the existence of these old cookies might interfere with proper recording. Please note that in order to allow the recording of a number of sub domains - all of them need to be enabled for recording in your Manage Domains list. In the specific case where you have several domains, each having several sub-domains, you may find the following code useful. It will let you aggregate monitoring of several sub-domains for each main domain.

ClickTaleCookieExpiryDays
This variable allows you to change the default expiry of the ClickTale first-party tracking cookie (WRUID). This cookie enables ClickTale to know that a specific set of pageviews belongs to a unique visitor. The default value is 365 days. If you set the variable to false then the cookie will be a session cookie.

ClickTaleUIDCookieName and ClickTaleIgnoreCookieName
These variables contain the names that ClickTale will use to name the first-party cookies that it is using. The defaults are "WRUID" and "WRIgnore" respectively. Changing the values to other names will enable you to have separate ClickTale classification on a single domain, such that one classification (on some pages) could use a ratio that is different from another classification (used on other pages).

Set these variables before the call to ClickTale and after the WR javascript has been referenced.

Set these variables to "False" if user opts-out using cookies. In this case the recording process will not initiate.

ClickTaleUploadPage
Usage: ClickTaleUploadPage(Pre,Suf) This function initiates a process of uploading the page content to a ClickTale server from the visitor's browser. Normally, the ClickTale server will take the page content from your server by requesting the same page the visitor had requested. In some cases - such as password protected areas, session dependent pages and POST pages - requesting the page content from your server may not produce the correct response. One of the possible solutions is to call this function to initiate a transfer of the content directly from the visitor's browser.

Pros: Simple, effective. Cons: Puts load on the visitor's side. Not recommended for production environment and may affect customer experience. Mainly designed for making Offline recordings.

Call this function according to your tracking code type and specify the opening and closing tags (including DOCTYPE and ) that you are using in the recorded HTML page. (How can I find which code type my project is using?)

If you have code type Atlas, click 'Expand' below to see the instructions for placing your code. Click 'Collapse' to close the section.

If you have code type Balkan, click 'Expand' below to see the instructions for placing your code. Click 'Collapse' to close the section.

ClickTaleFetchFrom
This variable allows you to set an alternative URL that ClickTale will use to pull the page's HTML from. This is another technique that you can use to support POST and session dependent pages. When you assign a URL to this variable, ClickTale will not fetch the page's content from the URL that the visitor had requested but rather from the URL that you had supplied. You can supply URLs of static pages or dynamic GET pages. Pros: Doesn't affect your visitors. Cons: You have to define new pages or modify existing ones to support this kind of parameterization.

Also see ClickTaleFetchFromWithCookies

Syntax:

Example of use
Imagine that you have a contact form called "contact.html" and a contact processing page called "contact.php" that sends an email and displays a "Thank you" note. Normally, ClickTale would attempt to make an HTTP GET request for "contact.php". This request will probably fail as no correct POST parameters would be sent along with the request. In this case, if you would like to record the "Thank you" note page, you would have to either: This is known as a "Dummy Page".
 * save the content of the "contact.php" response into a static HTML file such as "contact_resp.html" and set it as the ClickTaleFetchFrom location in the following manner:

or


 * modify your php file to check for some GET parameters (for example, "ct=1") and as a result skip any processing (emailing, DB update, etc') and merely display the success message. In this case, set "contact.php?ct=1" as your ClickTaleFetchFrom location in the following manner:

ClickTaleEventsMask
Usage: ClickTaleEventsMask-=x; This variable allows you to customize the type of data that is recorded by ClickTale. By default all options are enabled. Subtract the following values to disable various features: 1 = mouse movement (mousemove) 2 = low level mouse clicks (mouseup, mousedown) 8 = high level mouse clicks (click, context) 4 = key strokes (keydown, keyup, keypress) 16 = coordinate correction data 32 = client javascript errors

These can be combined eg. to block recording of key strokes AND client javascript errors a value of 36 could be used. The line should be added before the call to the ClickTale function. For additional information, see also Sensitive_data

ClickTaleSetUID
Usage: ClickTaleSetUID(UID) Since version: 12.5 Call this function to set the ID of a specific visitor. A null or an empty string will result in the visitor not being recorded. A UID value in the form of two integer numbers concatenated with a dot will set the visitor ID value and they will be recorded.

ClickTaleGetUID
Usage: ClickTaleGetUID Call this function to get the ID of this visitor. Null is returned if this visitor is not recorded or if the decision to record has not taken place yet. Note: this function is broken in v10. See here for a solution.

ClickTaleGetSID
Usage: ClickTaleGetSID Call this function to get the ID of the specific page view. Null is returned if the recording hasn't started yet. Prerequisite: Define "function ClickTaleOnRecording" to receive an event when recording starts.

ClickTaleGetPID
Usage: ClickTaleGetPID Since version: 12.3 Call this function to receive the ID of the project used to record the page. Null is returned if the recording hasn't started yet. Prerequisite: Define "function ClickTaleOnRecording" to receive an event when recording starts.

ClickTaleExec
Usage: ClickTaleExec(code) This function enables you to integrate with DHTML sites. Call it to inject a javascript command into the recording. The command will be executed during playback exactly at this point in the timeline.

Example of use:
Imagine you have an HTML page with a button that when clicked shows a DIV HTML element. This is basically a simple case of a tab control or a DHTML menu. If the button onClick event is It would need to be changed to: As a result, the ClickTale player will execute the event during playback to provide a more accurate rendering of the browsing session.

Get more examples and use cases on the JavaScript Integration page.

An alternative approach to dynamic elements handling for ClickTale is the ActivePlayback API.

ClickTaleSensitive CSS Class
This is a CSS class that may be applied to individual HTML elements. ClickTale will not record any characters typed for an element if the element has this class assigned to it. This feature is designed for INPUT and TEXTAREA HTML elements, which contain sensitive information such as credit card numbers.

Example of use
or in case there is already a class assigned to the element: Please also see the following article: Sensitive data.

ClickTaleScriptSource
This variable allows you to set the location that you want to use to load the second part of the ClickTale tracking javascript file. Normally a second part is loaded from the ClickTale CDN in case a visitor is classified to be recorded. If you are hosting the external javascript files yourself, you will need to set this variable to the HTTP location where the additional WR*.js files are found.

Functionality Set 2 - The Recording Set
The second set of functions, the 'recording set' becomes available once a recording is in progress. You may want to check whether the recording set was loaded by using a line similar to this:

ClickTaleIsRecording
Usage: ClickTaleIsRecording Get an indication (Bolean T/F) if ClickTale is recording currently or not.

ClickTaleOnRecording
Usage: ClickTaleOnRecording Run any code when ClickTale starts recording.

ClickTaleStop
Usage: ClickTaleStop This function stops the recording while preserving what has been recorded up to this point. Recording can not be resumed for this pageview after a 'stop'

ClickTaleTerm
Usage: ClickTaleTerm This function stops the recording while deleting what has been recorded up to this point. Recording can not be resumed for this pageview after a 'terminate'

ClickTaleRebindEvents
Usage: ClickTaleRebindEvents Available since version: 12.5 Call this function to have ClickTale rebind its event listeners on the elements on the page. You might need to run it if you dynamically add new form elements to the page after tracking starts. Try this if you have a DHTML or an Ajax functionality that generates forms and you can't see the form in playback or in Form Analytics.

Functionality Set 3 - Before Main Script
Some properties can be set to control the loading of the main script

ClickTaleIncludedOnDOMReady
Usage: window.ClickTaleIncludedOnDOMReady=true; Available since version: 12 Set this variable to true if you intend to add the ClickTale main script to the DOM programmatically on 'domload' as opposed to by including the "bottom tracking code" near the closing tag. Usually, in such cases you would also implement the function "ClickTaleOnReady" to continue configuration/setup once the main script has been loaded.

Inline variants
When you require the use of the API functions before the scripts are loaded, you may use these inline variants:

Inline ClickTaleIsPlayback
Usage: inline ClickTaleIsPlayback

Additional API Commands
All the commands in this section are available from version 13 onward

ClickTaleRegisterFormSubmitSent(form)
Call to declare that the form submit attempt passed validation and was sent to the server side. If not used, heuristics will be used to determine whether the form has been submitted successfully.

ClickTaleRegisterFormSubmitNotSent(form)
Call to declare that the form submit attempt did not pass validation and wasn’t sent to the server side. If not used, heuristics will be used to determine that the form has not been submitted successfully.

ClickTaleRegisterFormSubmitSuccess(form)
Call to declare that the form submit attempt passed the server side validation and is processing. If not used, heuristic will be used and consider every “sent” form submit as “success”. Pass the “form” parameter on the same page view when handling AJAX submission (and similar). Don’t pass (the optional) “form” param when dealing with standard POSTs and declaring the “hint” in the following pageview to the pageview where the submit attempt happened.

ClickTaleRegisterFormSubmitFailure(form)
Similar to ClickTaleRegisterFormSubmitSuccess, but for a failure of submission.

window.ClickTaleSettings.LocationRewriter
Change current URL programmatically, using URL or function.

window.ClickTaleSettings.ReferrerRewriter
Change previous URL (referrer) programmatically, using URL or function.

URL API

 * see also: ClickTale URL API

ClickTale enables you to perform some of the API functionalities simply by adding parameters to your URL without needing any programming. With the URL API you are able to:
 * Add events to any pageview.
 * Debug your ClickTale code.
 * Enable or disable a visitor from being recorded on the site.

Example: To add an event that tags all visitors to the URL  http://domain/page  with the event "SEM" you should add the ct parameter to the URL using ? or # as shown below
 *  http://domain/page?ct=t(SEM)  or
 *  http://domain/page#ct=t(SEM) 

For URLs already containing parameters, such as  http://domain/page?param=x  the ct event parameter can be added using & or #:
 *  http://domain/page?param=x&ct=t(SEM)  or
 *  http://domain/page?param=x#ct=t(SEM) 

The value of the ct parameter is a comma-separated list of ClickTale URL API commands. Commands can be combined in a comma-separated list, for example:  http://domains/page?ct=debug,enable,t(record) 

The commands are:
 * t([event name]) - adds an event to the page view (please note: The URL API cannot accept event names that contain a comma) e.g.: http://wwww.yourdomain.com?ct=t(special_event)
 * debug - shows the debug information
 * enable - marks the visitor as "to be recorded" disregarding the ratio
 * disable - marks the visitor as "not to be recorded" disregarding the ratio
 * reset - resets visitor ID which causes the user to be re-classified based on the ratio
 * u([UID]) - sets the UID of the visitor to the value in parenthesis. Useful if you need to track the visitor across two domain being recorded into a single ClickTale project, such as shop and checkout domains. e.g.: http://wwww.yourdomain.com?ct=u(123456) Available from version 12.5 of the tracking code.