Command Queue - Kameleoon Documentation

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. If the engine has loaded, it executes these commands immediately. Otherwise, it queues them for execution when it’s 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, you don’t need to take any further action. 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.

Use either the full method name (for example, Kameleoon.API.Core.enableLegalConsent) or the short name (for example, 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 hasn’t loaded.

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

By default, Kameleoon executes queued commands when the configuration (campaigns, goals, segments, and so on) 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 option is useful for code that must run before Kameleoon instantiates functions.Here’s an example of how to use the level: "IMMEDIATE" argument:

const 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.

APIs

​Usage and description of the command queue object

​Syntax

Usage and description of the command queue object

Syntax