Activation API Reference

Introduction

The Activation API is a JavaScript API provided directly by the Kameleoon application file installed on your website. You can call the methods of this API directly via JavaScript code. You can also read useful information from a variety of data structures available via this API. For instance, we provide geolocation and weather data of the current visitor, as well as the KCS (Kameleoon Conversion Score), our real-time, customer-centric, machine-learning powered score (note that the KCS is only available if you activate our A.I. Personalization module).

This is the reference documentation for version 1.0 of the Activation API. Code samples are on the right section. It details both the API entry points (modules containing static methods) as well as the objects (data structures). The methods in the modules can be called directly (for instance Kameleoon.API.Core.enableLegalConsent()), while of course data in the objects can be read only after you've obtained a reference to the desired object.

Note that not all modules, objects and methods are available to every customer. Some of them depend on specific commercial subscriptions. For example, obviously Kameleoon.API.Experiments is only available with an active subscription to the A/B testing module, and Kameleoon.API.Personalizations is only available with an active subscription to the Personalization module. When this is the case, it is clearly mentionned in this reference documentation.

Overview of the different modules and objects

Modules

Kameleoon.API.Core

This module contains essential functions for the implementation of front-end based A/B testing variations that won't result in any flickering effect. It is extremely important to use these methods in order to correctly operate the Kameleoon platform and leverage our Anti-Flickering technology. Any Front-End developer working with Kameleoon should be familiar with them.

It also contains several methods dealing with the initialization of the engine, for instance related to privacy laws and legal consent collection.

Kameleoon.API.Goals

This module deals with the triggering of goals and conversion data. For instance, a confirmed purchase with a generated revenue would have to be registered and implemented with this module.

Kameleoon.API.Data

This module mainly contains methods to set custom datas, which are the preferred way to provide additional customer or visit characteristics. Other methods are also related to data management (obtain and write data in Kameleoon cross-domain LocalStorage).

Kameleoon.API.Events

This module allows developers to trigger custom events that can be used in the targeting of your experiments and personalizations. Note that our API also offers standard DOM events which are documented here.

Kameleoon.API.Tracking

This module allows the integration of Kameleoon results with 3rd party tracking & analytics platforms (such as Adobe Omniture).

Kameleoon.API.Products

This module is an entry point to interact with your product catalog. For instance, it can be used to register a product view or purchase, add a product to the cart, obtain a set of automatic product recommendations, or obtain statistics about a given product (how many times it was bought or viewed in the last hour or day).

Kameleoon.API.Experiments

This module provides a collection of entry points to access the current live experiments ran by Kameleoon.

Kameleoon.API.Personalizations

This module provides a collection of entry points to access the current live personalizations ran by Kameleoon.

Kameleoon.API.Variations

This module contains methods to deal with variations.

Kameleoon.API.Segments

This module contains methods to deal with segments and targeting.

Kameleoon.API.Utils

This module contains several helper methods that can be useful for various operations.

Kameleoon.API.Visitor

This module is a shortcut to obtain a reference to the current Visitor object. There is only a single, unique Visitor object within the Activation API.

Kameleoon.API.CurrentVisit

This module is just a shortcut to obtain a reference to the current (in-progress) Visit object. It is the reference to the same object that you would obtain by calling Kameleoon.API.Visitor.visits[Kameleoon.API.Visitor.visits.length - 1].

Objects

Configuration Object

A Configuration object holds global, constant values related to the current configuration of Kameleoon on this site.

Visitor Object

A Visitor object contains data scoped to the visitor, that is not dependent of a given visit. Note that this object contains a list of all the Visit objects related to this visitor.

Visit Object

A Visit object represents a single visit. It contains all the information gathered by Kameleoon, which is updated in real-time. Data can be related to the context of the visit (device used, location...), to the behavior observed during the visit (duration, number of pages viewed...) or to Kameleoon operations (triggered experiments or personalizations).

Device Object

A Device object contains data about the device being used for a given visit.

Geolocation Object

A Geolocation object contains data about the physical location of the visitor for a given visit.

Weather Object

A Weather object contains data about the weather conditions occuring at the time of the visit.

Experiment Object

An Experiment object represents a Kameleoon A/B test. Its main properties are its segment (defining the conditions under which the experiment will be triggered) and the associated variations. Variations contain the JavaScript and CSS code that implement the changes needed to produce the desired end-result.

Personalization Object

A Personalization object represents a Kameleoon personalization action for a given segment. Its main properties are its segment (defining the conditions under which the personalization will be triggered and displayed) and the associated single variation. Technically, the Variation object is the same used by an Experiment. It contains the JavaScript and CSS code that implement the actual displayed personalization action.

ExperimentActivation Object

