Setup

This page walks you through the whole setup: install Kameleoon on your site, prepare your Kameleoon project, then connect your account so the agent and the Kameleoon panel can work with it. It takes about ten minutes.

What you need: a Highwind project (ideally already published) and a Kameleoon account with a project (site) for your app.

1. Get the site code

The site code identifies your Kameleoon project. It is public: it shows up in your site’s code anyway, it is not a secret.

1. In Kameleoon, open Admin → Projects.
2. Find your project and copy the value in the Sitecode column (you also find it in the project header, with a copy button).

A site code is made of letters and digits only.

2. Add Kameleoon to your app

1. In your project’s chat, type @ (or open the + menu → Connectors) and choose Kameleoon, the entry in the Analytics category. Complete your request, for example:

   @Kameleoon Add Kameleoon so I can run A/B tests on the site.

2. Send the message. The agent adds the connector and a The agent needs your Kameleoon connection card shows up in the chat.

3. Choose a connection already saved in your account (Use a connection from your account) or paste the site code in the Site code field, then confirm. Highwind checks that the code matches a Kameleoon project, without changing anything on your side.

4. The agent installs the Kameleoon tag. When it’s done, click Publish to put the tag online.

Two “Kameleoon” entries in the menu

The connectors menu offers two Kameleoon entries: the one in the Analytics category is the app connector (the tag on your site); the one in the Context for the agent category is the context source (your account, see step 5). To install Kameleoon on your site, pick the first one.

You can also link the connector from the project settings, and change the site code later in Project settings → Secrets (value KAMELEOON_SITE_CODE).

What the agent puts in index.html

By default (A/B tests and personalizations built in Kameleoon), the agent places at the very top of <head>, before any other script:

• a small anti-flicker script: the page stays hidden while Kameleoon applies the variation, for at most 750 ms, so visitors never see the original “flash” before the variation;
• your project’s engine.js tag, loaded from kameleoon.io, with an automatic fallback to kameleoon.eu (older projects are hosted on that domain).

The agent never uses the old kameleoon.js tag, which is no longer supported. On a dark site, it matches the anti-flicker overlay color to the site’s background.

See the installed code

SITE_CODE is replaced with your site code.

<script>
  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 src="https://SITE_CODE.kameleoon.io/engine.js" fetchpriority="high" async onerror="this.onerror=null;var s=document.createElement('script');s.src='https://SITE_CODE.kameleoon.eu/engine.js';s.async=true;document.head.appendChild(s)"></script>

For feature flags decided in code, the agent can use Kameleoon’s JavaScript SDK instead of the tag: ask for it explicitly (see The agent and Kameleoon).

3. Prepare your Kameleoon project

Three settings are made in Kameleoon. The agent reminds you of them in its summary.

Turn on support for dynamic websites

A Highwind app is a single-page React application: when visitors move to another page, the browser doesn’t reload everything. For Kameleoon to reapply your experiments on every navigation:

1. In Kameleoon, open Admin → Projects, then your project.
2. Go to Setup → Technical configuration.
3. Turn on Enable support for dynamic websites.

Caution

Without this setting, an experiment may only apply to the first page viewed, and not after navigating within the site.

Choose the consent policy

In the European Union, Kameleoon may only track a visitor with their consent. The agent wires your site’s cookie banner to Kameleoon: when the visitor accepts, the banner calls enableLegalConsent(); when they decline, disableLegalConsent(). A visitor is never left in an unknown state.

In Kameleoon, open Admin → Projects → Consent and choose the policy that matches this behavior (consent managed by your site).

Tip

If your site doesn’t have a cookie banner yet, ask for one at the same time: “Add a cookie banner wired to Kameleoon consent”.

Declare the published site’s address

Kameleoon only applies your experiments on the domains declared for the site. In your Kameleoon project settings, add your published app’s address: for example my-app.highwind.site, or your custom domain. You can also declare a wildcard domain such as *.highwind.site.

Tip

The Kameleoon panel suggests this address as the Tested page when you create an experiment. With a wildcard domain (*.highwind.site), the suggested address isn’t your app’s: fix it before creating the experiment.

4. Get your API credentials

For the agent and the panel to access your account, you need your Kameleoon API credentials.

1. In Kameleoon, click your profile (top right), then My profile.
2. Click See my API credentials, or Generate if you don’t have any yet.
3. Keep the client ID and the client secret at hand.

Caution

These credentials carry the same rights as your Kameleoon account. Only paste them in the Highwind form meant for them, never in the chat.

5. Connect the Kameleoon source

1. Open the Connectors page (main menu, or the chat’s + menu → Manage connectors).
2. In the Context for the agent category, open Kameleoon.
3. Paste your Client ID and Client secret, then click Connect. Highwind checks the credentials with Kameleoon and stores them encrypted.
4. The card shows: “Connected: the agent can read your Kameleoon sites, experiments, feature flags and goals.”

Allow the agent to make changes

Once connected, the card shows the Allow the agent to make changes switch. It is off by default.

• Off: the agent and the panel only read. The panel is Read-only.
• On: the agent can also create and edit (experiments, feature flags, goals…) when you explicitly ask it to, and the panel lets you create experiments, variations and goals, and start your tests.

Even when it’s on, the agent only changes what you ask for, and never in Discussion mode. See The agent and Kameleoon.

6. Open the Kameleoon panel

Go back to your project (if the mode doesn’t show up right away, reload the editor page). The switch at the top of the left panel now shows three modes: Chat | Design | Kameleoon. Click Kameleoon.

The panel shows up when three conditions are met:

• the Kameleoon source is connected on your account (the project owner’s);
• the project has a site code (Kameleoon app connector added);
• that code matches a site in the connected Kameleoon account.

If something is stuck

Symptom	Likely cause	Fix
The site code is rejected	Code miscopied, or project not found	Copy the Sitecode column again (letters and digits only).
The credentials are rejected	Client secret miscopied, or credentials regenerated since	Generate them again in Kameleoon and reconnect the source.
No Kameleoon mode in the editor	One of the three conditions is missing	Check the source, the site code, then reload the editor.
The site code belongs to another account	The site isn’t visible with your credentials	Connect the credentials of the account that owns this site.
Experiments don’t apply on the site	Tag not published yet, domain not declared, or dynamic websites off	Publish, declare the site’s address, turn on support for dynamic websites.

See also

The Kameleoon panelWhat you see and what you can do in the editor's third mode.

Kameleoon connector cardPermissions, use cases and setup of the app connector.

Kameleoon context sourceWhat the agent reads in your Kameleoon account.

Publish your appPut the Kameleoon tag online with your latest version.