PHP control script

The ClickTale control script is a PHP script intended to help you filter the visitors you want to record. It allows you to set filters, such as time, day of the week, IP address, country, referral address & URL.

Please note: your site does not have to be a PHP site in order to use this script. PHP support can easily be added to all versions of IIS

Requirements

Server running PHP (version 5.X).

Installation

1. Download and extract the script package (3 files) to your website.
2. Open the Configuration file (ClickTaleControl.ini) and edit the rules of filtering (See "Configuration file" section).
3. Replace the existing code in your recorded pages from:

    <!-- ClickTale Bottom part -->
    ...
    <script src="[... some url ...]/WRb.js" type="text/javascript"></script>
    ...
    <!-- ClickTale end of Bottom part -->

to:

    <!-- ClickTale Bottom part -->
    ...
    <script src="ClickTaleControl.php" type="text/javascript"></script>
    ...
    <!-- ClickTale end of Bottom part -->

Please note:

1. Only the reference to the WRxx.js file should be changed the remainder of the tracking code is still required.
2. The previous example is for recording http pages. To record https pages you need to place the files in an https location and change the path in the tracking code accordingly.
   
3. The <script src="ClickTaleControl.php" section should point to the actual location of the ClickTaleControl.php file.

The configuration file

• The default configuration file is called ClickTaleControl.ini
• Multiple configuration files can be created, and used by sending a parameter to the script. For Example:

    <script src="ClickTaleControl.php?config=c2.ini" type="text/javascript"></script>

• A configuration file can consist of all or any of the filter rules. (Any unlisted rule default to "off")

Filter reference

script

The ClickTale tracking code url to execute if all rules pass.

rec_repeat_always

When "on", visitors who have been recorded previously will be recorded regardless of filter rules.

    script = "http://s.clicktale.net/WRb.js"
    rec_repeat_always = "off" 

IP filters

Its settings are:

filter

This parameter allows you to filter your visitors by their IP address. Values: off, blacklist, whitelist.

ip_maskX

A list of IP masks. Valid formats: 127.*.*.*, 127.0.0.0/8, 127.0.0.0/255.0.0.0
Please note: The "filter" setting must come after [ip]. Your IP masks must come after [ip_list], and they each have to have a unique number.

Example 1: Blocking by IP

    script = "http://s.clicktale.net/WRb.js"

    [ip]
    filter = "blacklist"
    [ip_list]
    ip_mask1 = "80.100.*.*"
    ip_mask2 = "80.200.0.0/16"
    ; This filter will not record visitors whose IP starts with 80.100, or 80.200

Country filter

This filter allows you to record (or not record) visitors from specific countries. Its settings are:

filter

Values: off, blacklist, whitelist.

mode

Values: http, db.

db_path

Path to GeoLite files. (geoip.inc, GeoIP.dat. See Notes below) (Required in db mode)

countryX

A list of countries.
Please note:

• The "filter" setting must come after [country]. Your countries must come after [country_list], and they each have to have a unique name.
• Both modes implemented in this script use free Geolocation services. The http mode uses the api from hostip.info.
• The db mode in this script uses the MaxMind GeoLite Country API. If you plan on using this option (much faster than using the http service) you will need to download the database file and api from the above link, and copy them to your website. (Specifically, you will need "geoip.inc" & "GeoIP.dat") Country Codes
• You have to check that you don't violate the license terms of the db provider.
• Advanced Users: You can implement different http or db services if you wish, by updating the functions getCountryDB & getCountryIP in "ClickTaleControl_lib5.php".

Example 2: Recording by visitor country

    script = "http://s.clicktale.net/WRb.js"

    [country]
    filter = "whitelist"
    mode = "db"
    db_path = "geoip/"
    [country_list]
    country1 = "us"
    country2 = "ca"
    country3 = "gb"
    ; recording US, Canada and UK visitors.

Day and time filters

These filters can let you record your visitors (or not record) during specific hours of the day, or specific days of the week. Their settings are:

time

Values: record, norecord, off.

time_zone

Allows you to set the timezone to calculate the time (optional). List of supported timezones: http://www.php.net/manual/en/timezones.php.

