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

'''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, according to the type of code you are using: 

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

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

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


 * Modify the configuration according to the instructions below:


 * If you have code type Atlas, click 'Expand' below and perform step 3 as described. Click 'Collapse' to close the section.


 * If you have code type Balkan, click 'Expand' below and perform step 3 as shown here. Click 'Collapse' to close the section.

 4. If you are using this file as your configuration file, please save it as "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.  Example 1: Blocking by IP 

NOTE: Blocking recordings by IP is also possible using the account UI. See this article.

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

 Example 2: Recording by visitor country </P>

This script will cause only visitors from the UK to be recorded in ClickTale.

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 </P> Values: record, norecord, off.  time_zone </P> 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 </P> The time to start/stop recording (or not recording). In (HH:mm 24 Hour Format) Values from 00:00 - 23:59.  day </P> The days of the week to record. Values: off, the digits 1-7, separated by commas.  Example 3: Recording by time </P> 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".  Example 4: Recording by time and day </P>

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 </P> Values: off, blacklist, whitelist.  mode </P> Values: simple, regex.  urlX </P> The list of referrer URL's. When using regex mode, these must be valid regular expression patterns, or preg_match will fail.
 * simple - searches if any of the strings in [referer_list] appear anywhere in the URL.
 * regex - matches using regular expression patterns.

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 </P>

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 </P> Values: off, blacklist, whitelist.  mode </P> Values: simple, regex.  refX </P> The list of referrer URL's. When using regex mode, these must be valid regular expression patterns, or preg_match will fail.
 * simple - searches if any of the strings in [referer_list] appear anywhere in the URL.
 * regex - matches using regular expression patterns.

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 </P>

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 server and specify a relative path.