Writing efficient custom code in Web Experimentation

In the Kameleoon App, there are multiple entry points where you can add custom JavaScript that executes on your website. This article provides specific recommendations for each available entry point. Note that all Kameleoon scripts run once per page load. Before implementing custom scripts, consider using Kameleoon Command Queue for optimized execution.

Kameleoon Command Queue

The most efficient way to interact with Kameleoon’s API (whether for converting goals, setting custom data, or triggering events) is to leverage existing triggers in your Tag Manager (for example, Google Tag Manager) alongside the Kameleoon Command Queue. Combining Tag Manager triggers with the Command Queue should be your primary approach when adding JavaScript to Kameleoon. Instead of writing lengthy JavaScript code directly in Kameleoon, you can achieve the same results with just two lines of code within your Tag Manager.

Examples

- Convert a revenue goal In your Tag Manager, create a trigger on the confirmation page to capture the revenue, and add the following code:

// Replace kameleoonGoalID and {{revenue}} with your actual values
window.kameleoonQueue = window.kameleoonQueue || [];
window.kameleoonQueue.push(['Goals.processConversion', kameleoonGoalID, {{revenue}}])

For guidance on creating a goal conversion from GTM, see this documentation. -Set a Custom Data value when the visitor logs in Instead of writing custom JS in Kameleoon, set the value directly via your Tag Manager:

// Replace "customDataName" and "customDataValue" with your actual values
window.kameleoonQueue = window.kameleoonQueue || [];
window.kameleoonQueue.push(['Data.setCustomData', "customDataName", "customDataValue"]);

- Trigger an event when a visitor adds a product to the cart Use this to target visitors based on specific actions:

// Replace "customEventName" with your actual event name
window.kameleoonQueue = window.kameleoonQueue || [];
window.kameleoonQueue.push(['Events.trigger', "customEventName"]);

If you can’t use kameleoonQueue, see the specific recommendations for each available script detailed below.

Global Script & variation scripts

Optimize JavaScript execution with the Activation API

Utilize Kameleoon’s Activation API to apply variations at the appropriate time. This approach helps prevent performance issues and ensures a seamless experience for visitors. Below are some essential functions of the Activation API that you can use to improve visitor experience:

runWhenConditionTrue : Executes the code when a specific condition returns true. By default, it runs every 200 milliseconds. However, be careful with conditions that may never resolve, as this can lead to unnecessary looping. Note that the loop will continue running until the function explicitly returns true. Returning false or undefined won’t stop the loop or trigger the callback.

❌ Incorrect usage (Infinite loop risk): The following example will never return true on all pages other than the product page, causing the loop to run indefinitely:

Kameleoon.API.Core.runWhenConditionTrue(() => {
    return window.dataLayer && window.dataLayer.find(layer => layer.pageType === "product");
}, () => {
    // Product page logic here
});

✅ Recommended approach: Always return true to exit the loop, and then handle the logic inside the callback:

let pageTypeLayer;
Kameleoon.API.Core.runWhenConditionTrue(() => {
    pageTypeLayer = window.dataLayer && window.dataLayer.find(layer => layer.pageType);
    return pageTypeLayer; 
}, () => {
    if (pageTypeLayer?.pageType === "product") {
        // Product page logic here
    }
});

It’s preferable to retrieve information using the URL or cookies/localStorage instead of depending on runWhenConditionTrue to wait for the dataLayer or other late-loading objects, like when trying to get information about the page type. This approach ensures faster execution and better performance.

runWhenElementPresent: This method ensures that your code runs only when a specific element is present in the DOM, avoiding unnecessary delays caused by dynamically loaded elements.

Key considerations

Uses Mutation Observers by default (recommended for performance).
If you turn off Mutation Observers on your site, you can specify a polling interval as the third argument of this method.
If the element is dynamically inserted into the DOM, set isDynamicElement to true as the fourth argument of this method:

Use the code below sparingly and only when absolutely necessary. Limit its usage to the minimum number of cases and avoid applying it to multiple elements simultaneously to maintain optimal page performance.Be mindful of the potential for an infinite loop if the source code of the page modifies the element on every update.

