PHP integration module

This Integration module is for sites built with PHP and using content which changes for each user independently (Shopping cart pages are often such pages). The module will allow you to store the exact version of the page that the user had seen and allow the ClickTale bot to fetch that version of the page so it is available for viewing during playback and for aggregated reports (Heatmaps, Form Analytics reports).

The module is PHP5 based, it is provided with full sources, that allows better integration of a PHP site with ClickTale, enabling accurate caching of the HTML that is sent to the visitor in the recorded pageviews.

If you are unable to install a binary module on your site, or if you have an older version of PHP (prior to Version 5), please use the FetchFromWithCookies method instead.

Installation Guide
 The module itself can be found here. Extract the archive to a directory named "ClickTale" on your website. You do not need to create a directory named "ClickTalePHPIntegrationModule_X.X" in it. Simply place the files in ".../ClickTale/". Generate the ClickTale tracking code you wish to use in your pages. Copy and paste the tracking code into the appropriate parts in the ClickTale/ClickTaleScripts.xml file. Add the cache fetching redirection code, according to your tracking code type:    (How can I find which code type my project is using?) 

Add to header and footer
Every page you wish to be recorded should contain the following PHP code: A - At the top (before any content is sent, i.e. before the Doctype and opening HTML tag, this is to ensure the entire page is captured including the section.)

B - At the bottom (after all content has been sent, including the closing HTML tag).

Make sure to replace [physical_path_to_clicktale_dir_here] with the relevant folder. Create two directories named "Cache" and "Logs" under the 'ClickTale' directory. Make sure they have writing permissions, for instance:
 * If you are using Apache with mod_php then the Cache and Log directories should be writable by Apache.
 * If the PHP is executed by some other means (CGI, for instance), it is possible that it is executed under a different user than that of the web server. In that case, it might be simpler to set the permissions for those directories to 777.


 * For windows machines, the directories should be writable by the webserver.

Tip: see Selective Recording to disable or enable yourself from being recorded. Apply this to everyone who is working in the organization, otherwise they may use a part of your account's recording quota. You may enable the option to be recorded for testing purposes.</ol>

Troubleshooting
After the files are copied you can navigate to  http://yoursite/ClickTale/Install/index.php  to view some helpful information regarding caching and other configuration settings. You may delete the Install folder in case you don't need the troubleshooting/debugging assistance it provides. Deleting it prevents some of your configuration setting from being publicly available.

Configuring the caching provider
The Integration Module caches the content of the pages so it can later provide the content to the ClickTale servers for processing. This caching requires some persistent storage,thus, different caching providers are supported. The default caching provider is the file system ("cache" folder). ClickTale recommends using the MySQLMemory provider. Doing so requires a valid connection to a MySQL database.

Another option is using the APC module. More details about APC can be found here.

After installing APC or MySQL, you can enable its provider by editing config.php file, and changing: to or

Note: The file-system provider will need write permissions to the "ClickTale/Cache" folder.

FileSystem

 * $config['DeleteAfterPull'] = (true / false)
 * If true, the cached page is deleted after clicktale fetches it from your site
 * $config['CacheLocation'] = (path to directory)
 * Where the cache files should be saved. This directory should be writable (you can use the Install/index.php to check write permissions)
 * $config['MaxFolderSize'] = (integer)
 * The size of the cache dir in MegaBytes. If the cache gets larger than that, stale caches are removed

MySQLMemory

 * $config['DeleteAfterPull'] = (true / false)
 * See FileSystem
 * $config['CacheLocation'] = (mysql url)
 * URL in this format: http:// : @ : /

For the second server:

and so on.

Using cookies for accessing a specific server
Some load balancers use an HTTP cookie to assign a specific visitor to a specific server permanently. This is often called "Sticky Sessions". If you know that such a cookie exists in your environment, you should be able to have the Bot reach the original server by recording the cookie value. This is done using the ClickTaleFetchFromWithCookies API. To do so, change the ClickTaleFetchFrom line to: Where [!COOKIENAME!] is the name of the cookie that maintains the visitor's affinity to a specific server.

Troubleshooting and debugging
The module's log files are located in: "ClickTale/Logs/Log_{0}.txt", where {0} is the log file's date.

There are 3 settings which need to be modified in order to produce a detailed log of the Module's activity. All settings may be found in the config.php file:

1. $config['AllowDebug'] = true; Provides the basic log.

2. $config['LogCaching'] = true; Provides a log with entries regarding the caching process.

3. $config['LogFetching'] = true; Provides a log with entries regarding the fetching process.

License
The module is subject to a permissive license for ClickTale users. Please see license.txt in the archive for more information.

Q&A
Q: Are cached pages protected from being accessed by third party elements?
 * A: Yes, several layers of protection are in place. Only certain IPs are allowed to request the cached pages ("AllowedAddresses") and only processes which already have access to the page have the unique token required to request the cached content.
 * If you want to redirect unauthorized access attempts to a certain page, set the following parameter in config.php - $config['FetcherUnauthorizedURL'] = ""; where  the URL is in the " ".
 * Any unauthorized attempt to access ClickTaleCache.php will be redirected to the URL specified. Leave blank for no redirection.

Q: Is it possible to inject the script in other places rather than after/before body tags?
 * A: Yes. By default the top script is injected after and the bottom before, but this can be changed by adding an 'InsertAfter' attribute to the script[name="Top"] element or by adding a InsertBefore attribute to the script[name="Bottom"] element, both are regular expressions.

Q: Some of my pages already have the ClickTale script, I do not want the script to appear twice.
 * A: You should either remove the script from those pages and let the module handle the insertion or you should use the DoNotReplaceCondition. See step 2 for an example. The default script in Step 2 is already configured to prevent double inclusion.

'''Q: After installing the module, I tried to watch a recording but I got the following notice instead: "Request from an unauthorized IP." . What should I do?'''
 * A: This could be a misconfiguration, a change in our IP addresses or a hacking attempt. Please contact us so we can investigate this further.

'''Q: I have installed the module but I don't see the tracking code in the source of the page. What is wrong?'''
 * A: The module will only inject the code for visitors who are classified as "to-record" (have the WRUID cookie with non-zero value) or for those who are not classified (no WRUID cookie). Visitors who are classified as "not-to-record" will not get the code.