Skip to main content
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 doesn’t 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 doesn’t 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 minimize that impact.

​
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 once the Kameleoon application file loads (usually under 50 ms) or when the specified timeout (default 750 ms) 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 Behavior if timeout occurs setting on the Settings tab of your project. You have the following options:
  • Turn off Kameleoon for that visitor on the current page or for the entire visit.
  • Run Kameleoon’s code normally (which may cause flickering).
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 (for example, 100 ms) may not allow enough time for the browser to download and execute the file, especially on slow connections or when the browser queues other scripts first.
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.
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 isn’t a concern, such as when using hybrid mode.
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 doesn’t provide technical support for flickering issues caused by TMS implementations. TMS environments don’t allow synchronous loading of external JavaScript. For TMS implementations, use the asynchronous JavaScript tag.
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.
Don’t 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’s not designed to operate correctly in that environment.

​
FAQ

If your website restricts the loading of resources (scripts, images, media, CSS) via the standard Content-Security-Policy (CSP) HTTP header, update your site’s CSP to allow Kameleoon resources to load. The same policy covers the Kameleoon application file and client-side SDKs.

​
Easy setup (with wildcards)

script-src always trumps default-src. Do not use this setup if you already use the complete setup in your CSP.
Add the following content to your CSP header configuration:

​
Complete setup (fully detailed)

Kameleoon regularly adds new features to the product, which could result in additional URLs. List all possible hosts and resource types (script, image, etc.) explicitly in the CSP header.
Replace [your-site-code] with your Kameleoon site code in each line where it appears and add this to your configuration:
Each URL in the CSP policy serves a specific purpose:
Web Experimentation
  • https://[your-site-code].kameleoon.xx: Loads the Kameleoon Web Experimentation Application Script, engine.js (previously named kameleoon.js).
  • https://(eu|na)-data.kameleoon.(eu|io): Used for tracking.
  • https://logger.kameleoon.io: Sends tracking data for logging.
  • https://data.kameleoon.net: Required if you use the Kameleoon Simulation tool to QA experiments across multiple subdomains.
Feature Experimentation (client-side SDKs)
  • https://client-config.kameleoon.com: Required for SDK versions < 2.1.0.
  • https://sdk-config.kameleoon.eu: Required for SDK versions >= 2.1.0.
  • https://events.kameleoon.com:8110: Required for real-time streaming, a premium option.
  • https://api.kameleoon.com: Authenticates SDK requests (/oauth/token).
  • https://(eu|na)-data.kameleoon.(eu|io): Used for tracking.
  • https://logger.kameleoon.io: Sends tracking data for logging.
Graphic editors
  • https://static.kameleoon.com: (deprecated) Loads static resources for the old graphic editor.
  • https://editor.kameleoon.com: (deprecated) Used by the old graphic editor.
  • https://graphical-editor.kameleoon.com: Used by the new graphic editor.
  • https://storage.kameleoon.(eu|io): Loads images used in experiments created with the graphic editors.
Prompt-based experimentation (PBX)
  • https://aibuilder.kameleoon.com: Used by the prompt-based editor.
  • https://electra.kameleoon.com: Used by the prompt-based editor.
  • https://storage.kameleoon.(eu|io): Loads images in the prompt-based editor.
  • https://api.kameleoon.com: Loads account-related information.
  • https://sdk-config.kameleoon.eu: Controls Kameleoon feature flags activated in the prompt-based editor.
  • wss://electra.kameleoon.com : Used for data exchange.
Simulation
  • https://api.kameleoon.com: Used by the old simulation.
  • https://simulation.kameleoon.com: Used by the new simulation.
Product recommendation
  • https://static.products.kameleoon.com: Loads resources for the Product Recommendation module.
  • https://api.products.kameleoon.com: API used by the Product Recommendation module.
  • https://images.products.kameleoon.com: Loads product images for recommendations.
