Installation guide

Before launching tests on your website, you must install Kameleoon script. This article will guide you through this installation.

Standard installation

The installation is quick and easy but you will need to change the source code of your HTML pages in order to insert a JavaScript tag, which includes your site code. This script will never change, whichever tests you are running on your website.

Access the script 

To find the JavaScript with your site code, login to your personal space.

Use the menu on the left to go on the “Configured sites” page.

Click on the “Installation” button below the URL of your website.

You will find the script to insert in your website on this installation page. Note that this script contain your unique “Site code” and will only work with the corresponding URL.

On the top right of this page, Kameleoon will indicate if the script is installed or not on your website.

Installing the script

Copy this script and paste it in your pages code source. To do so, use a code source editor (such as Notepad or Brackets) and open the file generating the code source of your pages. Add this code on all of your websites pages.

We recommend to add Kameleoon script right after the <head> element of your pages.

Tip: it is not mandatory to install the script on all of your pages, but it is highly advised. Installing Kameleoon on just a part of your website will make you miss some functionalities covering the entire website (in the targeting options of an A/B test, for example).

Congratulation! You just installed Kameleoon!

Site code

Your site code is unique and is used to identify your website. It is already included in the script so you should not have to worry about it.

However, if you choose to do an advanced installation of Kameleoon, you ill need this code to insert it in the script you will use for the installation. 

To do so, it is very simple, you will find your code in the script given in the "Installation" part of your Back-office. It is the highlighted part in the example below:

Advanced installation

Although installing Kameleoon via a  <script> tag is very easy, many particular situations can occur.

Keep in mind that the main problem when using an advanced integration is that it can negatively affect the loading of the script and introduce a flicker effect

Here are the different ways of installing Kameleoon along with their respective advantages and disadvantages:

  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

 

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

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 access to your configuration options, use the left menu to go to the “Configured sites” page.

Click on the “Advanced configuration” button below the URL of your website.

Then, choose "Advanced options" on the list.

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;
var kameleoonStartLoadTime = new Date().getTime(); 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>

Optimum location for the script

Kameleoon script

Kameleoon must be loaded and executed as soon as possible in order to avoid the flicker effect

Knowing that the browsers load and execute scripts (and other resources, such as CSS style sheets) in their order on the HTML page, we recommend to place the script as high as possible on the HTML code.

Ideally, we recommend to place it just after the opening <head> element, before every other JavaScript scripts.

Note: this recommendation contradicts the usual rules for external JavaScript integration. Usually, it is recommended to insert the external scripts at the end of the page. In the case of A/B testing and Kameleoon however, it is better to do otherwise. Similarly, it is not recommended to load the script in asynchronous mode, even if it is possible, once again to avoid the flicker effect

With Google Analytics script

Both Kameleoon and Google Analytics scripts should be lplaced in the <head> element of your webpages. But which one should be first?

Ideally, Kameleoon script should be located before Google Analytics, especially in case of A/B tests with a target in the title of the page.

Both scripts should be placed after the <title> element, usually located on the top of the <head> element.

To sums up, the ideal order is this one:

<!DOCTYPE html>
<html>
	<head>
<title>My title</title> <!-- Insert your Kameleoon tag here --> <script>Kameleoon</script> <!-- Insert your Google Analytics tag here --> <script>Google Analytics</script> </head> <body> <!-- Insert your remaining HTML code here --> <h1>My first heading</h1> <p>My first paragraph.</p> </body> </html>

Special cases

Wide domain support

Kameleoon offers automatic and elegant support for wide domain A/B tests, that is, tests 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 kameleoonURL = "https://SITE_CODE.kameleoon.eu";
var kameleoonStartLoadTime = new Date().getTime();
var kameleoonLoadingTimeout = 1000;
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 tests 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.

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. Moreover, the tag manager needs to be loaded first to load Kameleoon, which can add a latency period.

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 A/B tests). If your TMS caches Kameleoon, you won't be able to run any tests.

However, if you have to use a tag manager to install Kameleoon, we recommend to use the version below for the script. It is the asynchronous non-blocking version.

<script type="text/javascript">
var scriptNode = document.createElement("script"); scriptNode.src = "//static.kameleoon.com/css/customers/SITE_CODE/0/kameleoon.js"; scriptNode.type = "text/javascript"; scriptNode.async = true; document.head.appendChild(scriptNode);
</script>

Simply replace SITE_CODE parameter by your own site code.

Wide Domain Support for Tag manager systems

<script type="text/javascript">
var kameleoonLoadingTimeout = 1000;
var kameleoonStartLoadTime = new Date().getTime();
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);}
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>

Asynchronous loading for old versions of IE

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;
var kameleoonStartLoadTime = new Date().getTime(); 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 Kameleoon 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

Use of 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 access to your configuration options, use the left menu to go to the “Configured sites” page.

Click on the “Advanced configuration” button below the URL of your website.

Then, choose "Advanced options" on the list.

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