PHP Control Script

The ClickTale Control Script is a PHP script intended to help filter the visitors recorded. It allows you to set filters and distinguish the visitors you are interested in recording from the ones you are not interested in recording. A few examples of the filters are: Time, IP, Country of Origin.

'''Please note: your site does not have to be a PHP site in order to use this script. Your web server should include the option of running PHP. PHP support can be added to all versions of IIS'''.



Requirements
A Server running PHP (version 5.X). The ClickTale control script is a PHP script intended to help filter the visitors recorded. It allows you to set filters and distinguish the visitors you are interested in recording from the ones you are not interested in recording. A few examples of the filters are: Time, IP, Country of Origin.

'''Please note: your site does not have to be a PHP site in order to use this script. Your web server should include the option of running PHP. PHP support can be added to all versions of IIS'''

Installation

 * 1. Download and extract the script package (3 files) to your server.
 * 2. Replace the following section in the existing code on your recorded pages:


 * If you have code type Atlas, click 'Expand' below to see the instructions for placing your code. Click 'Collapse' to close the section.  (How can I find which code type my project is using?)


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

Please note: The <script src="ClickTaleControl.php" section should point to the actual location of the ClickTaleControl.php file on your server.


 * 3. Open the Configuration file (ClickTaleControl-sample.ini) from the installation location.


 * 4. Make the following changes in the file, according to your project's tracking code type.


 * If you have code type Atlas:  (How can I find which code type my project is using?)


 * If you have code type Balkan:


 * 5. If you are using the file as your configuration file, please change its name to ClickTaleControl.ini

Editing the Configuration File

 * Multiple configuration files can be created, and used by sending a parameter to the script. For Example:


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

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.

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.

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


 * geoip.inc can be extracted from the packages available on the PHP section of this page. Make sure to match your PHP version.
 * geoip.dat can be downloaded from the Downloads section of this page.

There is also a list of country codes you may need.


 * 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".

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:

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

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.

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:

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

with:

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.

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.