An ExperimentActivation object represents the activation of an experiment for a particular visit. It represents a loose link to the experiment object, in the sense that since the visit can be an old one, the corresponding experiment can already be stopped. In this case, the experiment common data (name, dateLaunched, targetSegment...) is not injected into the Kameleoon application file. Thus the experiment is not available via the Activation API and the experiment property will be null. However, the ids are always available.

PersonalizationActivation Object

An PersonalizationActivation object represents the activation of an personalization for a particular visit. It represents a loose link to the personalization object, in the sense that since the visit can be an old one, the corresponding personalization can already be stopped. In this case, the personalization common data (name, dateLaunched, targetSegment...) is not injected into the Kameleoon application file. Thus the personalization is not available via the Activation API and the personalization property will be null. However, the ids are always available.

Variation Object

A Variation object represents one of the main components of an Experiment. An A/B test experiment contains a list of variations (if the test contains 1 variation in addition to the original, it is usually called an A/B test, if it has 2 variations, an A/B/C test, and so on). Note that while an Experiment contains a list of variations, a Personalization has a reference and is associated to a single Variation object.

Template Object

A Template object represents an instantiated template. Widget templates can be defined in Kameleoon's Back-Office, and provide an easy way to generate several variations from a common code base, via a convenient interface. In the Activation API, a Template object mainly contains the fields defined in the base template along with their actual instantiated values for the associated variation. Some properties from the base template are also available.

Goal Object

A Goal object represents a given KPI (Key Performance Indicator) that is tracked on the website. Goals are defined via Kameleoon's Back-Office.

Segment Object

A Segment object contains a list of criteria that must be fulfilled for the visit to belong to the segment. Note that on the Kameleoon platform, a Segment contains both "constant" conditions (such as age, location) and "triggering" conditions (such as the number of seconds ellapsed since the page load or since the beginning of the visit, or the total amount of items in the shopping cart).

Product Object

A Product object describes a product in your catalog, with much information attached. Most properties of a Product can be null.

Kameleoon.API.Core

This module contains essential functions for the implementation of front-end based A/B testing variations that won't result in any flickering effect. It is extremely important to use these methods in order to correctly operate the Kameleoon platform and leverage our Anti-Flickering technology. Any Front-End developer working with Kameleoon should be familiar with those.

It also contains several methods dealing with the initialization of the engine, for instance related to privacy laws and legal consent collection.

enableLegalConsent

var agreedButton = Kameleoon.API.Utils.querySelectorAll("#agreed")[0];

Kameleoon.API.Utils.addEventListener(agreedButton, "mousedown", function(event) {
    Kameleoon.API.Core.enableLegalConsent();
});

The enableLegalConsent() method should be called once you have obtained legal consent from the visitor to activate Kameleoon. It triggers the activation of Kameleoon's normal mode. For more information, please refer to this article.

Arguments

disableLegalConsent

var disableButton = Kameleoon.API.Utils.querySelectorAll("#disable")[0];

Kameleoon.API.Utils.addEventListener(disableButton, "mousedown", function(event) {
    Kameleoon.API.Core.disableLegalConsent();
});

The disableLegalConsent() method should be called once you know that the visitor declines the use of Kameleoon. It disables Kameleoon normal operation mode. For more information, please refer to this article.

Arguments

enableSinglePageSupport

if (location.href.indexOf("mySPAWebsitePart") != -1)
{
    Kameleoon.API.Core.enableSinglePageSupport();
}

The enableSinglePageSupport() method triggers a reload of the Kameleoon engine when the active URL changes, even if there is no actual browser page load involved. If your website is a Single Page Application with different URLs but a single initial page load, the use of this method is recommended. Every URL change will then be considered as a new page by Kameleoon. This will enable URL targeting to work, as well as the correct gathering of some information, such as the number of page views.

getConfiguration

var configuration = Kameleoon.API.Core.getConfiguration();

if (configuration.siteCode == "abcde12345")
{
    document.cookie = "MyMainSite=true;";
}
else if (configuration.siteCode == "12345abcdef")
{
    document.cookie = "MySubSite=true;";
}

The getConfiguration() method returns a reference to the Configuration object. This objects holds global, constant values related to the current configuration of Kameleoon on this site.

Return value

load

var href = location.href;

var intervalId = Kameleoon.API.Utils.setInterval(function () {
    if (location.href != href)
    {
        Kameleoon.API.Core.load();
    }
}, 2000);

The load() method initalizes the Kameleoon engine. It is normally called automatically when the Kameleoon application file loads, at each page load. However, sometimes it is useful to call it manually. The example on the right shows for instance how you could implement reloading after each URL change (similar to what the enableSinglePageSupport() method does).

processRedirect

