JavaScript API
From ClickTale Wiki
[edit] 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>
[edit] 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.
[edit] 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.
[edit] 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.
[edit] 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.
[edit] 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.
[edit] 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() ).
[edit] 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 the name of your top level domain (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 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.
[edit] ClickTaleUnloadPause
ClickTale performs a pause before allowing the document to unload. This pause is required to allow the last packet of information to be sent. The default recommended value is 200ms. Increasing the value of this variable will reduce the number of corrupt recording but will increase the exit time of pages. You can set another positive value if you prefer.
[edit] 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.
[edit] 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 will hurt customer experience. Mainly for making Offline recordings.
Call this function before the call to ClickTale() and specify the opening and closing tag (including DOCTYPE) 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>
The default for "Suf" is </html> so you can omit it in most of the cases and accept the default. The default for "Pre" is <html> which is a bad choice in most cases, so you are encouraged to supply it.
[edit] 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.
Call this function before the call to ClickTale().
[edit] 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 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.
[edit] 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
[edit] ClickTaleGetUID
Usage: ClickTaleGetUID()
Call this function to get the ID of this visitor. Null is returned if this user 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.
[edit] ClickTaleGetSID
Usage: ClickTaleGetSID()
Call this function to get the ID of this page view. Null is returned if recording haven't started yet.
Preliminary: Define "function WRoninit()" to receive an event when recording starts.
[edit] 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.
[edit] 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.
[edit] 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.
[edit] 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">[edit] 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.
[edit] 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')
[edit] 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'
[edit] 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'
[edit] Inline variants
When you need to use the API functions before the scripts are loaded, you can use these inline variants instead:
[edit] Inline ClickTaleIsPlayback
Usage: inline ClickTaleIsPlayback()
function CTIsPlayback() { try { return parent && parent.WebPlayer; } catch(e) { return false; } }
[edit] 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
You can combine commands as shown in the next example: http://domains/page?ct=debug,enable,t(record)
