Command Queue

The Kameleoon platform offers a JavaScript-based Activation API for retrieving data (such as visitor geolocation) and modifying engine behavior (such as manual variation assignment).

However, developers must ensure the Kameleoon Engine loads before accessing the Activation API. This requirement complicates embedding JavaScript code directly in HTML files.

The Kameleoon Command Queue provides delayed command execution, similar to Google Analytics. Instead of calling the Activation API via the Kameleoon.API object, pass commands and functions to the kameleoonQueue object. The engine executes these commands immediately if loaded; otherwise, it queues them for execution when ready.

Usage and description of the Command Queue Object

To use the kameleoonQueue object, execute the following initialization code first. The Kameleoon installation tag typically includes this code at the top of the HTML file, after the opening <head> tag. In this case, no further action is required. However, if using a custom setup (for example, loading Kameleoon via a Tag Manager), initialize the queue before adding custom code.

window.kameleoonQueue = window.kameleoonQueue || [];

While the Kameleoon application file loads, kameleoonQueue acts as a standard JavaScript array that accepts commands via the push() method. After loading, the engine processes the array and executes commands in order. The engine then replaces the array with a custom object whose push() method executes commands immediately.

Syntax

Pass either an array or an anonymous function to the push() method.

kameleoonQueue.push(['Kameleoon.API.Events.trigger', 'myCustomEvent']);
kameleoonQueue.push(['Events.trigger', 'anotherEvent']);

When passing an array, the first object represents the Kameleoon API method name (as a string), and subsequent objects represent the method arguments.

note

Use either the full method name (e.g., Kameleoon.API.Core.enableLegalConsent) or the short name (e.g., Core.enableLegalConsent). Additional arguments are optional.

Pass an anonymous function directly as an argument. Kameleoon uses the function as a callback when ready for processing.

kameleoonQueue.push(function() {
  const experimentID = 1;
  const variationID = 3;
  Kameleoon.API.Experiments.assignVariation(experimentID, variationID);
});

The command queue also works within HTML code, as shown in the example below. Initialize kameleoonQueue before the browser encounters the targeted HTML element to ensure click tracking, even if the engine has not loaded.

<button onclick="kameleoonQueue.push(['Goals.processConversion', 42]);">
  Action Button with Kameleoon goalID = 42
</button>

note

By default, Kameleoon executes queued commands when the configuration (campaigns, goals, segments, etc.) is ready and after the global custom script runs.

Use the level: "IMMEDIATE" argument when pushing a command to execute it immediately, without waiting for configuration processing. This is useful for code required before Kameleoon instantiates functions.

Here's an example of how to use the level: "IMMEDIATE" argument:

function callback = () => {
 {... any code to run before Kameleoon triggers any campaign code}   
};
window.kameleoonQueue.push({
	level: "IMMEDIATE",
	command: callback
});

In this example, the callback function executes immediately, regardless of configuration processing.

Use the level: "IMMEDIATE" argument to override internal Kameleoon functions. Standard function redefinition fails if the engine loads and executes the original version first. The IMMEDIATE level ensures the custom function executes before the engine loads its own version.

Usage and description of the Command Queue Object​

Syntax​

Usage and description of the Command Queue Object

Syntax