Advanced Installation Guide

Although installing Kameleoon via a <script> tag is very easy, many particular situations can occur. This guide details the various ways Kameleoon can be integrated to your own website, given your specific technical setup.

Keep in mind that the main problem when using an advanced integration is that it can negatively affect the load of the Kameleoon script and introduces a noticeable flicker effect. Flickering means that the variation will load on the page shortly after the original page displays.

Different ways of installing Kameleoon along with their respective advantages and disadvantages are summarized below:

  Synchronous loading Standard asynchronous loading Asynchronous loading with anti-flicker
Speed Yes Yes Yes
Sensibility to incidents Strong Weak Weak
Absence of flicker effect Yes No Yes

Recommended location for script

While several code snippets are presented in this guide, you should always install the snippet at the very top of the <head> HTML section. It is very important to do so, before any other resources are written into the HTML code (such as CSS files or other JavaScript files). Although Kameleoon will work if the script is not placed at the very top, resources that are present before Kameleoon increases the chances that a flicker effect or timeout will happen.

Here is an example of a webpage correctly tagged with Kameleoon:

<!DOCTYPE html>
<html>
	<head>
		<title>My title</title>
		<!-- Insert your Kameleoon tag here -->
		<script type="text/javascript" src="//static.kameleoon.com/css/customers/SITE_CODE/0/kameleoon.js"></script>
	</head>
	<body>
		<!-- Insert your remaining HTML code here -->
		<h1>My first heading</h1>
		<p>My first paragraph.</p>
	</body>
</html>

The only exception to this rule is, of course, the use of a Tag Management System, since you won't directly need to edit your HTML code.

Synchronous loading

Note : This is the integration method recommended by the Kameleoon team.

To install Kameleoon synchronously, use the following code without forgetting to replace the SITE_CODE variable below by your own:

<script type="text/javascript" src="//static.kameleoon.com/css/customers/SITE_CODE/0/kameleoon.js"></script>

Asynchronous loading

For modern websites loading an important number of JavaScript files, best practice suggests that every script be loaded asynchronously.

This ensures that page loading is not blocked while scripts are downloaded by the browser. In addition, ideally, scripts that are important should be loaded at the top of the page, and scripts that are less important or that can afford to wait should be loaded at the bottom.

A script is loaded asynchronously when the browser doesn't wait for the script to load to display the requested page to the user. Consequently, an asynchronous script loads in parallel with the loading of the page, and doesn't prevent it from being displayed.

We offer two different ways to load Kameleoon asynchronously.

Standard asynchronous loading

To install Kameleoon asynchronously, without any attempt to mitigate the flicker effect that can happen, use the following code without forgetting to replace the SITE_CODE variable below by your own:

<script src="//static.kameleoon.com/css/customers/SITE_CODE/0/kameleoon.js" async="true"></script>

Asynchronous loading with anti-flicker

This integration simulates a blocking effect, preventing the loading of the page until the Kameleoon JavaScript is received by the browser. This is done in order to mitigate flickering effects, while ensuring that if the script takes a long time to download, the page will be displayed.

The timeout after which the page is displayed even if Kameleoon is not yet ready, is customizable and controlled by the variable kameleoonLoadingTimeout in the script below. Its default value is set at 1000ms.

If a timeout indeed occurs, the original, unmodified version of the page is instantly displayed, and Kameleoon continues to try loading in the background. You can choose what happens if/when Kameleoon finally loads.

To do so, log in to your Kameleoon account and use the left menu to access the “Configured sites” page.

You will see the list of websites you have configured with Kameleoon. Click on "Advanced configuration" below your domain name.

 

Then, scroll down to “Behavior in case of timeout” and choose from one of the 3 following options:

  • Run Kameleoon (with flicker): By default, A/B tests or web personalizations will be launched, even in case of timeout. As a result, a noticeable flicker effect can occur.
  • Disable Kameleoon for this page: This option will disable Kameleoon for the current page, from which a timeout has occured.
  • Disable Kameleoon for the entire visit: This option will disable Kameleoon for the entire duration of the visit.

