JavaScript API

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


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):

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


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 ClickTaleGetVersion 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 ?ct=debug 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#Inline ClickTaleIsPlayback

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.

<br\>

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

  ClickTaleField('field_name', value);

//to access field in playback

  context.fields.field_name

Examples of use

//in recording

  ClickTaleField('mm_pd', 12345);

//in playback

  if(CTIsPlayback()){

//Playback Mode

    if(typeof window.ClickTaleContext == "object" && typeof ClickTaleContext.getRecordingContextAsync == "function") {
            ClickTaleContext.getRecordingContextAsync("1.1", function(context) {
                if(typeof context.fields.mm_pd != 'undefined') mmcore.SetCookie('pd', context.fields.mm_pd, 365);
            });
    } 
}

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.
  • 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.
  • The sub-domains referred in the above manner will still count for your total allowed domains. Make sure you have enough domains left in your plan and that the sub-domains are checked in the Domains list.


The added code should be placed according to your code type, as outlined in this Code Placement article.



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.

If you have code type Atlas, click 'Expand' below to see the code you should use. Click 'Collapse' to close the section.

 
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;


If you have code type Balkan, click 'Expand' below to see the code you should use. Click 'Collapse' to close the section.

 
<!-- ClickTale Bottom part -->
<script type='text/javascript'>
 
// The ClickTale Balkan Tracking Code may be programmatically customized using hooks:
//
   function ClickTalePreRecordingHook() {
window.CTcoodom = document.location.hostname.split(".");
window.CTdomfin = new String();
for (i = 1; i < CTcoodom.length; i++) {
    if (i == 1) {
        CTdomfin += CTcoodom[i];
    }
    else {
        CTdomfin += "." + CTcoodom[i];
    }
}
ClickTaleCookieDomain = CTdomfin;
  }
//
// For details about ClickTale hooks, please consult the wiki page
 
http://wiki.clicktale.com/Article/Customizing_code_version_2
 
document.write(unescape("%3Cscript%20src='"+
(document.location.protocol=='https:'?
"https://clicktalecdn.sslcs.cdngc.net/wwwXX/ptc/xxxxxx-xxxx-xxxx-xxx-xxxxxx.js":
"http://cdn.clicktale.net/wwwXX/ptc/xxxxxx-xxxx-xxxx-xxx-xxxxxx.js")+"'%20type='text/javascript'%3E%3C/script
 
%3E"));
</script>


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 before the call to the ClickTale() function and specify the opening and closing tags (including DOCTYPE and <HTML>) that you are using in the recorded HTML page.

Example:

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

 
<!-- ClickTale Bottom part -->
<div id="ClickTale" style="display: none;"></div>
<script src="http://cdn.clicktale.net/WRe0.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([ProjectID],[RecordingRatio],["PartitionID"]);
</script>

Important Note:
The "Pre" parameter (the first parameter in the function call) should match the beginning of your page's HTML, therefore it should be configured accordingly.
So in the example above, this function call would be used ONLY 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's HTML. In most cases </HTML> is appropriate.


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

 
<!-- ClickTale Bottom part -->
<script type='text/javascript'>
 
// The ClickTale Balkan Tracking Code may be programmatically customized using hooks:
// 
   function ClickTalePreRecordingHook() {
     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>');                                       
      }
//
// For details about ClickTale hooks, please consult the wiki page http://wiki.clicktale.com/Article/Customizing_code_version_2
 
document.write(unescape("%3Cscript%20src='"+
(document.location.protocol=='https:'?
"https://clicktalecdn.sslcs.cdngc.net/wwwcc/ptc/xxxxxx-xxxx-xxxx-xxx-xxxxxx.js":
"http://cdn.clicktale.net/wwwxx/ptc/xxxxxx-xxxx-xxxx-xxx-xxxxxx.js")+"'%20type='text/javascript'%3E%3C/script%3E"));
</script>
<!-- ClickTale end of Bottom part -->


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

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

This is known as a "Dummy Page".

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:
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. The line should be added before the call to the ClickTale() function. For additional information, see also Sensitive_data#ClickTaleEventsMask

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

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

It would need to be changed 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.

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

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

or in case there is already a class assigned to the element:

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

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:

if(typeof ClickTaleStop=='function')

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 </body> 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()

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

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.


ClickTaleSettings

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.