Skip to main content

Command Queue

The Kameleoon platform offers a JavaScript-based Activation API that developers can use for various purposes. The API allows for retrieving data in a read-only mode, such as visitor geolocation information, as well as modifying the engine's behavior, such as manually assigning a variation for a specific experiment.

However, accessing the Activation API can be tricky for developers because they need to ensure that the Kameleoon Engine has loaded before making any API calls. This is especially cumbersome for back-end developers who embed JavaScript code directly in HTML files.

To address this issue, we provide a solution inspired by Google Analytics, which faced a similar problem and solved it elegantly. We offer a Kameleoon Command Queue object that allows for delayed command execution. Instead of directly calling the Activation API via the Kameleoon.API JavaScript object, developers can pass commands and functions to the kameleoonQueue JavaScript object. If the Kameleoon engine is already loaded, the commands/functions will be executed immediately; otherwise, they will be queued and executed once the engine is ready.

Usage and description of the Command Queue Object​

Initialization​

To initialize the Kameleoon command queue correctly, you must execute the following code before using the kameleoonQueue object. This code is typically included in the Kameleoon installation tag, which should be placed at the top of the HTML file, after the opening <head> tag. In this case, there is nothing you need to do. However, if you do not follow this recommended setup (for example, if you load Kameleoon via a Tag Manager), make sure to include the initialization before your custom code.

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

While the Kameleoon application file is loading, kameleoonQueue is a standard JavaScript array that can be filled using the push() method. After Kameleoon has loaded, its engine will look into this array and execute any commands in the order they were pushed. It then replaces the array with a custom object whose push() method immediately executes any command given as an argument.

Syntax​

There are two ways to use the command queue. You can either pass an array or an anonymous function as an argument to the push() method.

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

When passing an array, it is convention to have the first object of the array be the name of a Kameleoon API method (as a string), and the subsequent objects to be arguments to that method.

note

The name can be either the full name of the method (ie Kameleoon.API.Core.enableLegalConsent) or just the short names (Core.enableLegalConsent). Additional arguments are optional.

When passing an anonymous function, simply pass the function directly as an argument, and it will be used as a callback when Kameleoon is prepared to process it.

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

You can also use the command queue in the HTML code of your page as shown in this example. As long as the initialization code for kameleoonQueue is executed before the targeted HTML element is encountered by the browser, clicks will be tracked without any errors, even if the Kameleoon engine is not yet loaded at the time of the click.

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

When you use the kameleoonQueue, by default Kameleoon will execute the queued commands when the configuration of your campaigns, goals, segments, etc. are ready to be processed AND after the global custom script is executed.

If you have any code that needs to be triggered before Kameleoon instantiates any function, you can use an additional argument level: "IMMEDIATE" while pushing a command to the queue. This argument tells Kameleoon to execute the command immediately, without waiting for any configuration to be processed.

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 will be executed immediately, without waiting for any configuration to be processed by Kameleoon.

Additionally, using the level: "IMMEDIATE" argument in conjunction with the kameleoonQueue can also be useful if you want to override an internal function that is used by Kameleoon. If you simply define a new function with the same name, it will not work because Kameleoon will have already loaded and executed its own version of the function before your code runs. However, by using the level: "IMMEDIATE" argument, you can ensure that your custom function is executed before Kameleoon loads its own version of the function, effectively overriding it.