NAV
JavaScript
  • Command Queue

    • Command Queue

    Context

    The Kameleoon platform provides a JavaScript based Activation API that the customer can use for various purposes. Data can be retrieved in a read-only mode from the API (for instance, to fetch information about the visitor such as his geolocation), and the API also provides methods that write data into the engine and modify its standard behavior (for example, to manually assign a variation for a given experiment).

    Since the Activation API is a JavaScript API, it can be a bit tricky to access any property or method in the API, because the developer must be sure that the Kameleoon Engine is ready (ie, that the Kameleoon application file has loaded) before doing so. Besides, calls to the API may be made either in JavaScript files, or directly in JavaScript code embedded in the HTML file outputted by the back-end server. In the case of embedded JS code, it can be especially cumbersome for the back-end developer to check for the actual presence of the Kameleoon.API JS object and delay code execution accordingly.

    We provide a solution for this, inspired by Google Analytics which faced the exact same problem and solved it in an elegant way. A Kameleoon Command Queue object is available, which allows for delayed command execution. The principle is simple: instead of directly calling the Activation API via the Kameleoon.API JavaScript object, you pass commands and functions to another JavaScript object, kameleoonQueue. If the Kameleoon engine is already loaded, the commands / functions will be instantly executed, otherwise they will be queued and will be executed once the engine is ready.

    Usage and description of the Command Queue Object

    Initialization

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

    To properly initialize the Kameleoon command queue, the following code must be executed BEFORE any use of the kameleoonQueue object. Normally, this code is included in the Kameleoon installation tag, which should be placed at the very top of the HTML file, after the opening <head> tag, so you don't have to do anything. If this is not the case (ie. your setup is not a recommended one, for instance you load Kameleoon via a Tag Manager), be sure to include the initialization before your custom code.

    While the Kameleoon application file is loading, kameleoonQueue is simply a standard JavaScript array, and can be filled via the push() method. Once Kameleoon has loaded, its engine will look into this array and execute (in the order they were pushed) any commands that were present there. It then replaces the array by a custom object, whose push() method will now instantly execute any command given as argument.

    Syntax

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

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

    In the case of an array, by convention the first object of the array must be the name of a Kameleoon API method (a string), and the next objects are arguments to that method. Note that the name can be either the full name of the method (ie Kameleoon.API.Core.enableLegalConsent) or just short names (Core.enableLegalConsent). Additional arguments are optional.

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

    In the case of an anonymous function, you just pass the function directly as argument, and it will be used as a callback when Kameleoon is ready to process it.

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

    Of course, you can also use the command queue directly in the HTML code of your page, as shown in this example. As long as the kameleoonQueue initialization code was executed before the browser encounters the targeted HTML element, clicks will be tracked without errors, even if the Kameleoon engine isn't yet loaded at the time of the click.

    JavaScript