Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt

Use this file to discover all available pages before exploring further.

To implement Kameleoon on your website, add a JavaScript installation tag to the HTML source code of your pages.

​
Implement Kameleoon in the HTML source code

For web experimentation, always add the Kameleoon tag in the <head> section of your HTML source code. Placing the tag in the <body> section, especially at the end of the page, increases the risk of flickering. Add the tag as high as possible in the <head> section, ideally immediately after the opening <head> tag. This position allows the browser to load the Kameleoon application file before other resources. CSS or other scripts placed before the Kameleoon tag increase the risk of flickering.
If you use hybrid mode (both an SDK and the JavaScript installation tag), you can place the tag later in the body, such as right before the closing </body> tag. Flicker does not occur when using a web SDK.
Kameleoon recommends the Asynchronous tag with anti-flicker method for web experimentation. While this method loads Kameleoon slower than other methods, it provides the safest implementation. An asynchronous script ensures that Kameleoon does not block your website’s load. The white overlay “simulates” a synchronously loaded script to prevent flickering. To prioritize faster loading times, use the synchronous tag instead.
If your website uses multiple subdomains, include the additional unified session data across subdomains code in the implementation script. Kameleoon requires this code to use session data across all subdomains for advanced behavioral targeting.
Adding any script or resource to your website increases the load. Kameleoon prioritizes performance and optimizes its code to achieve the best possible results.

​
Asynchronous tag with anti-flicker

This method loads the Kameleoon script asynchronously and includes anti-flickering code. Kameleoon uses a “blocking CSS rule” to hide page content and removes it as soon as the application code loads (usually under 50ms) or when the specified timeout (default 750ms) expires. This safeguard ensures that Kameleoon never causes your website to crash or stay blank indefinitely. Adjust the timeout using the kameleoonLoadingTimeout JavaScript variable in the installation snippet.
If a timeout occurs and the Kameleoon code eventually loads, you can configure the next steps in the advanced confirmation settings of your project. You have two options:
  • Disable Kameleoon entirely for that visitor.
  • Run Kameleoon’s code normally (which may cause flickering).
<script>
  // Duration in milliseconds to wait while the Kameleoon application file is loaded
  var kameleoonLoadingTimeout = 750;

  window.kameleoonQueue = window.kameleoonQueue || [];
  window.kameleoonStartLoadTime = Date.now();
  if (! document.getElementById("kameleoonLoadingStyleSheet") && ! window.kameleoonDisplayPageTimeOut) {
    var kameleoonS = document.getElementsByTagName("script")[0];
    var kameleoonCc = "html::after { content: ''; position: fixed; inset: 0; background: #fff; z-index: 2147483647; }";
    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(fromEngine) {
      if (!fromEngine) {
        window.kameleoonTimeout = true;
      }
      if (kameleoonStn.parentNode) {
        kameleoonStn.parentNode.removeChild(kameleoonStn);
      }
    };
    window.kameleoonDisplayPageTimeOut = window.setTimeout(window.kameleoonDisplayPage, kameleoonLoadingTimeout);
  }

</script>

<script type="text/javascript" src="//SITE_CODE.kameleoon.io/engine.js" fetchpriority="high" async></script>
Replace the SITE_CODE placeholder with your project site code.
Kameleoon script domains vary by project. Projects use either kameleoon.eu or kameleoon.io based on their creation date. Use the domain displayed in the Kameleoon App for your project.
The timeout counter starts when the browser executes the code, not when it begins downloading engine.js. Setting a timeout too low (e.g., 100ms) may not allow enough time for the browser to download and execute the file, especially on slow connections or when other scripts are queued.
Place the Kameleoon installation tag within the <head> tag or at the beginning of the <body> tag. Placing it later in the <body> may cause the page to load, disappear, and reappear because the anti-flickering code requires execution inside the <head> to function correctly.

​
Synchronous tag

This method loads the Kameleoon script synchronously to prevent flickering. However, this approach blocks page loading until the browser downloads and executes the Kameleoon code, which may impact performance. 
<script>window.kameleoonQueue = window.kameleoonQueue || [];</script>
<script type="text/javascript" src="//SITE_CODE.kameleoon.io/engine.js" fetchpriority="high"></script>
Replace the SITE_CODE placeholder with your project site code.
Kameleoon script domains vary by project. Projects use either kameleoon.eu or kameleoon.io based on their creation date. Use the domain displayed in the Kameleoon App for your project.

​
Asynchronous tag without anti-flicker

This tag installs the Kameleoon application file asynchronously without anti-flicker prevention. Use this tag if flicker is not a concern, such as when using hybrid mode. 
<script>
  window.kameleoonQueue = window.kameleoonQueue || [];
</script>
<script type="text/javascript" src="//SITE_CODE.kameleoon.io/engine.js" fetchpriority="high" async></script>
Replace the SITE_CODE placeholder with your project site code.
Kameleoon script domains vary by project. Projects use either kameleoon.eu or kameleoon.io based on their creation date. Use the domain displayed in the Kameleoon App for your project.

​
Implement Kameleoon in a Tag Manager

Kameleoon supports all major Tag Management Systems (TMS). To avoid flickering, install Kameleoon directly in your page’s source code. Using a TMS delays loading, which often results in noticeable flicker, especially if the TMS loads at the bottom of the HTML page. Kameleoon does not provide technical support for flickering issues caused by TMS implementations. TMS environments do not allow synchronous loading of external JavaScript. For TMS implementations, use the asynchronous JavaScript tag. 
window.kameleoonStartLoadTime = new Date().getTime();
var scriptNode = document.createElement("script");
scriptNode.src = "//SITE_CODE.kameleoon.io/engine.js"; //replace the SITE_CODE variable by your Kameleoon project Sitecode.
scriptNode.type = "text/javascript";
scriptNode.async = true;
scriptNode.setAttribute("data-tagmanager", true);
document.head.appendChild(scriptNode);
Kameleoon script domains vary by project. Projects use either kameleoon.eu or kameleoon.io based on their creation date. Use the domain displayed in the Kameleoon App for your project.
Some TMS offer server-side support, which allows you to install Kameleoon without causing issues. This setup is equivalent to embedding the installation code directly in your HTML.

​
Choose the correct trigger

When implementing Kameleoon via a TMS, use a specific trigger to ensure the script executes as early as possible. Choose the trigger that fires earliest on every page for your specific TMS.
Do not configure your TMS to cache or combine the Kameleoon script. The application file contains dynamic configuration data required to execute experiments and personalizations. Caching this file prevents experiments from starting or running correctly.Avoid using anti-flicker prevention technology within a TMS, as it is not designed to operate correctly in that environment.