Kameleoon.API.Core - Kameleoon Documentation

This module contains functions for implementing frontend A/B testing variations without flickering. The module also includes engine initialization methods, which cover privacy laws and legal consent collection.

enableLegalConsent

Call the enableLegalConsent() method after you obtain legal consent from the visitor to activate Kameleoon. This method activates Kameleoon’s normal operation mode. For more information, refer to the Consent management article.

var agreedButton = Kameleoon.API.Utils.querySelectorAll("#agreed")[0];

Kameleoon.API.Utils.addEventListener(agreedButton, "mousedown", function (event) {
  Kameleoon.API.Core.enableLegalConsent();
});

Arguments

Name	Type	Description
module	String	Name of the module to enable: `PRODUCT_RECOMMENDATION`, `AB_TESTING`, `PERSONALIZATION`, or `BOTH`. For example, `PRODUCT_RECOMMENDATION` executes the entry point exclusively with product recommendation capabilities. `AB_TESTING` enables A/B testing and product recommendation (unless the custom option to differentiate consent is active). `BOTH` enables all capabilities. If omitted, the method activates legal consent for all modules (`BOTH`) by default.

A custom option is also available that allows separate management of Product Recommendation consent. When this option is active, explicitly call enableLegalConsent("PRODUCT_RECOMMENDATION") to activate the module. Contact the Customer Success Manager to enable this feature.

disableLegalConsent

Call the disableLegalConsent() method when a visitor declines the use of Kameleoon. This method disables normal operation mode. For more information, refer to the Consent management article.

var disableButton = Kameleoon.API.Utils.querySelectorAll("#disable")[0];

Kameleoon.API.Utils.addEventListener(disableButton, "mousedown", function (event) {
  Kameleoon.API.Core.disableLegalConsent();
});

Arguments

Name	Type	Description
module	String	Name of the module to turn off: `AB_TESTING`, `PERSONALIZATION`, or `BOTH`. If omitted, the method turns off legal consent for all modules (`BOTH`).

A custom option is also available that allows separate management of Product Recommendation consent. When this option is active, explicitly call disableLegalConsent("PRODUCT_RECOMMENDATION") to turn off the module. Contact the Customer Success Manager to enable this feature.

enableSinglePageSupport

The enableSinglePageSupport() method reloads the Kameleoon engine when the active URL changes, regardless of browser page loads. Use this method for Single Page Applications (SPAs) with multiple URLs and a single initial load. Kameleoon treats each URL change as a new page, enabling URL targeting and accurate tracking of metrics like page views.

if (location.href.indexOf("mySPAWebsitePart") != -1) {
  Kameleoon.API.Core.enableSinglePageSupport();
}

Kameleoon also automatically removes all elements added to the page that use HTML IDs that begin with “kameleoonElement” or “kameleoonStyleSheet” when the SPA reloads.

enableDynamicRefresh

The enableDynamicRefresh() method detects element changes and reapplies Graphic Editor modifications. This method supports SPAs that dynamically modify the DOM without URL changes or page reloads, preventing dynamic updates from removing experiments. Refer to enableSinglePageSupport() for other SPA types.

if (location.href.indexOf("cart") != -1) {
    Kameleoon.API.Core.enableDynamicRefresh();
}

getConfiguration

The getConfiguration() method returns a reference to the Configuration object, which contains global constant values for the site’s Kameleoon configuration.

var configuration = Kameleoon.API.Core.getConfiguration();

if (configuration.siteCode == "abcde12345") {
  document.cookie = "MyMainSite=true;";
} else if (configuration.siteCode == "12345abcdef") {
  document.cookie = "MySubSite=true;";
}

Return value

Name	Type	Description
configuration	Object	Configuration object.

load

The load() method initializes the Kameleoon engine. While initialization typically occurs automatically during application file loading, you might need to make manual calls. To reload Kameleoon after each URL change in a single-page app, use enableSinglePageSupport() instead of watching the URL yourself.

Kameleoon.API.Core.load();

Kameleoon also automatically removes all elements added to the page that use HTML IDs that begin with “kameleoonElement” or “kameleoonStyleSheet” when the SPA reloads.

processRedirect

The processRedirect() method redirects the browser to another URL, typically for split A/B experiments. Use this method instead of window.location.href = redirectionURL; to ensure accurate background tracking.

var experiment = Kameleoon.API.Experiments.getByName("RedirectExperiment");

if (experiment.associatedVariation.id == 123456) {
  Kameleoon.API.Core.processRedirect("https://www.mywebsite.com?variation=A");
}

If the redirection URL is on a domain other than the base URL and the Kameleoon installation omits unified session data, the engine adds a kameleoonRedirect-{experimentID} parameter to the target URL to ensure accurate tracking.

Arguments

Name	Type	Description
redirectionURL	String	URL for redirection. This field is mandatory.

runWhenConditionTrue