Kameleoon.API.Core.runWhenElementPresent('#myDynamicElement', ([elem]) => {
	// Logic once the element loaded
}, null, true); // isDynamicElement is set to true

Set your code’s scope to specific pages

To optimize performance, make sure your code executes only on the relevant pages. Care matters most with loop-based methods such as runWhenConditionTrue and runWhenElementPresent, because running them across the entire site can lead to unnecessary executions and affect performance. For instance, if you are waiting for revenue information in the dataLayer, wrap your code in a condition that checks whether the URL corresponds to the confirmation page. This approach ensures that the code runs only on the confirmation page instead of running site-wide. Example: Targeting a specific confirmation page before running a loop

if (document.location.href.includes('/confirmation')) {
    let revenueLayer;
    Kameleoon.API.Core.runWhenConditionTrue(() => {
        revenueLayer = window.dataLayer && window.dataLayer.find(layer => layer.revenue);
        return revenueLayer;
    }, () => {
        Kameleoon.API.Goals.processConversion(goalId, revenueLayer.revenue);
    });
}

Similarly, if you’re waiting for an element to load on the page, make sure the element will appear at some point, and run the script only on the relevant page.

if (document.location.href.includes('/subscription')) {
    Kameleoon.API.Core.runWhenElementPresent("#form", () => {
        // Add the rest of your logic here
    });
}

3. Prefer CSS for visual changes instead of using JavaScript, especially when dealing with variations in scripts

Using CSS instead of JavaScript results in faster and smoother rendering. You can use CSS to hide or modify elements, swap blocks, and change styles or text.

Handling single-page apps (SPAs)

If an experiment runs on a single-page app (SPA) or a dynamically updating page, you need specific implementation steps. Unlike traditional websites, SPAs don’t reload entire pages, so Kameleoon needs to identify when content updates happen. See the guide on setting up an experiment on a single-page app for best practices.

Segments / Triggers

The first best practice is to base targeting on data that’s immediately available when the page loads. This includes information such as the page URL, browser type, device type, and any data stored in cookies or local storage. If your targeting requires data that isn’t instantly accessible, follow these guidelines to ensure efficient execution and avoid unnecessary delays.

1. Custom Javascript condition

This condition allows you to use custom JavaScript to target visitors. There are two main options available: ####- a. Checking the condition immediately This script executes every 75 milliseconds before the DOM is fully loaded, and then every 250 milliseconds afterward. By default, it returns undefined, which causes the script to continue running in a loop until it explicitly returns true (to include the visitor) or false (to exclude them). Always ensure that your condition eventually resolves to either true or false to prevent unnecessary looping. Here’s an optimized example:

if (window.dataLayer && window.dataLayer.some(layer => layer.pageType == "homepage")) return true; 

else if (window.dataLayer && window.dataLayer.some(layer => layer.pageType != "homepage")) return false;

####- b. Running the condition asynchronously Use this script when you need to wait for a response from an external web service or API before targeting the visitor. Once you receive the response, call setTargeting(true) or setTargeting(false). See the code below.

If you want to target a specific element, use the native condition “Element on the page” instead.
If you want to wait for information on the page, use the “check condition immediately” option described earlier.

const userId = localStorage.getItem("user_id"); 
if (!userId) {
   setTargeting(false);
}
// Example API endpoint - replace with your actual endpoint
const apiUrl = `https://api.example.com/check-segment?userId=${userId}`;

fetch(apiUrl, { method: "GET", headers: { "Content-Type": "application/json" } })
  .then(response => response.json())
  .then(data => {
    if (data && data.isInSegment) {
      setTargeting(true);
    } else {
      setTargeting(false);
    }
  })
  .catch(error => {
    setTargeting(false);
  });

2. Custom event

Using custom events is an effective and passive way to target visitors. Rather than continuously monitoring conditions, this method listens for a specific custom event that you define and triggers targeting when that event occurs. This approach is particularly useful in two key scenarios:

Scenario 1: When the targeting logic is complex