var experiment = Kameleoon.API.Experiments.getByName("RedirectExperiment");

if (experiment.associatedVariation.id == 123456)
{
    Kameleoon.API.Core.processRedirect("https://www.mywebsite.com?variation=A");
}

The processRedirect() method sends the browser to another URL. It is generally used in split A/B experiments. Note: do not write code such as window.location.href = redirectionURL; for your split experiments. Always use this method as it takes care of some important details (like ensuring proper tracking) in the background.

Arguments

runWhenConditionTrue

Kameleoon.API.Core.runWhenConditionTrue(function(){
    return typeof jQuery != "undefined"; 
 }, function(){
    jQuery("#bloc-2345").text("Mon nouveau texte");
 }, 200);

The runWhenConditionTrue() method will execute a JavaScript function (callback) as soon as the conditionFunction function returns true. It periodically calls the conditionFunction with a polling mechanism, so its use can result in flickering. For this reason, we strongly recommend the use of the next method, runWhenElementPresent(), over the use of this method. See the description of runWhenElementPresent() for more details.

Arguments

runWhenElementPresent

// With mutation observers
Kameleoon.API.Core.runWhenElementPresent("#bloc-2345", function(elements) {
    elements[0].innerText = "My new Text";
});

// Without mutation observers
Kameleoon.API.Core.runWhenElementPresent("#MyPopup.showed", function(elements) {
    Kameleoon.API.Events.trigger("popup displayed");
}, 200);

The runWhenElementPresent() method will execute a JavaScript function (callback) as soon as a specific element appears in the DOM. Technically, it uses Mutation Observers underneath, and is the core method enabling the use of our Anti-Flickering technology. Thus when implementing front-end A/B experiments, you should try to determine which are the main element you need to act on for your variation. Then always call runWhenElementPresent() with the given element as first argument and the variation implementation code in a callback as the second argument. Our system will then ensure all your modification code runs as soon as the desired HTML element appears in the DOM, before any display refresh cycle is initiated by the browser.

In case your code needs to act on several elements, which is often the case, it is better to call runWhenElementPresent() several times with different arguments rather than trying to guess which element will appear last and use runWhenElementPresent() once with this element. If called a single time, flickering can appear if a refresh cycle happens between the apparition of a "first" element that needs to be visually modified and the "last" one (given as argument to the method).

Important note: a third argument, pollingInterval, can optionally be given to this method. If present, mutation observers / anti-flickering will be disabled and our previous, legacy mechanism relying on pollers will be used instead (with the given polling interval). Since it can result in noticable flickering, we do not recommend providing this argument except in very special cases (complex selector queries that would have a huge impact on the CPU browser usage, for instance).

Arguments

Kameleoon.API.Goals

This module deals with the triggering of goals and conversion data. For instance, a confirmed purchase with a generated revenue would have to be registered and implemented with this module.

cancelConversion

var buttons = Kameleoon.API.Utils.querySelectorAll(".btnRemoveFromCart");

buttons.forEach(function (button) {
    Kameleoon.API.Utils.addEventListener(button, "mousedown", function(event) {
        Kameleoon.API.Goals.cancelConversion(event.target.id);
    });
});

The cancelConversion() method allows you to cancel a conversion that was previously triggered during the same visit. It cannot cancel conversions registered in previous visits.

Arguments

processConversion

var buyButton = Kameleoon.API.Utils.querySelectorAll("#buyButton")[0];

Kameleoon.API.Utils.addEventListener(buyButton, "mousedown", function() {
    Kameleoon.API.Goals.processConversion("buy", 19.99);
});

The processConversion() method allows you to trigger a conversion.

Arguments

Kameleoon.API.Data

This module contains mainly methods to set custom datas, which are the preferred way to provide additional customer or visit characteristics. Other methods are also related to data management (obtain and write data in Kameleoon cross-domain LocalStorage).

checkInterest

var imagesToCheck = [
    "http://developers.kameleoon.com/logo.png",
    "http://developers.kameleoon.com/background.jpg",
    "http://developers.kameleoon.com/icon-api.png"
];

Kameleoon.API.Data.checkInterest(imagesToCheck, "Interest Kameleooon", function (isFound) {
    if (isFound)
    {
        Kameleoon.API.Events.trigger("My Custom Event");
    }
});

The checkInterest() method allows you to manually check if some images (with provided URLs) are present in the visitor's browser cache, which means their hosting site was visited recently. It also automatically updates an associated interest (passed as argument) with the result of the check.

Arguments

readLocalData

var userId = Kameleoon.API.Data.readLocalData("myUserId");

if (userId)
{
    Kameleoon.API.Data.retrieveDataFromRemoteSource(userId, function (data) {
        console.log(data.returningVisitor);
    });
}

