Help talk:OsCommerce Integration Module

This Integration module is for sites built with OsCommerce 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 above code into the appropriate parts in the ClickTale/ClickTaleScripts.xml file. Add: Just before the line '''Please note: You do not need to change "%FetchFromUrl%" to a specific URL. It will be replaced automatically during the rendering process, with a value dependent on the page being recorded.''' Your xml file should now look like this: Code V2 to be inserted here

PLEASE NOTE: This is how the code looks like in a text editor. In a browser, "&amp;lt;" will be converted to "<" and "&amp;gt;" will become ">"

PLEASE ALSO NOTE: This code sample relates to HTTP tracking code only! for a version of the tracking code which can record both HTTP and HTTPS pages you should first make sure your plan enables the recording of HTTPS pages (check if the option is available in the tracking code generation page), then generate SSL/HTTPS compliant code and use it in step 6 instead (you should still add the ClickTaleFetchFrom command, right before the line var ClickTaleSSL=1; or between 2 lines var ClickTaleSSL=1; and ClickTale([your ClickTale parameters]); ).

Add to header and footer
Every page you wish to be recorded should contain the following PHP code: A - Paste in to the \catalog\includes\application_top.php file, at the very top of the file.

B - Paste in to the \catalog\includes\application_bottom.php file, at the very bottom of the file. 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 osCommerce installation folder.

Example 

application_top.php file  <?php /* $Id$ osCommerce, Open Source E-Commerce Solutions http://www.oscommerce.com Copyright (c) 2008 osCommerce Released under the GNU General Public License */ // start the timer for the page parse time log define('PAGE_PARSE_START_TIME', microtime); . ..

application_bottom.php file

if (DISPLAY_PAGE_PARSE_TIME == 'true') { echo ' Parse Time: '. $parse_time. 's '; } }  if ( (GZIP_COMPRESSION == 'true') && ($ext_zlib_loaded == true) && ($ini_zlib_output_compression < 1) ) { if ( (PHP_VERSION < '4.0.4') && (PHP_VERSION >= '4') ) { tep_gzip_output(GZIP_LEVEL); } }  <?php require_once("\www\clicktale\ClickTaleBottom.php"); ?>

Create two directories named "Cache" and "Logs" under the 'ClickTale' directory. Make sure they have writing permissions, for instance:</li>
 * 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.

</li>
 * 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 of the form 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 (IPs of ClickTale servers) and only processes which already have access to the page have the unique token required to request the cached content.


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