Note that since the Kameleoon JavaScript file is cached by the browser, timeouts will mainly occur on the first page load on your website. On the second page load, Kameleoon will be ready very quickly because it won't have to be downloaded again.

To install Kameleoon asynchronously with anti-flicker, use the following code without forgetting to replace the SITE_CODE variable below by your own:

<script type="text/javascript">
	var kameleoonLoadingTimeout = 1000;
	if (! document.getElementById("kameleoonLoadingStyleSheet") && ! window.kameleoonDisplayPageTimeOut){
	var kameleoonS = document.getElementsByTagName("script")[0];var kameleoonCc = "* { visibility: hidden !important; background-image: none !important; }";
	var kameleoonStn = document.createElement("style");kameleoonStn.type = "text/css";kameleoonStn.id = "kameleoonLoadingStyleSheet";
	if (kameleoonStn.styleSheet){kameleoonStn.styleSheet.cssText = kameleoonCc;}else{kameleoonStn.appendChild(document.createTextNode(kameleoonCc));}kameleoonS.parentNode.insertBefore(kameleoonStn, kameleoonS);
	window.kameleoonDisplayPage = function(){if (kameleoonStn.parentNode){kameleoonStn.parentNode.removeChild(kameleoonStn);}};
	window.kameleoonDisplayPageTimeOut = window.setTimeout(window.kameleoonDisplayPage, kameleoonLoadingTimeout);}
</script>
<script src="//static.kameleoon.com/css/customers/SITE_CODE/0/kameleoon.js" async="true"></script>

Particular cases

Integration with a Tag Management System

Kameleoon is compatible with all major Tag Management Systems (TMS). However, if possible, we recommend to install Kameleoon directly in the source code of your website, and not via a TMS. The reason for this is again related to the flicker effect. Using a TMS delays the load of Kameleoon and increases flickering. This is especially problematic if your TMS is loaded at the bottom of your HTML page.

If you use a Tag Management System (such as Google Tag Manager, Tag Commander, etc), you should not use the asynchronous with anti-flicker script as it is not designed to work within a TMS. You can either use the standard asynchronous script or the synchronous one. However, inside a TMS, loading synchronously is not possible, so the synchronous code will act as the asynchronous one.

Be also careful not to instruct your TMS to cache and combine the Kameleoon script, as the script contains a dynamic part (the data needed to represent the currently running web personalization). If your TMS caches Kameleoon, you won't be able to run any web personalizations.

Wide Domain Support

Kameleoon offers automatic and elegant support for wide domain web personalizations, that is, web personalizaions that span several distinct domains (such as www.mydomain.com and www.mydomain.org). If you require wide domain support, which is a more complex setup (it uses an iframe rather than a script), use the following snippet without forgetting to replace the SITE_CODE variable below with your own:

<script type="text/javascript">
var kameleoonLoadingTimeout = 1000; var kameleoonURL = "https://SITE_CODE.kameleoon.eu"; var kameleoonProcessMessageEvent = function(event){if (kameleoonURL == event.origin){window.removeEventListener("message", kameleoonProcessMessageEvent);window.kameleoonExternalIFrameLoaded = true;eval(event.data);Kameleoon.Analyst.load();}};
if (window.addEventListener){window.addEventListener("message", kameleoonProcessMessageEvent, false);}
if (! document.getElementById("kameleoonLoadingStyleSheet") && ! window.kameleoonDisplayPageTimeOut){
var kameleoonS = document.getElementsByTagName("script")[0];var kameleoonCc = "* { visibility: hidden !important; background-image: none !important; }";
var kameleoonStn = document.createElement("style");kameleoonStn.type = "text/css";kameleoonStn.id = "kameleoonLoadingStyleSheet";
if (kameleoonStn.styleSheet){kameleoonStn.styleSheet.cssText = kameleoonCc;}else{kameleoonStn.appendChild(document.createTextNode(kameleoonCc));}kameleoonS.parentNode.insertBefore(kameleoonStn, kameleoonS);
window.kameleoonDisplayPage = function(){if (kameleoonStn.parentNode){kameleoonStn.parentNode.removeChild(kameleoonStn);}};
window.setTimeout(function(){}, 25);
window.kameleoonDisplayPageTimeOut = window.setTimeout(window.kameleoonDisplayPage, kameleoonLoadingTimeout);}
var iframeNode = document.createElement("iframe");
iframeNode.src = kameleoonURL;
iframeNode.id = "kameleoonExternalIframe";
iframeNode.style = "float: left !important; opacity: 0.0 !important; width: 0px !important; height: 0px !important;";
document.head.appendChild(iframeNode);
</script>
Note : You do not need wide domain support if you only run web personalizations on different subdomains (for instance www.mydomain.com and checkout.mydomain.com).
Note : With wide domain support, the loading is always asynchronous, there is no way to load Kameleoon synchronously.