APIs and integrations
  • https://api.kameleoon.com: Required if you intend to use the Automation API for testing directly from the browser.
  • https://customers.kameleoon.com: Required if you use the SDK API or a custom integration developed by Kameleoon.
Internal resources
By default, engine.js does not include simulation paths or application-specific information to minimize script size. To provide these details, load the full script kameleoonFull.js, which supplies engine.js with necessary data on internal resources and loading instructions.
  • https://static.kameleoon.com: Loads internal resources.
  • https://static.experimentation.dev: Loads internal resources.
  • https://sdk-config.experimentation.dev: Controls Kameleoon feature flags activated in the Kameleoon product.
  • https://eu-data.experimentation.dev: Sends tracking data for logging purposes.
The domain for your Kameleoon scripts https://[your-site-code].kameleoon.xx may vary from one project to another. Projects use either kameleoon.eu or kameleoon.io depending on their creation date. Use the domain displayed in the Kameleoon App for your project. The same applies if you use Kameleoon in hybrid mode.
The Kameleoon JavaScript engine requires the eval() function to add custom code to Kameleoon, such as custom data and custom JavaScript, when implementing variations of a page. The eval() function allows Kameleoon to dynamically execute this custom code at runtime.If you use a Content Security Policy (CSP) directive that prevents the use of the eval() function, implement the following JavaScript snippet before the Kameleoon installation tag:
If your CSP blocks eval(), implementing the code snippet will not remove these restrictions. To ensure full functionality, adjust the relevant CSP directive to allow eval() or similar functions. Otherwise, certain advanced targeting or customization features in Kameleoon remain inaccessible due to browser security enforcement.
The Kameleoon Graphic Editor (including the simulation panel) also requires the eval() function. However, you can work around this requirement by installing the Kameleoon Chrome Extension and enabling the Dev Tools > Tag injection > Bypass policies setting to override the policies locally. You must also provide your sitecode. Enabling the Bypass policies setting allows you to use the Graphic editor in a Chrome browser.
Bypass policies setting in the Chrome extension
Some features of Kameleoon are not available if a CSP directive blocks the eval() function. These limitations apply even if you use any code snippet or workaround mentioned in this answer. The following features will remain unavailable unless your CSP explicitly allows eval():
  • Targeting a segment with a custom JavaScript condition (only supported when the condition runs asynchronously).
Targeting condition async setting
  • Using custom data with custom JavaScript code.
  • Using acquisition channels with custom JavaScript code.
The iframe Kameleoon uses to unify session data across subdomains does not use the eval() function. You can implement session data unification regardless of your CSP eval() policy.
Unfortunately, no. While SRI provides a useful security feature, the Kameleoon app file changes over time. If it didn’t, features like starting and stopping experiments instantly without a redeployment would be impossible. Since the file contents change, the resource hash also changes, so you can’t use SRI. Otherwise, the browser would block the resource once it updates on the servers.
Kameleoon scripts are already short, and using a minified version doesn’t meaningfully affect page load time because the code is already compressed using Brotli or Gzip. Kameleoon doesn’t recommend minified versions, but if required, they’re available below.

​
Asynchronous loading with anti-flicker

​
Unify session data across subdomains

If you use the unified session data tag to unify session data across subdomains with either the synchronous tag or the asynchronous tag without anti-flicker:
If you use the unified session data tag and the asynchronous tag with anti-flicker, add the three script tags in the following order:
  1. Asynchronous tag with anti-flicker.
  2. Unified session data tag.
  3. Kameleoon installation tag.
Don’t modify installation tags. Their code is extensively tested and optimized. Modifying them can result in a non-working setup. If an installation tag requires modification, contact your Customer Success Manager to coordinate with developers. Don’t attempt independent modifications.
Don’t include any installation tag in its own separate, external script. For example, never do this:
While this may technically work, it significantly affects Kameleoon performance and introduces a noticeable flicker effect. This setup creates the problems of using a tag manager without any associated benefits.