The runWhenConditionTrue() method executes the callback function when the conditionFunction returns true. The method uses a polling mechanism, which might cause flickering. Use runWhenElementPresent() instead for improved performance. Refer to the runWhenElementPresent() description for details.

Kameleoon.API.Core.runWhenConditionTrue(function () {
  return typeof jQuery != "undefined";
}, function () {
  jQuery("#bloc-2345").text("Mon nouveau texte");
}, 200);

Arguments

Name	Type	Description
conditionFunction	Function	JavaScript function returning true or false. This field is mandatory.
callback	Function	JavaScript function executing when the conditionFunction returns true. This field is mandatory.
pollingInterval	Number	The engine executes the conditionFunction periodically at this interval. When `runWhenElementPresent()` is unavailable, a lower pollingInterval reduces flickering but increases CPU usage. If omitted, the method defaults to 200 milliseconds.

runWhenElementPresent

The runWhenElementPresent() method executes the callback function when a specific element appears in the DOM. This method uses mutation observers to power antiflickering technology. Identify the key elements for a variation and call runWhenElementPresent() with the element as the first argument and the implementation code as the callback. Calling the method ensures that modifications execute when the element appears, before the browser initiates a display refresh cycle. To act on multiple elements, call runWhenElementPresent() separately for each element rather than targeting only the expected final element. A single call may result in flickering if a refresh cycle occurs between the appearance of different elements.

// With mutation observers management.
Kameleoon.API.Core.runWhenElementPresent("#bloc-2345", function (elements) {
 elements[0].innerText = "My new Text";
});

// With multiple CSS selectors. Executes if any one of the elements is present.
Kameleoon.API.Core.runWhenElementPresent("#bloc-567, .cta-button, #bloc-789", function (elements) {
 elements[0].innerText = "More new text";
});

// Without mutation observers management, Kameleoon polls every 200ms to check if the element is on the page.
Kameleoon.API.Core.runWhenElementPresent("#MyPopup.showed", function (elements) {
 Kameleoon.API.Events.trigger("popup displayed");
}, 200);

// With mutation observers management and Single Page App support, Kameleoon applies modifications whenever new elements are added to the DOM or when there is a dynamic refresh of the Single Page App that removes previous modifications.
Kameleoon.API.Core.runWhenElementPresent(".product-button", function (elements) {
 elements.forEach(element => {
  element.innerText = "Add To Cart";
 });
}, null, true);

Providing this value disables Mutation Observers and Anti-Flickering, reverting to legacy polling. Use this argument only in specific cases, such as complex selector queries with high CPU impact.

Arguments

Name	Type	Description
selector	String	CSS selector of the element. To specify multiple CSS selectors, provide a single comma-separated string. The callback executes when one or more elements exist. This field is mandatory.
callback	Function	JavaScript function to execute when the element appears in the DOM. This field is mandatory.
pollingInterval	Number	Providing this value disables Mutation Observers and reverts the engine to legacy polling, which may cause flickering. This field is optional.
isDynamicElement	Boolean	When active, Kameleoon tracks the selector if not immediately found at page load and executes the callback as elements appear. The callback triggers again for each new element matching the selector. This setting supports dynamic menus, infinite scrolling, and pop-ups. This field is optional.

runWhenShadowRootElementPresent

The runWhenShadowRootElementPresent() method executes the callback function when a specific element appears in a shadow DOM set to mode: open.

const wrapper = document.querySelector(".shadow-wrapper");
const shadow = wrapper.attachShadow({ mode: "open" });
const span = document.createElement("span");
span.classList.add("selector-inside-wrapper");
span.textContent = "I'm in the shadow DOM";
shadow.appendChild(span);

Kameleoon.API.Core.runWhenShadowRootElementPresent('.shadow-wrapper', '.selector-inside-wrapper', (elements) => {
    elements[0].innerText = "New text" 
});

Arguments

Name	Type	Description
parentSelector	String	CSS selector for the parent element. This field is mandatory.
shadowRootElementSelector	String	CSS selector inside the shadow DOM. This field is mandatory.
callback	Function	JavaScript function to execute when the element appears in the shadow DOM. This field is mandatory.
isDynamicElement	Boolean	When active, Kameleoon tracks the selector if not immediately found and executes the callback as elements appear. The callback triggers again for each new element matching the selector. This setting supports dynamic menus, infinite scrolling, and pop-ups.

APIs

​enableLegalConsent

​disableLegalConsent

​enableSinglePageSupport

​enableDynamicRefresh

​getConfiguration

​load

​processRedirect

​runWhenConditionTrue

​runWhenElementPresent

​runWhenShadowRootElementPresent

enableLegalConsent

disableLegalConsent

enableSinglePageSupport

enableDynamicRefresh

getConfiguration

load

processRedirect

runWhenConditionTrue

runWhenElementPresent

runWhenShadowRootElementPresent