Activation API events

In addition to the usual methods and data structures provided by Kameleoon's Activation API, some custom DOM events are also fired by our JavaScript engine. They make excellent entry points to customize Kameleoon's behavior and extend our platform. For instance, you can listen to the Kameleoon::ExperimentTriggered event to be notified in your own JavaScript code whenever a new experiment is triggered.

A full list of currently implemented events is provided below. If you think a useful event is absent from our current Activation API, do not hesitate to contact our teams to ask for an improvement. It's easy for our developers to add new events which can suit your needs.

note

Since there is only one single thread of execution in a JavaScript environment, events triggered in a continuous synchronous block of execution are actually received at the same time. Ie, your callback listeners will run after the whole Kameleoon code block has finished executing, not at the moment Kameleoon code actually triggers the event. For instance, Kameleoon::Loaded and Kameleoon::Started can be received simultaneously if local storage load is implemented synchronously (which is usually the case, except in a cross domain setup when the current URL is not on the main domain). Kameleoon::Started and Kameleoon::ExperimentTriggered are also simultaneous for experiments where targeting can be evaluated immediately.

List of events

Kameleoon::Loaded

window.addEventListener('Kameleoon::Loaded', function (event) {
  var loadTime = event.detail.loadTime;
  var timeout = event.detail.timeout;
});

This event is fired when the Kameleoon application file has just finished loading and Kameleoon engine code is available for execution in the browser. The event is fired at the very beginning of Kameleoon's setup. Further events (see below) are fired as various steps are reached in the initialization process.

Data available in the event

Name	Type	Description
loadTime	Number	Time of the completed loading of the Kameleoon application file (UTC format - ms since 1st January, 1970).
timeout	Boolean	true if a timeout occured during the (asynchronous) load of the Kameleoon application file.

Kameleoon::Aborted

window.addEventListener('Kameleoon::Aborted', function (event) {
  var reason = event.detail.reason;
});

This event is fired when the Kameleoon engine stopped its execution on the current page. If this event is fired, it means that Kameleoon is not active, as if Kameleoon was not installed into your site (for current visitor and page). The reason of the abortion is given in the event, and can be one of those:

