Web Experimentation installation guide

This page includes step-by-step instructions for installing Kameleoon, including creating a Web Experimentation project for your website and configuring your project settings. (Feature Experimentation projects support both Web / Backend and Mobile app platforms.)

​

Overview

Before launching experiments on your website or mobile app, you must install the Kameleoon script. You must add this script, which contains your unique project code, to the <head> tag of your source code. If your package allows, you can manage multiple sites or apps from your Kameleoon account, which is useful for testing in staging or pre-production environments. When you create a project, the setup form guides you through four steps. Your installation method decides which options you see: If you turn on cross-domain tracking, the checklist also includes a task to host the Kameleoon static HTML file on your main domain.

​

Project configuration

In the Kameleoon app, click Admin > Projects to see a list of your projects. By default, your account has a project for the website or mobile app you entered when you signed up.

​

Configuring an existing project

To modify a project’s installation settings:

1. Click Admin > Projects.
2. Click Edit on the project’s row, then click the Setup tab.
3. In the Installation method or Technical configuration section, click Edit. The three-step setup form opens.

​

Creating a new project

To create a new project:

1. Click Admin > Projects, then click New project.
2. Select Web Experimentation, or All campaign types if you also run feature flags and SDK experiments from the same project. After you create the project, you can’t change its type. Click Next.
3. Enter the main project domain, choose a color, and optionally add a name, description, and tags, then click Next.
4. Select the installation method and, for the code snippet, the loading mode, then click Next.
5. Configure dynamic website support (code snippet only), resource hosting, and domains, then click Next. If you selected Shopify as the installation method, Kameleoon skips this step.
6. Complete the tasks in the checklist, then click Complete setup.

To finish later, click Save for later on the Installation method or Technical configuration step. Kameleoon saves the project as a draft, and the project appears on the Projects page with the Draft status. When you click Complete setup, Kameleoon saves the project as Enabled. For the full list of options, see Create a project.

​

Choose your implementation settings

In the Installation method step of the setup form, you choose how to install Kameleoon and how Kameleoon loads on your website. For technical details, including how to install Kameleoon using a tag manager or implement custom script types, see the Standard implementation article.

​

Consent

Before installing the Kameleoon script on your website, ensure your setup complies with your organization’s consent management policy. If you use a Consent Management Platform (CMP), you can integrate it with Kameleoon to control when Kameleoon activates experiments and data collection. For details, refer to Kameleoon’s consent management article.

​

Domains and subdomains

You can define which domains and subdomains can load the Kameleoon script and access its features.

• In the Technical configuration step, under Domains and subdomains, enter a domain and click Add domain to whitelist domains for cross-domain tracking.
  • This lets you use Kameleoon’s Graphic editor and store/retrieve visitor data across domains.
  • If you try to use Kameleoon on a domain not listed, loading will fail due to browser security policies (CORS).

​

Cross-domain tracking

Cross-domain tracking lets you:

• Track the same visitor across different domains and subdomains (for example, example.com and example.org).
• Avoid reclassifying users as “new visitors” when they move between domains.
• Offer consistent personalization and experiment experiences across properties.

​

Authorizations

If you’re targeting subdomains, check these two HTTP header settings:

• Don’t set an X-Frame-Options response header on the page that hosts the Kameleoon iframe.
• Allow Kameleoon resources in your Content Security Policy.

​

Resource hosting

You can choose whether Kameleoon hosts its public resources or if you prefer to self-host them.

• In the Technical configuration step, under Resource hosting, turn on Self-host the script file, Self-host images, or both.
• Enter the URL of your Content Delivery Network (CDN) or server in Script file URL, Image base URL, or both.

Learn more about resource hosting here.

​

Install the Kameleoon script

After you define your project’s main domain, Kameleoon generates a script for installation. You find it on the Setup tab and in the Add JavaScript snippet to your website task of the Checklist step.

1. Click Copy to copy the code snippet.
2. Paste it immediately after the <head> tag in your site’s source code.
3. Save and upload your updated pages to your server.
4. In Kameleoon, click Mark as completed.

​

Preventing flickering

When a webpage loads, users may briefly see the original version before Kameleoon applies the variation. This momentary flash is the flicker effect, or flickering. Flickering occurs when the variation’s changes load late, creating a visible switch between the original and modified content. Flickering can affect user experience and experiment reliability, especially in A/B testing.

​

Guidelines to avoid flickering

​

Implementation

Place the Kameleoon script as high as possible in the <head> tag. Ensure the script loads in under 1 second, ideally below 500 ms. To check Kameleoon’s loading time, use the Network tab in your browser’s developer tools. The most effective way of ensuring fast loading is installing Kameleoon directly in your HTML source code, rather than using a tag manager like Google Tag Manager. Optionally, you can use the anti-flicker script as an additional layer of protection against flickering. For more information, refer to Kameleoon’s developer documentation. If you enable this option, you’ll have several configurations to control how Kameleoon behaves if the timeout occurs. The timeout duration is configurable within the installed script and defaults to 750 ms. To explore the available options, refer to the screenshot below. You can access the Behavior if timeout occurs dropdown by clicking Admin > Projects, clicking Edit on your project’s row, and opening the Settings tab. Click Edit in the Campaign display section.

​

Consent

If you set your consent policy to consent required, flickering may occur on the first page view when the visitor hasn’t yet given consent. This flickering happens if you choose to partially or completely block Kameleoon when consent is unknown. To prevent flickering, don’t block Kameleoon, so experiments can display on the visitor’s landing page before the visitor gives consent. This approach is fully compliant with privacy regulations such as GDPR, CCPA, and other major frameworks in the UK, Canada, and the US, as no tracking or data storage (cookies/localStorage) occurs before the visitor grants consent. To explore available options, refer to the screenshot below. To access the Behavior when consent is unknown dropdown, click Admin > Projects, click Edit on your project’s row, and open the Consent tab. Click Edit in the For A/B tests and feature experiments or For personalizations section, then select Consent required in Consent policy.

​

Targeting

Use information available at page load

To improve performance, base targeting on data that’s available immediately on page load, such as:

• Page URL
• Browser type
• Device type
• cookies/localStorage

When possible, avoid targeting elements that load late, such as the dataLayer variables. Since these may load asynchronously, using them for targeting can delay variation execution. If a segment relies on a custom JS condition or custom data that itself depends on the dataLayer, flickering may occur as well. To minimize flickering, use targeting conditions that resolve as early as possible in the page lifecycle. To learn more about all targeting conditions in the Segment Builder, refer to this article.

​

Variation code

Use CSS instead of JavaScript for visual changes

Using CSS instead of JavaScript ensures faster and smoother rendering. Use CSS for:

• Hiding or modifying elements
• Swapping blocks
• Changing styles or text

Optimize JavaScript execution with the Activation API

If JavaScript is necessary, use Kameleoon’s Activation API to apply variations at the right moment:

• runWhenConditionTrue: Executes the code when a specific condition becomes true.
• runWhenElementPresent: Ensures that the variation displays when the targeted element loads on the page. Using these methods avoids delays caused by elements that load asynchronously.

Handling single-page applications

If your experiment runs on a single-page app (SPA) or a dynamically updating page, you need special implementation steps. For recommendations, follow the guide to setting up an experiment on an SPA.

​

FAQ