The readLocalData() method allows you to read local data previously stored on the visitor's web browser via the writeLocalData() method. Underneath, our engine will read this data on our cross-domain Local Storage. You don't have to worry about the usual limitations of the Local Storage - our implementation removes them.

Arguments

Return value

performRemoteSynchronization

Kameleoon.API.Data.performRemoteSynchronization("customDataName", "customDataValue", false);

The performRemoteSynchronization() method triggers a Server Synchronization Call (SSC). It consists in a call to our Data API that retrieves a list of visits stored on our backend servers for this visitor. It then writes all these visits in the LocalStorage and ensures that this data is properly accessible via the Activation API or usable for targeting purposes. This method is generally used for cross-device history reconciliation or ITP purposes on Safari and is triggered automatically in those contexts, so it should normally not be called manually.

Arguments

resetCustomData

Kameleoon.API.Data.resetCustomData("MyCustomDataName");

The resetCustomData() method allows you to reset a custom data.

Arguments

retrieveDataFromRemoteSource

if (location.href.indexOf("loginPage") != -1)
{
    Kameleoon.API.Core.runWhenConditionTrue(function () {
        return typeof dataLayer != null;
    }, function () {
        dataLayer.forEach(function (map) {
            if (map.userId)
            {
                Kameleoon.API.Data.retrieveDataFromRemoteSource(userId, function(data) {
                    Kameleoon.API.Data.setCustomData("known_user", data.knownUser);
                });
            }
        });
    }, 200);
}

The retrieveDataFromRemoteSource() method allows you to retrieve data (according to a key passed as argument) stored on a remote Kameleoon server. Usually data will be stored on our remote servers via the use of our Data API. This method, along with the availability of our highly scalable servers for this purpose, provides a convenient way to quickly store massive amounts of data that can be later retrieved for each of your visitors / users.

Note that since a server call is required, this mechanism is asynchronous, and you must pass a callback as argument to the method.

Arguments

setCustomData

Kameleoon.API.Data.setCustomData("myCustomDataName", "myNewValue");

The setCustomData() method allows you to set a custom data value.

Arguments

writeLocalData

Kameleoon.API.Data.writeLocalData("myData", "myDataValue", true);

The writeLocalData() method allows you to write local data on the visitor's web browser and later retrieve it via the readLocalData() method. Underneath, our engine will write this data on our cross-domain Local Storage. You don't have to worry about the usual limitations of the Local Storage - our implementation removes them. The data passed will be available immediately for retrieval (in the same browser tab), as it is cached in RAM, but please note that the actual associated write happens asynchronously.

Arguments

Kameleoon.API.Events

This module allows developers to trigger custom events that can be used in the targeting of your experiments and personalizations. Note that our API also offers standard DOM events which are documented here.

trigger

Kameleoon.API.Events.trigger("myTriggerEventName");

The trigger() method allows you to trigger a custom event. Custom events are used in targeting segments.

Arguments

Kameleoon.API.Tracking

This module allows the integration of Kameleoon results with 3rd party tracking & analytics platform (such as Adobe Omniture).

processOmniture

function s_doPlugins(s)
{
    /* Kameleoon Integration */

    if (window.Kameleoon)
    {
        Kameleoon.API.Tracking.processOmniture(s);
    }
    window.kameleoonOmnitureCallSent = true;

    // Add your other doPlugins code below
}

s.doPlugins = s_doPlugins;

We provide a native integration with Adobe Omniture if you wish to track results of your experiments and personalizations on Omniture. To use this bridge, you must modify the file containing the s_doPlugins() code as shown in the example on the right. Two important things need to be done inside the s_doPlugins() function:

• add a mandatory call to the Kameleoon.API.Tracking.processOmniture() method;
• set a global variable, window.kameleoonOmnitureCallSent, to true so that we can know when a first tracking call has been sent. You can also set this variable on your own somewhere else if you wish, but it is recommended to set it on the s_doPlugins() code.