• BROWSER: the browser used is not supported by Kameleoon engine (usually an old / exotic browser is being used);
• PRERENDER: this is actually a prerender request (Chrome uses such requests for optimization purposes) and not an actual webpage being viewed by an human. In those cases, Kameleoon does not run as it would produce false statistics;
• STORAGE: some technical prerequisites for normal operations of Kameleoon cannot be met. Usually, it means it was impossible to write in the Local Storage;
• TIMEOUT: the Kameleoon application file loading time exceeded allowed amount, and Kameleoon was configured to abort in such cases;
• DISABLED: Kameleoon was disabled via the back-office application. When this is used, all loads of Kameleoon on the front-end side immediately abort;
• PARAMETER: A special parameter is present in the current URL, which causes Kameleoon to stop execution (usually for debugging or verification purposes). The parameter is (#|?|&)kameleoonDisabled=true;
• SCRIPT: A custom abort script has been implemented and returned true for the current load of Kameleoon.

Data available in the event

Name	Type	Description
reason	String	Reason / cause of the abortion.

Kameleoon::Started

window.addEventListener('Kameleoon::Started', function (event) {
  var newVisitor = event.detail.newVisitorCode;
});

This event is fired when the Kameleoon engine has reached the end of its main initialization. At this stage, local storage data has been loaded by the engine, and execution of the global script code, custom data acquisition code, and of any delayed commands via the Command Queue has been performed. Just after this event, Kameleoon activation and tracking loops are started. This essentially means that experiments and personalizations will get triggered (if their corresponding targeting segments conditions are fulfilled), and data collection and tracking starts.

Kameleoon's Activation API methods can be called. Kameleoon.API is also already readable, although some information are not yet available (such as geolocation data, which is obtained at the return of a further asynchronous call). Note that you can know if a new visitorCode was generated during initialization via a boolean present on the event data.

Data available in the event

Name	Type	Description
newVisitorCode	Boolean	true if a new (random) visitorCode has been generated for this visitor (unknown / new visitor for Kameleoon), else false.

Kameleoon::DataGathered

window.addEventListener('Kameleoon::DataGathered', function (event) {
  // At this point, we're guaranteed that the object will be present and correct.
  var currentLocation = Kameleoon.API.CurrentVisit.geolocation;
});

This event is fired when Kameleoon engine has gathered all the data it intends to track. Since many collected data result in remote calls or other asynchronous methods, this happens when all those calls and methods actually returned.

When this event is fired, the Activation API is fully usable. All fields on the API are present, with their correct values.

Note that many remote calls are only performed at the beginning of a visit, so usually this event is fired quite late on the first page view and almost immediately on subsequent page views. While reading out data from the Activation API as soon as Kameleoon is loaded may work (and indeed will work most of the times on non-first page views), there is no guarantee that the data will always be present or accurate. Listening on this event before performing read operations on the Activation API (especially to read visit data such as geolocation, weather...) is thus highly recommended.

Kameleoon::RemoteSynchronizationPerformed

window.addEventListener('Kameleoon::RemoteSynchronizationPerformed', function (event) {
  var allVisits = event.detail.visits;
});

This event is fired when the Kameleoon engine just completed a SSC (Server Synchronization Call) that was initiated by the Kameleoon.API.Data.performRemoteSynchronization() method. This usually happens in the context of cross-device history reconciliation, Intelligent Tracking Prevention or custom data updates. Read more about SSCs here.

Data available in the event

Name	Type	Description
visits	Array	List of Visit objects corresponding to this visitor, returned by the Data API.
currentVisitOnly	Boolean	true if Kameleoon.API.Data.performRemoteSynchronization() was called with the currentVisitOnly argument set to true, else false.

Kameleoon::LegalConsentUpdated

window.addEventListener('Kameleoon::LegalConsentUpdated', function (event) {
  var legalConsentUpdate = event.detail.legalConsentUpdate;
});

This event is fired everytime a change is registered in the legal consent status for the current visitor. It can be either an acceptance (Kameleoon.API.Core.enableLegalConsent()) or a denial (Kameleoon.API.Core.disableLegalConsent()), for either the AB Testing or Personalization module (or both). Note that the updated (current) status can be obtained via Kameleoon.API.Visitor.experimentLegalConsent / Kameleoon.API.Visitor.personalizationLegalConsent, and the update itself is available via the event object.

Data available in the event

Name	Type	Description
legalConsentUpdate	Object	Update that was just processed. It follows the format {"AB_TESTING": true|false, "PERSONALIZATION": true|false}. So this could be equal to {"AB_TESTING": false} if we just registered a denial only for the AB Testing module, or to {"AB_TESTING": true, "PERSONALIZATION": true} if an acceptance occured for both modules.

Kameleoon::ExperimentTriggered

window.addEventListener('Kameleoon::ExperimentTriggered', function (event) {
  var experiment = event.detail.experiment;
  var experimentId = experiment.id;
});

This event is fired whenever a new experiment is triggered (ie, when the visitor matches the target segment of the experiment). As an experiment can be associated with extra options (such as exclusion of a percentage of traffic or capping), it is possible that the visitor will trigger the experiment but will not activate it (see next event). Note that if the experiment triggers on several pages, the event will be fired several times during the session, not just the first time.

Data available in the event

Name	Type	Description
experiment	Object	Experiment object

Kameleoon::ExperimentActivated

window.addEventListener('Kameleoon::ExperimentActivated', function (event) {
  var experiment = event.detail.experiment;
  var experimentId = experiment.id;
  var associatedVariationId = experiment.associatedVariation.id;
});

This event is fired whenever a new experiment is activated (ie, when the visitor will actually be counted towards the experiment results). An experiment is considered activated when it is both triggered (previous event) when the visitor matches the target segment, and all exposition conditions are also fulfilled. Note that if the experiment is activated on several pages, the event will be fired several times during the session, not just the first time.

Data available in the event

Name	Type	Description
experiment	Object	Experiment object

Kameleoon::PersonalizationTriggered

window.addEventListener('Kameleoon::PersonalizationTriggered', function (event) {
  var personalization = event.detail.personalization;
  var personalizationId = personalization.id;
});

This event is fired whenever a new personalization is triggered (ie, when the visitor matches the target segment of the personalization). As a personalization can be associated with extra exposition options, such as capping, it is possible that the actual personalization action does not take place (banner or popin not displayed, for instance). In this case, the personalization does not activate (see next event). Also note that if the personalization triggers on several pages, the event will be fired several times during the session, not just the first time.

Data available in the event

Name	Type	Description
personalization	Object	Personalization object

Kameleoon::PersonalizationActivated

window.addEventListener('Kameleoon::PersonalizationActivated', function (event) {
  var personalization = event.detail.personalization;
  var personalizationId = personalization.id;
  var associatedVariationId = personalization.associatedVariation.id;
});

This event is fired whenever a new personalization is activated (ie, when the personalization is actually displayed on the page). A personalization is considered activated when it is both triggered (previous event) when the visitor matches the target segment, and all exposition conditions are also fulfilled. Note that if the personalization is activated on several pages, the event will be fired several times during the session, not just the first time.

Data available in the event

Name	Type	Description
personalization	Object	Personalization object

Kameleoon::CustomDataSet

window.addEventListener('Kameleoon::CustomDataSet', function (event) {
  var customDataName = event.detail.name;
  var customDataValue = event.detail.value;
});

This event is fired whenever a custom data is set (when its value is provided). It will fire no matter what acquisition method was used (Data Layer integration, Activation API, Data API or Custom JS code).

Data available in the event

Name	Type	Description
name	String	Name of the custom data.
value	Any	Value of the custom data. Its type depends on the defined type of the custom data.

Kameleoon::ConversionTriggered

window.addEventListener('Kameleoon::ConversionTriggered', function (event) {
  var goal = event.detail.goal;
});

This event is fired whenever a conversion is triggered (ie, when a goal has been reached).

Data available in the event

Name	Type	Description
goal	Object	Goal object

Kameleoon::SegmentTriggered

window.addEventListener('Kameleoon::SegmentTriggered', function (event) {
  var segment = event.detail.segment;
});

This event is fired whenever an active segment is triggered (ie, when a visitor matches all the conditions of a targeting segment). A segment is considered active if it is associated to a currently running experiment or personalization, or if it is used in the Audiences tool. All other segments defined in Kameleoon are considered inactive.

Data available in the event

Name	Type	Description
segment	Object	Segment object

Kameleoon::ConversionScoreComputed

window.addEventListener('Kameleoon::ConversionScoreComputed', function (event) {
  var kcs = event.detail.kcs;
  var segmentId = event.detail.targetSegment.id;
});

This event is fired whenever a segment defined as a key moment is triggered. At this point, a KCS (Kameleoon Conversion Score) is computed by our machine learning algorithms and made available.

Data available in the event

Name	Type	Description
kcs	Number	KCS (Kameleoon Conversion Score), an integer from 0 to 100.
targetSegment	Object	Segment object corresponding to the key moment when the KCS is computed.