PHP integration module

From ClickTale Wiki

Revision as of 11:14, 8 July 2010 by Inbal (Talk | contribs)
Jump to: navigation, search

The module is for sites using dynamic content which changes for each user independently. For example, shopping carts are often such pages. It will allow you to store the exact version that the user saw and allow our fetching bot to collect that version so it will be available to you in the playback of visitors visits and other reports. The PHP Integration Module is the next generation of the PHP Integration Code and adds further support to cases that were not previously covered, such as POST processing pages.

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

Contents


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

Integration with third-party applications

Please use the following integration methods if you are using one of these applications on your website.

Installation Guide

  1. The module itself can be found here.
  2. Remove the existing ClickTale code and/or disable other integration methods (for example, PHP integration code - which supports session state only.)
  3. Extract the archive to a directory named "ClickTale" in your website. Do not to create a directory named "ClickTalePHPIntegrationModule_X.X" in it. Simply place the files in ".../ClickTale/".
  4. Generate the ClickTale tracking code you want to use in your pages (or locate your already generated code).
  5. Copy and paste that code (from previous step) into the appropriate parts in ClickTale/ClickTaleScripts.xml file.
  6. Add 
    ClickTaleFetchFrom="%FetchFromUrl%";

    Just before the line 

    if(typeof ClickTale=='function') ClickTale([your ClickTale parameters])

    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: 

    <?xml version="1.0" encoding="utf-8" ?>
<scripts>
  <script name="Top" DoNotReplaceCondition = "&lt;!-- ClickTale Top part --&gt;">
    <![CDATA[
<!-- ClickTale Top part -->
<script type="text/javascript">
var WRInitTime=(new Date()).getTime();
</script>
<!-- ClickTale end of Top part -->]]>
  </script>
  <script name="Bottom" DoNotReplaceCondition="&lt;!-- No ClickTale --&gt;" InsertBefore="&lt;!-- ClickTale Bottom part Here --&gt;|&lt;/body&gt;">
    <![CDATA[<!-- ClickTale Bottom part -->
<div id="ClickTaleDiv" style="display: none;"></div>
<script type="text/javascript">
if(document.location.protocol!='https:')
  document.write(unescape("%3Cscript src='http://s.clicktale.net/WRb.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
ClickTaleFetchFrom="%FetchFromUrl%";
if(typeof ClickTale=='function') ClickTale([Your ClickTale parameters]);
</script>
<!-- ClickTale end of Bottom part -->]]>
  </script>
</scripts>

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

    IMPORTANT NOTE! This code sample relates to http tracking code only! for tracking code which can record both http and https pages you should first make sure your plan offers the ability to record 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;).
  7. Every page you wish to be recorded should contain the following PHP code: 
              <?php
          require_once("[physical_path_to_clicktale_dir_here]\ClickTale\ClickTaleTop.php");
          ?>

    at the top (before any content is sent, including the Doctype and opening html tag) and 

              <?php
          require_once("[physical_path_to_clicktale_dir_here]\ClickTale\ClickTaleBottom.php");
          ?>

    at the bottom (after all content has been sent, including the closing html tag). For example, with Joomla! you can try adding these lines to the top and bottom of the file index.php (in Joomla's root), this will add recording to all pages.

    Do not forget to replace [physical_path_to_clicktale_dir_here] with the relevant folder.
  8. Create two directories named "Cache" and "Logs" under the ClickTale directory. Make sure they have the proper writing permissions, for instance:
    • If you are using Apache with mod_php then the Cache and Log directories must be writable by Apache.
    • If the PHP is executed by some other means (CGI for instance), it's possible that it is executed as a different user than the webserver, so in that case it might be simpler to just make the permissions for those directories 777.
    • For windows machines, the directories should be writable by the webserver.

Optionally: see here to disable or enable yourself from being recorded. Apply this to everyone who is working with you on the site otherwise they will use recording quota, or enable this for testing to make sure all is working correctly.

Troubleshooting

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

Configuring the caching provider

The module caches the content of the pages so it can later provide the content to ClickTale servers for processing. This caching requires some persistent storage and so different caching providers are supported. The default caching provider is the file system ("cache" folder), it is slower than other methods. It is recommended to use the MySQLMemory provider. To do so you will need a valid connection to a MySQL database. There is also the APC module which requires installation. 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: 

$config['CacheProvider'] = "FileSystem";

to 

$config['CacheProvider'] = "MySQLMemory";

or 

$config['CacheProvider'] = "APC";

Note: The file-system provider will need write access rights to the "ClickTale/Cache" folder. On the other hand, APC and MySQLMemory will use memory for storage.

Caching provider settings

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 then that, stale caches are removed

MySQLMemory

  • $config['DeleteAfterPull'] = (true / false)
    • See FileSystem
  • $config['CacheLocation'] = (mysql uri)
    • url of the form http://<db username>:<db password>@<host of mysql>:<port of mysql>/<database to use>.<memory table name to use>
  • $config['MaxCachedSeconds'] = (integer)
    • Will only keep pages in cache for up to MaxCachedSeconds seconds. This will make sure that your cache storage will only take a small amount of memory.

APC

  • $config['DeleteAfterPull'] = (true / false)
    • See FileSystem
  • $config['MaxCachedSeconds'] = (integer)
    • See MySQLMemory

Use With "Expires" Header And Enable Reuse Of Cached Pages

Some websites use "cache-control" and "expires" headers to cache pages on the client. This improves performance but may be problematic when used with our module. Pages are removed from the module's cache right after they are being accessed (for security and performance reasons). So, if a visitor browses a page more than once without refreshing the content from the server (usually a result of using the back button), ClickTaleCache.php will be called several times with the same token. This will cause a cache miss for any request beyond the first one. To overcome this problem, it is possible to use the DeleteAfterPull="false" parameter in the configuration. This will disable the removal of cached pages when ClickTaleCache.php is called. Cached data will be removed after MaxCachedPages="???" new pages are cached, so you might want to extend this parameter as well to allow sufficient traffic between the first pageview and the next (duplicate pageview). Additionally, you can change your HTTP cache control to "no-cache" which will might be more correct for your application logic in the first place. Currently, this feature is not available when caching to databases.

Troubleshooting and debugging

The module's log files are located in: "ClickTale/Logs/Log_{0}.txt", where {0} is the log file's date. Setting: $config['AllowDebug'] = true; in config.php allows for more detailed log files.

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 access by third parties?
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 secret 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 <body> and the bottom before </body>, but this can be changed by adding a InsertAfter attribute to the script[name="Top"] element or 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 appear twice.
A: You should either remove the script from those pages and let the module handle the insertion or you should use DoNotReplaceCondition. See the code 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 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 get no code.
Q: I'm using a proxy server for my website - what steps should I take to record properly?
A: Move the IP restriction rule to the proxy and set the IP in config.php (located in the php integration module directory) to the IP of the proxy.

Using a proxy server

Move the IP restriction rule to the proxy and set the IP in config.php (located in the php integration module directory) to the IP of the proxy.

Reference

ASP.NET integration module - Good read as some configuration schema is shared.

Retrieved from "http://wiki.clicktale.com/Article/PHP_integration_module"
Personal tools