Asynchronous loading for old versions of Internet Explorer

Old Internet Explorer versions (versions 9 and anterior) do not support the async attribute of the <script> tag. If you absolutely require asynchronous loading even on these browsers, you can use an integration code that creates the <script> node dynamically. It will then load in a non-blocking way even on older IEs, but has an important drawback. Since the <script> is not treated by the HTML parser, all other resources that are hardcoded in the HTML code, even later, take precedence and are placed higher in the browser download queue. This means Kameleoon loading is significantly delayed, thus increasing the risk of flicker or timeout.

<script type="text/javascript">
var kameleoonSiteCode = "SITE_CODE";
var kameleoonLoadingTimeout = 1000;
if (! document.getElementById("kameleoonLoadingStyleSheet") && ! window.kameleoonDisplayPageTimeOut){
	var kameleoonS = document.getElementsByTagName("script")[0];var kameleoonCc = "* { visibility: hidden !important; background-image: none !important; }";
	var kameleoonStn = document.createElement("style");kameleoonStn.type = "text/css";kameleoonStn.id = "kameleoonLoadingStyleSheet";
	if (kameleoonStn.styleSheet){kameleoonStn.styleSheet.cssText = kameleoonCc;}else{kameleoonStn.appendChild(document.createTextNode(kameleoonCc));}kameleoonS.parentNode.insertBefore(kameleoonStn, kameleoonS);
	var kameleoonScn = document.createElement("script");kameleoonScn.type = "text/javascript";kameleoonScn.async = true;
	kameleoonScn.src = "//static.kameleoon.com/css/customers/"+kameleoonSiteCode+"/0/kameleoon.js";kameleoonS.parentNode.insertBefore(kameleoonScn, kameleoonS);
	window.kameleoonDisplayPage = function(){if (kameleoonStn.parentNode){kameleoonStn.parentNode.removeChild(kameleoonStn);}};
	window.kameleoonDisplayPageTimeOut = window.setTimeout(window.kameleoonDisplayPage, kameleoonLoadingTimeout);}
</script>

Use of the Kameleoon high performance CDN

For high-traffic or performance-sensitive websites, Kameleoon offers a more high-end CDN than the default one. If you have a contract with Kameleoon that includes the use of this high-performance CDN, replace in your chosen code snippet all the occurences of:

static.kameleoon.com

With :

static-bp.kameleoon.com

Using your own CDN

The Kameleoon script can also be hosted using your own CDN. In this case, you need to create in your CDN interface a subdomain (such as http://kameleoon.mydomain.com) that points to the following domain:

static-direct.kameleoon.com

Then, you will need to replace in your chosen code snippet all the occurences of:

static.kameleoon.com

With your newly created subdomain, for instance:

kameleoon.mydomain.com

Also, don't forget to specify in your Kameleoon back-office the domain you created. Otherwise, you won't be able to upload and use images in your variations.

To do so, log in to your Kameleoon account and use the left menu to access the “Configured sites” page.

You will see the list of websites you have configured with Kameleoon. Click on “Advanced configuration” for the website of your choice.

Scroll down to the "Custom URL CDN" section and add the URL of your newly created CDN subdomain.

Have more questions? Submit a request
Powered by Zendesk