Simple implementation
Follow this guide to implement Kameleoon on your website. The implementation process requires adding 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 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.
The recommended method for web experimentation is the Asynchronous tag with anti-flicker. While this method does not load Kameleoon the fastest, it is the safest. Using 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 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).
kameleoon.js is deprecated and replaced by engine.js. Kameleoon will stop supporting kameleoon.js after June 1st, 2026. Update your implementation snippet to ensure your campaigns continue to function.
<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 is designed to function inside the <head>.
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.
kameleoon.js is deprecated and replaced by engine.js. Kameleoon will stop supporting kameleoon.js after June 1st, 2026. Update your implementation snippet to ensure your campaigns continue to function.
<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.
kameleoon.js is deprecated and replaced by engine.js. Kameleoon will stop supporting kameleoon.js after June 1st, 2026. Update your implementation snippet to ensure your campaigns continue to function.
<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.
kameleoon.js is deprecated and replaced by engine.js. Kameleoon will stop supporting kameleoon.js after June 1st, 2026. Update your implementation snippet to ensure your campaigns continue to function.
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 is equivalent to embedding the installation code directly in your HTML.
Choose the correct trigger
When implementing Kameleoon via a TMS, you must 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.