It’s better to avoid embedding all the logic directly in a JavaScript condition within the targeting. Instead, you can define a custom event in the Global Script. For example, if you want to target visitors on the cart page who have at least three products in their cart and a total amount of more than $30, you would trigger an event in the Global Script once a visitor meets these conditions, rather than writing all of the logic within the JavaScript segment condition. If several segments require the same or slightly different variations of the same condition, using a custom event prevents redundant code and enhances maintainability. Example: You need to target visitors based on different cart amounts. Instead of duplicating the logic in multiple segments, you define a single script in the Global Script and trigger different custom events for each segment:

if (document.location.href.includes('/cart')) {
    Kameleoon.API.Core.runWhenElementPresent("#cartContainer", ([cartContainer]) => {
        if (cartContainer.length >= 3) {
            const totalAmount = Number(cartContainer.querySelector('#totalAmount').innerText);
          
            if (totalAmount >= 90) 
                Kameleoon.API.Events.trigger("3ArticlesAbove90"); // Segment 1
            else if (totalAmount >= 60) 
                Kameleoon.API.Events.trigger("3ArticlesAbove60"); // Segment 2
            else if (totalAmount >= 30) 
                Kameleoon.API.Events.trigger("3ArticlesAbove30"); // Segment 3
        }
    });
}

Custom Data

Custom data, like custom events, helps to avoid duplicate code by allowing you to store and reuse values. You can define custom data in the Global Script or in other scripts, and then utilize it within segments. However, custom data differs from custom events in two key ways:

a. By the scope options: “Page,” “Visit,” or “Visitor”

Unlike custom events, which only apply to the current page, custom data can persist across multiple pages and sessions:

Visit Scope: This keeps the value throughout a visitor’s session.
Visitor Scope: This stores the value for up to 365 days, depending on the cookie policy.

For example, if you want to display a banner on all pages once a visitor logs in, you can set a custom data value to “true” with a visit scope. A visit-scoped value keeps the visitor targeted with the banner across all pages during their session after logging in.

b. By enhanced experiment insights

Custom data can serve as filters and breakdown criteria on the results page of experiments. Filtering and breaking down results by custom data enables deeper insights and allows for more effective analysis of visitor behavior. To discover all available targeting conditions in the segment builder, see this documentation.

Home

Web Experimentation

Feature Experimentation

Core concepts

Privacy and compliance

Developer tools

Writing efficient custom code in Web Experimentation

Kameleoon Command Queue

Examples

Global Script & variation scripts

Optimize JavaScript execution with the Activation API

Key considerations

Set your code’s scope to specific pages

3. Prefer CSS for visual changes instead of using JavaScript, especially when dealing with variations in scripts

Handling single-page apps (SPAs)

Segments / Triggers

1. Custom Javascript condition

2. Custom event

Scenario 1: When the targeting logic is complex

Custom Data

a. By the scope options: “Page,” “Visit,” or “Visitor”

b. By enhanced experiment insights

Home

Web Experimentation

Feature Experimentation

Core concepts

Privacy and compliance

Developer tools

​Kameleoon Command Queue

​Examples

​Global Script & variation scripts

​Optimize JavaScript execution with the Activation API

​Key considerations

​Set your code’s scope to specific pages

​3. Prefer CSS for visual changes instead of using JavaScript, especially when dealing with variations in scripts

​Handling single-page apps (SPAs)

​Segments / Triggers

​1. Custom Javascript condition

​2. Custom event

​Scenario 1: When the targeting logic is complex

​Scenario 2: When multiple segments share similar logic

​Custom Data

​a. By the scope options: “Page,” “Visit,” or “Visitor”

​b. By enhanced experiment insights

Kameleoon Command Queue

Examples

Global Script & variation scripts

Optimize JavaScript execution with the Activation API

Key considerations

Set your code’s scope to specific pages

3. Prefer CSS for visual changes instead of using JavaScript, especially when dealing with variations in scripts

Handling single-page apps (SPAs)

Segments / Triggers

1. Custom Javascript condition

2. Custom event

Scenario 1: When the targeting logic is complex

Scenario 2: When multiple segments share similar logic

Custom Data

a. By the scope options: “Page,” “Visit,” or “Visitor”

b. By enhanced experiment insights