With our integration, Kameleoon will try to minimize the number of overall Omniture hits sent (which is important, since the number of hits directly affects Omniture pricing). It will only send an additional hit if an experiment or personalization triggers after the main Omniture call has already been processed and sent. This can happen either if Kameleoon loads after the Omniture code (not recommended and should not be the case, but possible since Kameleoon's application file usually loads asynchronously) OR if there is an experiment or personalization triggering "late" (ie, not at page load, but for instance after a click on a button).

In the normal case, where Kameleoon loads first and all active experiments can be known at page load, all the additional data is sent along the global, standard Omniture tracking call.

Arguments

Kameleoon.API.Products

This module is an entry point to interact with your product catalog. For instance, it can be used to register a product view or purchase, add a product to the cart, obtain a set of automatic product recommendations, or obtain statistics about a given product (how many times it was bought or viewed in the last hour or day).

obtainRecommendedProducts

Kameleoon.API.Products.obtainRecommendedProducts("popular", {
    limit: 6,
    format: "object",
    categoryID: 123456
}, function(result) {
    if (result.length > 0)
    {
        var recommendationAction = Kameleoon.API.Utils.querySelectorAll("#recommendationAction");
        result.forEach(function (productData) {
            var product = document.createElement("div");
            product.className = "productItem";
            product.innerHTML = "<a href='" + productData.url + "'>" +
                "<img src='" + productData.mainImageURL + "' alt='" + productData.name + "'>" +
            "</a>";
            recommendationAction[0].appendChild(product);
        });
    }
});

The obtainRecommendedProducts() method will retrieve a list of recommended products as computed by the specified algorithm. They are retrieved by an asynchronous server call.

Arguments

trackAddToCart

var buyButton = Kameleoon.API.Utils.querySelectorAll("#buyButton")[0];

Kameleoon.API.Utils.addEventListener(buyButton, "mousedown", function() {
    Kameleoon.API.Products.trackAddToCart("myProductId", 19.99, 1);
});

The trackAddToCart() method should be called when a product is added to the visitor's shopping cart.

Arguments

trackCategoryView

if (location.href.indexOf("productPage") != -1)
{
    Kameleoon.API.Core.runWhenConditionTrue(function () {
        return typeof dataLayer != null;
    }, function () {
        dataLayer.forEach(function (map) {
            if (map.categoryID)
            {
                Kameleoon.API.Products.trackCategoryView(5);
            }
        });
    }, 200);
}

The trackCategoryView() method should be called every time a category page is viewed by the visitor during his browsing session.

Arguments

trackProductView

Kameleoon.API.Products.trackProductView("myPoductID", {
    "name": "productName",
    "categoryID": 13,
    "category": "productCategory",
    "mainImageURL": "https://www.mywebsite/productImage.jpg",
    "price": 19.99,
    "available": true,
    "brand": "productBrand",
    "child": false,
    "gender": "F",
    "sizes": ["S", "M"],
    "type": "shirt",
    "feature": "productFeature",
    "sku": "productSKU",
    "description": "This is a short description",
    "rating": 4,
    "tags": ["shirt", "red"]
});

The trackProductView() method should be called every time a product is viewed by the visitor during his browsing session. Note that by ensuring this call is properly made, Kameleoon will be able to build a copy of your product catalog without the need for an explicit integration via a XML feed for instance. This can greatly facilitate the setup and launch of a product recommendations project, since all the integration work can take place only on the front-end.

Arguments

trackTransaction

Kameleoon.API.Products.trackTransaction([
    {
        "productID": "myProductID1",
        "quantity": 4
    },
    {
        "productID": "myProductID4564",
        "quantity": 1
    }
]);

The trackTransaction() method should be called when a purchase / transaction is actually carried out.

Arguments

Kameleoon.API.Experiments

This module provides a collection of entry points to access the current live experiments ran by Kameleoon.

assignVariation

var experimentID = 2468,
    variationID;

if (Kameleoon.API.CurrentVisit.device.type == "Desktop")
{
    variationID = 123456;
}
else if (Kameleoon.API.CurrentVisit.device.type == "Tablet")
{
    variationID = 654321;
}
else
{
    variationID = 987654;
}

Kameleoon.API.Experiments.assignVariation(experimentID, variationID);

This method forces the association of a given variation for an experiment, instead of relying on the standard allocation algorithm (which usually picks a variation at random according to the configured deviation). Note that this method can be called before the experiment is actually triggered. In this case, the variation will be "pre-allocated", which means that if the experiment later triggered in the current visit (or even a future one), this variation will be the one chosen. If the experiment was already previously triggered, a variation is normally already associated with the experiment. You should set the override argument to true if you want to replace it with the new one - else the method won't do anything.

Arguments

block

// The experiment will be blocked for the current page
Kameleoon.API.Experiments.block(12345);

// The experiment will be blocked for the whole visit
Kameleoon.API.Experiments.block(54321, true);

This method will block an experiment. Further triggering / activation of this experiment will not be possible, even explicitely via the use of methods such as trigger(). The block will be set for the current page (until the next Kameleoon.API.Core.load()) by default. It can be set for the whole visit by setting the visit argument to true.

Arguments

getAll

Kameleoon.API.Experiments.getAll().forEach(function (experiment) {
    if (experiment.id == 123456 && experiment.active)
    {
        console.log(experiment.name);
    }
});

Returns the list of experiments currently live in your website (ie, the experiments that are not in draft, paused or stopped, but actually running).

Return value

getActive

if (Kameleoon.API.Experiments.getActive().length == 0)
{
    Kameleoon.API.Events.trigger("No Experiments Events");
}

Returns the list of active experiments for the current visit and page. An active experiment means that its variation code has been executed in the current browser context (page). If the experiment was activated on a different URL but is not active in the current URL, it won't be returned by this method. You can however retrieve it via the getActivatedInVisit() method.

Return value

getById

var experiment = Kameleoon.API.Experiments.getById(123456);

if (experiment && experiment.active)
{
    console.log(experiment.name);
}

Returns the experiment with a specific id.

Arguments

Return value

getByName

var experiment = Kameleoon.API.Experiments.getByName("MyExperimentName");

if (experiment && experiment.active)
{
    console.log(experiment.id);
}

Returns the experiment with a specific name.

Arguments

Return value

getTriggeredInVisit

Kameleoon.API.Experiments.getTriggeredInVisit().forEach(function (experiment) {
    if (experiment.id == 123456)
    {
        console.log(experiment.name);
    }
});

Returns the list of experiments that were triggered in the current visit.

Return value

getActivatedInVisit

Kameleoon.API.Experiments.getActivatedInVisit().forEach(function (experiment) {
    if (experiment.id == 123456)
    {
        console.log(experiment.name);
    }
});

Returns the list of experiments that were activated in the current visit.

Return value

trigger

let experimentID = 123456;
Kameleoon.API.Experiments.trigger(experimentID, true);

This method forces the trigger of a given experiment, independently of the targeting segment. In practice, this will have the same effect as if conditions for the targeting were fulfilled. Note that this triggers the experiment, but not necessarily activates it.

Arguments

Kameleoon.API.Personalizations

This module provides a collection of entry points to access the current live personalizations ran by Kameleoon.

disable

let personalizationID = 12345;
Kameleoon.API.Personalizations.disable(personalizationID);

The disable() method should be used to mark a personalization as disabled. For instance, if you create a personalization that will display a pop-in or similar visual artefact that can be closed, if the user actually closes the pop-in by clicking on the close button, the underlying personalization should be marked disabled, as it is no longer active. Note that pop-ins automatically generated by Kameleoon (ie, not via custom JavaScript code, but via our interface) already implement a call to this method on a click on the close button.

Arguments

getActive

if (Kameleoon.API.Personalizations.getActive().length == 0)
{
    Kameleoon.API.Events.trigger("No Personalizations Events");
}

Returns the list of active personalizations for the current visit and page. An active personalization means that its variation code has been executed in the current browser context (page) and that the associated displayed action is still visible on the page. If the personalization was triggered on a different URL but is not active in the current URL, it won't be return by this method. Similarly a personalization displaying a pop-in that was already closed won't be returned. You can however retrieve such personalizations via the getTriggeredInVisit() method.

Return value

getAll

Kameleoon.API.Personalizations.getAll().forEach(function (personalization) {
    if (personalization.id == 123456 && personalization.active)
    {
        console.log(personalization.name);
    }
});

Returns the list of personalizations currently live in your website (ie, the personalizations that are not in draft, paused or stopped, but actually running).

Return value

getById

var personalization = Kameleoon.API.Personalizations.getById(123456);

if (personalization && personalization.active)
{
    console.log(personalization.name);
}

Returns the personalization with a specific id.

Arguments

Return value

getByName

var personalization = Kameleoon.API.Personalizations.getByName("MyPersonalizationName");

if (personalization && personalization.active)
{
    console.log(personalization.id);
}

Returns the personalization with a specific name.

Arguments

Return value

getTriggeredInVisit

Kameleoon.API.Personalizations.getTriggeredInVisit().forEach(function (personalization) {
    if (personalization.id == 123456)
    {
        console.log(personalization.name);
    }
});

Returns the list of experiments that were triggered in the current visit.

Return value

getActivatedInVisit

Kameleoon.API.Personalizations.getActivatedInVisit().forEach(function (personalization) {
    if (personalization.id == 123456)
    {
        console.log(personalization.name);
    }
});

Returns the list of experiments that were activated in the current visit.

Return value

trigger

This method forces the trigger of a given personalization, independently of the targeting segment. In practice, this will have the same effect as if conditions for the targeting were fulfilled. Note that this triggers the personalization, but not necessarily activates it.

Arguments

Kameleoon.API.Variations

This module contains methods to deal with variations.

execute

if (Kameleoon.API.Utils.querySelectorAll("#KameleoonPopin").length == 0)
{
    Kameleoon.API.Experiments.getById(123456).variations.forEach(function (variation) {
        if (variation.name == "MyVariation")
        {
            Kameleoon.API.Variations.execute(variation.id);
        }
    });
}

Execute JS code and apply CSS for the variation corresponding to the ID passed as argument.

Kameleoon.API.Segments

This module contains methods to deal with segments and targeting.

getAll

let segments = Kameleoon.API.Segments.getAll();

Returns the list of segments currently live in your website: the ones associated with experiments, personalizations, and the ones marked for tracking in Audiences.

Return value

getById

let segment = Kameleoon.API.Segments.getById(123456);

Returns the segment with a specific id.

Arguments

Return value

getByName

let segment = Kameleoon.API.Segments.getByName("My segment");

Returns the segment with a specific name.

Arguments

Return value

reevaluate

Kameleoon.API.Utils.addEventListener(document.body, "mouseleave", function (event) {
    if (event.clientY < 0) {
        Kameleoon.API.Segments.reevaluate(123456);
    }
});

Forces a re-evaluation of the given segment. Targeting conditions are usually evaluated as soon as it is possible (mostly at page load) and can be set to true, false, or undefined (still waiting). Calling this method will put all the targeting conditions to the undefined state, erasing their previous state. They will then be re-evaluted immediately, as if Kameleoon engine was initialized again at page load.

Arguments

trigger

Kameleoon.API.Segments.trigger(12345);

Forces a re-evaluation of the given segment. Targeting conditions are usually evaluated as soon as it is possible (mostly at page load) and can be set to true, false, or undefined (still waiting). Calling this method will put all the targeting conditions to the undefined state, erasing their previous state. They will then be re-evaluted immediately, as if Kameleoon engine was initialized again at page load.

Arguments

Kameleoon.API.Utils

This module contains several helper methods that can be useful for various operations.

addEventListener

var popin = document.createElement("div");
popin.id = "kameleoonPopin";
popin.innerHTML = "<img src='https://www.mywebsite.com/myImage.jpg'/>";
document.body.appendChild(popin);

Kameleoon.API.Utils.addEventListener(popin, "mousedown", function(event) {
    document.body.removeChild(popin);
});

The addEventListener() method attaches an event handler to the specified element.

Arguments

addUniversalClickListener

let btn = document.querySelector("#MyButton");

Kameleoon.API.Utils.addUniversalClickListener(btn, function (event) {
    let goalID = 1234;
    Kameleoon.API.Goals.processConversion(goalID);
});

The addUniversalClickListener() method attaches a click handler to the specified element. The interest of this method is that it will listen both for mouse clicks (for a desktop computer) and for touchdown events (in mobile phones and tablets). Technically, since touchdown events are not part of the specification, we consider a touchdown occured on mobile if a touchstart event was received, followed by a touchend event without a touchmove event between.

Arguments

clearInterval

var myInterval = Kameleoon.API.Utils.setInterval(function() {
    if (window.dataLayer != null)
    {
        Kameleoon.API.Utils.clearInterval(myInterval);
    }
}, 1000);

The clearInterval() method clears a timer set with the setInterval() method.

Arguments

clearTimeout

var myTimeout = Kameleoon.API.Utils.setTimeout(function () {
    var popin = document.createElement("div");
    popin.id = "kameleoonPopin";
    popin.innerHTML = "<img src='https://www.mywebsite.com/myImage.jpg'/>";
    document.body.appendChild(popin);
}, 5000);


Kameleoon.API.Utils.addEventListener(document.body, "mousedown", function() {
    Kameleoon.API.Utils.clearTimeout(myTimeout);
});

The clearTimeout() method clears a timer set with the setTimeout() method.

Arguments

computeHash

var emailId = Kameleoon.API.Utils.createHash("myemail@mail.com");
Kameleoon.API.Data.setCustomData("VisitorEmail", emailId);

The computeHash() method computes a hash from a given string. This is useful if you want to work on unique data, without having to directly manipulate the original data (especially personal data, for legal reasons).

Arguments

Return value

getURLParameters

var parameters = Kameleoon.API.Utils.getUrlParameters();

if (parameters.productID != null)
{
    Kameleoon.API.Events.trigger("ProductPage");
}

The getURLParameters() method parses the current URL and returns all parameters found. This method works with both search (?) and hash (#) parameters.

Return value

performRequest

Kameleoon.API.Utils.performRequest(
    "https://www.my_web_server_url.com",
    function()
    {
        if (this.readyState == 4 && this.status == 200)
        {
            eval(this.responseText);
        }
    },
    function()
    {
        console.log("Request cancelled");
    },
    2000
);

The performRequest() method can be used to initiate a call with a remote web server.

Arguments

querySelectorAll

var foundElements = Kameleoon.API.Utils.querySelectorAll(".kameleoonClassName");

foundElements.forEach(function (element) {
    element.style.display = "none";
});

The querySelectorAll() method returns all elements in the document that match a specified CSS selector(s), as a static NodeList object.

Arguments

Return value

setInterval

var countdown = 10;
var timer = document.createElement("div");
timer.innerHTML = countdown.toString();
document.body.appendChild(timer);

var myInterval = Kameleoon.API.Utils.setInterval(function() {
    countdown--;
    timer.innerHTML = countdown.toString();

    if (countdown == 0)
    {
        Kameleoon.API.Utils.clearInterval(myInterval);
    }
}, 1000);

The setInterval() method calls a function or evaluates an expression at the specified interval (in milliseconds).

Arguments

Return value

setTimeout

var myTimeout = Kameleoon.API.Utils.setTimeout(function () {
    Kameleoon.API.Events.Trigger("5 seconds elapsed");
}, 5000);

The setTimeout() method calls a function or evaluates an expression after a specified number of milliseconds.

Arguments

Return value

Kameleoon.API.Visitor

This module is a shortcut to obtain a reference to the current Visitor object. There is only a single, unique Visitor object within the Activation API.

Kameleoon.API.CurrentVisit

This module is just a shortcut to obtain a reference to the current (in-progress) Visit object. It is the reference to the same object that you would obtain by calling Kameleoon.API.Visitor.visits[Kameleoon.API.Visitor.visits.length - 1].

Configuration

A Configuration object holds global, constant values related to the current configuration of Kameleoon on this site.

Properties

Visitor

A Visitor object contains data scoped to the visitor, that is not dependent of a given visit. Note that this object contains a list of all the Visit objects related to this visitor.

Properties

Visit

A Visit object represents a single visit. It contains all the information gathered by Kameleoon, which is updated in real-time. Data can be related to the context of the visit (device used, location...), to the behavior observed during the visit (duration, number of pages viewed...) or to Kameleoon operations (triggered experiments or personalizations).

Properties

Device

A Device object contains data about the device being used for a given visit.

Properties

Geolocation

A Geolocation object contains data about the physical location of the visitor for a given visit.

Properties

Weather

A Weather object contains data about the weather conditions occuring at the time of the visit.

Properties

Experiment

An Experiment object represents a Kameleoon A/B test. Its main properties are its segment (defining the conditions under which the experiment will be triggered) and the associated variations. Variations contain the JavaScript and CSS code that implement the changes needed to produce the desired end-result.

Properties

Personalization

A Personalization object represents a Kameleoon personalization action for a given segment. Its main properties are its segment (defining the conditions under which the personalization will be triggered and displayed) and the associated single variation. Technically, the Variation object is the same used by an Experiment. It contains the JavaScript and CSS code that implement the actual displayed personalization action.

Properties

ExperimentActivation

An ExperimentActivation object represents the activation of an experiment for a particular visit. It represents a loose link to the experiment object, in the sense that since the visit can be an old one, the corresponding experiment can already be stopped. In this case, the experiment common data (name, dateLaunched, targetSegment...) is not injected into the Kameleoon application file. Thus the experiment is not available via the Activation API and the experiment property will be null. However, the ids are always available.

Properties

PersonalizationActivation

An PersonalizationActivation object represents the activation of an personalization for a particular visit. It represents a loose link to the personalization object, in the sense that since the visit can be an old one, the corresponding personalization can already be stopped. In this case, the personalization common data (name, dateLaunched, targetSegment...) is not injected into the Kameleoon application file. Thus the personalization is not available via the Activation API and the personalization property will be null. However, the ids are always available.

Properties

Variation

A Variation object represents one of the main components of an Experiment. An A/B test experiment contains a list of variations (if the test contains 1 variation in addition to the original, it is usually called an A/B test, if it has 2 variations, an A/B/C test, and so on). Note that while an Experiment contains a list of variations, a Personalization is associated to a single Variation object.

Properties

Template

A Template object represents an instantiated template. Widget templates can be defined in Kameleoon's Back-Office, and provide an easy way to generate several variations from a common code base, via a convenient interface. In the Activation API, a Template object mainly contains the fields defined in the base template along with their actual instantiated values for the associated variation. Some properties from the base template are also available.

Properties

Goal

A Goal object represents a given KPI (Key Performance Indicator) that is tracked on the website. Goals are defined via Kameleoon's Back-Office.

Properties

Segment

A Segment object contains a list of criteria that must be fulfilled for the visit to belong to the segment. Note that on the Kameleoon platform, a Segment contains both "constant" conditions (such as age, location) and "triggering" conditions (such as the number of seconds ellapsed since the load of the page or the visit, or the total amount of items in the shopping cart).

Properties

Product

A Product object describes a product in your catalog, with many attached information. However, most of the properties described here are optional and can be null.

Properties