JavaScript API

From ClickTale Wiki
(Redirected from ClickTaleFetchFrom)
Jump to: navigation, search

Contents

This article describes the functionality of the ClickTale Recording Time JavaScript API. This relates to 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 collection of needed information during recording to allow for proper playback and reports later. Calls to this API are performed at recording time.

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

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 (that looks similar to this): 

<script src="http://s.clicktale.net/WR[xxx].js" type="text/javascript"></script>

You can be notified when ClickTale's main script has been loaded if you define "function ClickTaleOnReady()".

ClickTale

Usage: ClickTale(ProjectID,RecordingRatio[,PartitionID])
This is the main function of ClickTale and is part of the auto-generated 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
This function returns the version number of the ClickTale tracking code you have included in your page. Version information is also shows as part of the debug information available when you append ?ct=debug to the url. See JavaScript_API#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. Don't check against "false". Use "!ClickTaleIsPlayback()" instead.
Also see ClickTaleExcludeBlock and JavaScript_API#Inline ClickTaleIsPlayback

ClickTaleTag

Usage: ClickTaleTag(Tag)
This function allows you to add an ClickTale Event (aka tag) to the current recording. Events allow you to identify recordings when browsing for them in the subscriber's area.

ClickTaleEvent

Usage: ClickTaleEvent(EventName)
Since version: 12.0
This function allows you to add an ClickTale Event to the current recording. Events allow you to identify recordings when browsing for them in the subscriber's area. 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.

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 identifies the visitor. Lack of this cookie means that the visitor has not yet been classified by ClickTale() or that he is unsupported.

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.

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. 

var CTcoodom = document.location.hostname.split(".");
var CTdomfin = new String();
for (i = 1; i < CTcoodom.length; i++) {
    if (i == 1) {
        CTdomfin += CTcoodom[i];
    }
    else {
        CTdomfin += "." + CTcoodom[i];
    }
}
ClickTaleCookieDomain = CTdomfin;

ClickTaleCookieExpiryDays

This variable allows you to change the default expiry of the ClickTale first-party tracking cookie. This cookie enables us 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).

ClickTaleUploadPage

Usage: ClickTaleUploadPage(Pre,Suf)
This function initiates a process of uploading the page content to a ClickTale server from the client's browser. Normally, the ClickTale server will take the page content from your server by requesting the same URL that the user had visited. 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 client.

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

Call this function before the call to ClickTale() and specify the opening and closing tag (including DOCTYPE and <html>) that you are using in the recorded HTML page. Example: 

<!-- ClickTale Bottom part -->
<div id="ClickTale" style="display: none;"></div>
<script src="http://s.clicktale.net/WRb.js" type="text/javascript"></script>
<script type="text/javascript">
if(typeof ClickTaleUploadPage=='function') ClickTaleUploadPage('<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html>','</html>');
if(typeof ClickTale=='function') ClickTale([your PID],[your ratio]);
</script>

