Integration module

The full list of integration modules can be found on our Plugins and Integrations page.

Introduction

An "Integration module" is a type of a ClickTale integration with a website that is platform specific and based on adding a code library to a website. Such a module resolves several issues related to using ClickTale on a dynamic site and generally simplifies ClickTale integration and procedures.

With an integration module you'll be able to use ClickTale for recording pages that were previously problematic, including password protected pages, pages that depend on session objects, pages with random elements and POST processing pages. A typical module provides:

• Automatic injection of ClickTale script to all outgoing pages.
• Automatic capturing of page content and temporary caching.

The benefits of using a module are:

• Having a single location for your ClickTale script makes it easier for you to take advantage of the benefits that ClickTale provides.
• ClickTale will be able to record all sorts of problematic pages such as: password protected pages, pages that depend on session objects, pages with random elements and POST processing pages.

Platforms

ClickTale currently offers the following modules:

• PHP integration module
• ASP.NET integration module
• J2EE integration module
• Ruby on Rails integration module

Basic operation flow

• The module installs itself in the web site platform as a filter and captures all pageview content as it flows out of the server.
• Content of pageviews that needs to be recorded is stored in a "cache storage provider" that is configurable and depends on the module used.
• The ClickTale tracking code is injected into the page and the page is sent to the visitor.
• The tracking code performs tracking of visitor activities on the client-side.
• The ClickTale crawler ("fetcher") makes a HTTP request to the module to receive the stored ("cached") page content.
• The stored content is deleted after access or after a certain time depending on configuration.

Usage with Load balancers

Most integration modules default to using a local (often in process memory) storage for storing the temporary cache of pageviews content. That content is later requested by ClickTale servers via HTTP(S). When using more than one server and using a load balancer to distribute the requests across the servers there is a chance that a visitor will be forwarded to a different server than the one to which the ClickTale crawler will be forwarded to. As a result the crawler will hit a server that doesn't contain the requested information and the recording (not the response to the visitor) will fail with a 404 error. A proper load balancing configuration should implement one of the following

• A way to force the request from ClickTale to reach a specific server in the farm
• A cache store that is centralized

Forcing a specific server

Using direct host for fetching

If you have a dedicated host for each server in the farm, and you can access resources of the web site by going to a direct url, then you can set ClickTale to fetch from a specific server. To do that you would customize the ClickTaleFetchFrom url of each server to specify a direct url to that server. For example if having a site http://www.site.com/ and servers http://s1.site.com/, http://s2.site.com/ then you would change the bottom tracking code on each server to have ClickTaleFetchFrom url refer to the specific server directly.

Using cookies for accessing a specific server

Some load balancers use a HTTP cookie to assign a specific visitor to a specific server permanently. This is often called "Sticky sessions". If you know that such cookie exists in your case, you should be able to cause the crawler to reach the original server if you record the cookie value. To do so see FetchFromWithCookies (note section 'Specifying a URL' for merging integration module url with FetchFromWithCookies code).

Centralized cache store

Most integration modules provide an option to use a cache store provider that is centralized. When using one centralized provider, all cached entries are available to all servers and proper crawling is achieved even if ClickTale server reaches a different server than the one reached by the visitor. Examples of centralized storage providers

• SQLServer for the ASP.NET integration module
• MySQL for the PHP integration module
• ehcache for the J2EE integration module

Usage with a (reverse) proxy server

If you are using a (reverse) proxy server, that server could change the request in such a way that they seem to appear to originate from the proxy and not from ClickTale servers. This will prevent the module from authenticating the request based on IP address. There are two ways to work around this.

• Change the allowed addresses value in the configuration of the module module and set it to the IP of the proxy. Then you need to configure your proxy to block access to the handlers of the proxy from IPs that are not ClickTale's IPs. See specific module documentation for instructions.
• or
• For some of the modules, if your proxy provides the original IP address in the HTTP headers, then you can instruct the module to use that header for identification. See specific module documentation for instructions on configuring "X-Forwarded-For" (or another header) as the IP source.

Troubleshooting

Tracking code not injected in to the HTML of the page

First please check that the module is installed correctly by using the debugging/troubleshooting functionality of the module. If the debug page appears functional, please check if you are browsing with a WRUID cookie set to value '0'. Having WRUID=0 means that you are classified as "not to record". The ClickTale tracking code will classify visitors as "to record" and "not to record" based on the recording ratio that you select at tracking code generation. Most integration modules are configured in such a way that they will not inject the tracking code to the page if the visitor is classified as "not to record" (for performance). Therefore if your tracking code is configured with ratio that is not 100%, you may be classified as "not to record" and as a result not getting the tracking code by design. Please use a cookie editor to change the WRUID cookie from '0' to '1' for testing.

Receiving 404 errors and other "not found" messages in recordings

Some websites use "cache-control" and "expires" headers to cache pages on the client. This improves performance but may be problematic when used with an integration module.

By default, pages are removed from the module's cache right after they have been accessed by the ClickTale crawler (for security and performance reasons). As a result the content will be deleted after the first pageview of that content is recorded. Recording subsequent pageviews will result in a cache miss (for ClickTale, not the visitor). This is often the case when a visitor browses a page more than once without refreshing the content from the server (usually a result of using the back button).

To overcome this problem, see the specific module configuration to set DeleteAfterPull="false" parameter. This will disable the removal of cached pages when the module is called. Cached data will be removed after MaxCachedPages or MaxCachedSeconds (depending on module and storage provider). You would want to tweak MaxCachedPages or MaxCachedSeconds to allow sufficient time between the first pageview and the next (duplicate pageview).

Additionally, you can change your HTTP cache control to "no-cache" which might be more correct for your application logic in the first place.

Preventing crawling of module cache

The cache URLs aren’t exposed to search engines. If you are still concerned about any theoretical impact to SEO you can block cache urls from being accesses by bots via a robots.txt file (or if you already have one, by modifying it).

Please see this Google article for an explanation about robots.txt and this guide for examples of its use.
The part preventing the crawling of the cache should look something like:
User-agent: *
Disallow: [CLICKTALECACHELOCATION]

Where CLICKTALECACHELOCATION is the location of the module cache (you can see it when viewing the source of the page suing the module, as the "ClickTaleFetchFrom" setting (not including query string parameters, which differ from pageview to pageview).