time_start/stop

The time to start/stop recording (or not recording). In (HH:mm 24 Hour Format) Values from 00:00 - 23:59.

day

The days of the week to record. Values: off, the digits 1-7, separated by commas.

Example 3: Recording by time

Please note: When defining the times, both hours must be on the same day. You should achieve the preferred hours of recording with the record/norecord values. For example, if we wanted to only record from 22:00-06:00, we would have the following setting:

    script = "http://s.clicktale.net/WRb.js"

    time = "norecord"
    time_start = "06:00"
    time_stop = "22:00"

And the opposite - to stop recording from 22:00-06:00 the "time" parameter should be switched to "record".

Example 4: Recording by time and day

    script = "http://s.clicktale.net/WRb.js"

    time = "record"
    time_start = "10:00"
    time_zone = "America/New_York";
    time_stop = "20:00"
    day = "5,6,7"
    ; This setting will record on Friday,Saturday and Sunday, between 10:00AM to 20:00(8PM)

URL filter

This filter lets you filter the actual page that is calling this script. This is useful if you would like to stop a page from recording without removing the ClickTale code from your files. Its settings are:

filter

Values: off, blacklist, whitelist.

mode

Values: simple, regex.

• simple - searches if any of the strings in [referer_list] appear anywhere in the URL.
• regex - matches using regular expression patterns.

urlX

The list of referrer URL's. When using regex mode, these must be valid regular expression patterns, or preg_match() will fail.

Please note: The "filter" & "mode" settings must come after [url]. Your URL's must come after [url_list], and they each have to have a unique name.

Example 5: Blocking by URL

    script = "http://s.clicktale.net/WRb.js"

    [url]
    filter = "blacklist"
    mode = "simple"
    [url_list]
    url1 = "index.php"
    url2 = "index.html"
    url3 = "test.php"

Referrer Filter

This filter allows you to record (or not record) visitors who came from a specific website. In order for this to work, you will need to pass the referrer url to the script with the GET paramater ref. If the page you are recording is .php, this can easily be done like so:

        <script src="ClickTaleControl.php?ref=<?php echo $_SERVER['HTTP_REFERER']; ?>" type="text/javascript"></script>  

If your page is not php, you can do this with Javascript. Replace:

           <script src="ClickTaleControl.php" type="text/javascript"></script>

with:

           <script type="text/javascript">
            var ctscript = '\<script type="text/javascript" src="ClickTaleControl.php?ref=' + document.referrer + '"><\/script>';
            document.write(ctscript)
           </script>

The filter settings are:

filter

Values: off, blacklist, whitelist.

mode

Values: simple, regex.

• simple - searches if any of the strings in [referer_list] appear anywhere in the URL.
• regex - matches using regular expression patterns.

refX

The list of referrer URL's. When using regex mode, these must be valid regular expression patterns, or preg_match() will fail.

Please note: The "filter" & "mode" settings must come after [referer]. Your URL's must come after [ref_list], and they each have to have a unique name.

Example 6: Blocking by referrer

    script = "http://s.clicktale.net/WRb.js"
 
   [referer]
    filter = "blacklist"
    mode = "regex"
    [ref_list]
    ref1 = "/forbiddenwebsite.com/"
    ref2 = "/^http:\/\/badsite/"
    ; this rule will not pass if "forbiddenwebsite.com" appears anywhere in the ref URL, or if it begins with "http://badsite"

Testing your settings

After installing and setting up your configuration file, you can open your browser directly to the script (http://www.example.com/ClickTaleControl.php).
If you are supposed to record this session (according to the rules you configured), you should see the contents of the recording script. If your configuration file was not configured properly, you should see the proper errors.
If you receive an empty page do the following to understand if a rule wasn't configured correctly or if your server is having a problem fetching the script:

1. Clear your cookies.
2. Reopen the page in your browser with the GET parameter debug: http://www.example.com/ClickTaleControl.php?debug
3. If all rules pass, then either the script setting in the .ini is not configured correctly, or your server is blocked from downloading the external script. In which case, try to save the script to your local and specify a relative path.