Please Note: The "Pre" parameter (the first parameter in the function call) should match the beginning of your page HTML, therefore you must configure it accordingly (e.g. in the example above this function call would be used for pages starting with <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html>. The "Suf" parameter (the second parameter in the function call) should match the ending of your page HTML. In most cases </html> is appropriate.

ClickTaleFetchFrom

This variable allows you to set an alternative URL that ClickTale will use to access the page's content. 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 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.
Set this variable before the call to ClickTale().
Also see ClickTaleFetchFromWithCookies

Syntax: 

ClickTaleFetchFrom="http://some_site/some_dir/some_alternate_page.html";

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 a HTTP GET request for "contact.php". This request will probably fail as no correct POST parameters will be sent to you. Still, if you would like to record the "Thank you" note page, you would have to either:

  • 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 like this: 
ClickTaleFetchFrom="http://some_site/contact_resp.html";

or

  • modify your php file to check for some GET parameters such as "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 like this: 
ClickTaleFetchFrom="http://some_site/contact.php?ct=1";

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.

ClickTaleSetUID

Usage: ClickTaleSetUID(UID)
Since version: 12.5
Call this function to set the ID of this visitor. Null or empty string will result the visitor to not be recorded. Proper UID value in a form of two integer numbers concatenated with a dot will set the visitor ID value (UID) in the appropriate cookie.

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 this page view. Null is returned if the recording hasn't started yet. Preliminary: Define "function ClickTaleOnRecording()" to receive an event when recording starts.

ClickTaleGetPID

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

ClickTaleExec

Usage: ClickTaleExec(code)
This function helps you 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 

function ButtonClicked()
{
  pane.style.display="block";
}

you will change it to 

function ButtonClicked()
{
  if(typeof ClickTaleExec=='function')
    ClickTaleExec("ButtonClicked()");
  pane.style.display="block";
}

As a result, the ClickTale player will execute the event during playback to provide a more accurate rendering of the browsing session.

ClickTaleSensitive CSS Class

This is a CSS class that you can apply 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 that contain sensitive information such as a credit card number.

Example of use

<input id="CCNum" type="text" class="ClickTaleSensitive">

or if you already have a class set for the element then: 

<input id="CCNum" type="text" class="red long ClickTaleSensitive">

Please also see an article about Sensitive data.

ClickTaleScriptSource

This variable allows you to set the location on the web that you want to use to load the second part of the ClickTale tracking javascript file. Normally a second part if loaded from the ClickTale CDN if the visitor is classified to be recorded. If you are hosting the external javascript files yourself, including the second part of the tracking code, then you will need to set this variable to the HTTP url root of 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 running. You may want to check whether the recording set was loaded by using a line similar to this: 

if(typeof ClickTaleStop=='function')

You can be notified when a recording is running if you define "function ClickTaleOnRecording()".

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 page-view 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 page-view after a 'terminate'

ClickTaleRebindEvents

Usage: ClickTaleRebindEvents()
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 started. Try this if you have DHTML or Ajax functionality that generates forms and you can't see form playback or form analytics on the recorded data.

Functionality set 3 - Before main script

Some properties can be set to control the loading of the main script

ClickTaleIncludedOnDOMReady

Usage: window.ClickTaleIncludedOnDOMReady=true;
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 </body> tag. Usually in such cases you would also implement "function ClickTaleOnReady()" to continue configuration/setup once the main script has been loaded.

Inline variants

When you need to use the API functions before the scripts are loaded, you can use these inline variants instead:

Inline ClickTaleIsPlayback

Usage: inline ClickTaleIsPlayback()

function CTIsPlayback() {
   try { return parent && parent.WebPlayer; }
   catch(e) { return false; }
}

Url API

ClickTale enables you perform some of the API functionality simply by adding Url parameters to your Url without having to do any javascript programing.
With Url API you can:

  • Tag the pageview with any tag. (read about tags here)
  • Perform debugging of your ClickTale code.
  • and Enable or disable the visitor from being recorded on the site

Let's start with an example. If you want to tag any visitor that comes to http://domain/page with the tag "SEM" you need to change the Url as follows:
http://domain/page ->
http://domain/page?ct=t(SEM) or
http://domain/page#ct=t(SEM)

http://domain/page?param=x ->
http://domain/page?param=x&ct=t(SEM) or
http://domain/page?param=x#ct=t(SEM)

The guide line is that you need to add a parameter called "ct" or "clicktale" either in the query ("?") part of the Url or in the hash ("#") part of the Url. The value of the parameter is a comma separated list of ClickTale Url API commands. The commands are:

  • t([tag name]) - adds a tag to the pageview (while using this API, you can't have tag names that contain a comma)
  • debug - shows debug information
  • enable - marks the visitor as "to record" disregarding the ratio
  • disable - marks the visitor as "not to record" 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 this visitor to the value in parenthesis. Useful if you need to track the visitor across two of your domain that you record to a single ClickTale project, such as shop and checkout domains. Available since version 12.5 of the tracking code.

You can combine commands as shown in the next example: http://domains/page?ct=debug,enable,t(record)

Retrieved from "http://wiki.clicktale.com/index.php?title=JavaScript_API&oldid=2864#ClickTaleFetchFrom"
Personal tools