Activation API events

Reference for custom DOM events fired by the Kameleoon JavaScript engine, including experiment, personalization, and conversion lifecycle events.

In addition to the methods and data structures provided by the Activation API, the JavaScript engine fires custom DOM events. These events serve as excellent entry points to customize Kameleoon’s behavior and extend the platform. For example, listen for the Kameleoon::ExperimentTriggered event to receive notification when an experiment triggers.

The following list details the currently implemented events. If the current Activation API lacks a required event, contact technical support to request an improvement. New events can be added to suit specific requirements.

Since there is only one thread of execution in a JavaScript environment, events triggered in a continuous synchronous block of execution are received simultaneously. Callback listeners execute after the complete Kameleoon code block finishes, rather than the exact moment the code triggers the event. For example, Kameleoon::Loaded and Kameleoon::Started can be received simultaneously if local storage load is implemented synchronously (the typical 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 finishes loading and the engine code is available for execution in the browser. The event triggers at the beginning of the setup process. Subsequent events (detailed below) trigger as the initialization reaches specific steps.

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 triggers when the Kameleoon engine stops execution on the current page. This event indicates that Kameleoon is inactive for the current visitor and page. The event provides the reason for abortion:

• BROWSER: The browser is not supported.
• PRERENDER: This is a prerender request (e.g., Chrome optimization), not a webpage viewed by a human. Kameleoon does not run to avoid false statistics.
• STORAGE: Technical prerequisites for normal operations, such as Local Storage writes, cannot be met.
• TIMEOUT: File loading time exceeded the allowed amount, and the configuration requires abortion.
• DISABLED: Kameleoon was disabled via the back-office application. All front-end Kameleoon loads immediately abort when this status is active.
• PARAMETER: A special parameter in the URL (e.g., kameleoonDisabled=true) causes the engine to stop execution for debugging or verification.
• SCRIPT: A custom abort script returned true for the current load.

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 completes its main initialization. At this stage, the engine has loaded local storage data and executed the global script, custom data acquisition code, and delayed commands via the Command Queue. Following this event, Kameleoon activation and tracking loops start. Experiments and personalizations trigger (if targeting conditions match), and data collection begins.

Activation API methods are available. Kameleoon.API is readable, though some data (such as geolocation data obtained via subsequent asynchronous calls) may be unavailable. The event data indicates if initialization generated a new visitorCode.

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 triggers when the Kameleoon engine completes data gathering. As collection often involves remote calls or asynchronous methods, this event triggers after those processes finish.

The Activation API is fully usable once this event triggers. All API fields contain correct values.

Kameleoon often performs remote calls only at the beginning of a visit, so this event triggers later on the first page view and almost immediately on subsequent views. While reading Activation API data early may work on subsequent views, data presence and accuracy are not guaranteed. Listening for this event before performing read operations (especially for visit data such as geolocation or weather) is highly highly recommended.

Kameleoon::RemoteSynchronizationPerformed

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

This event triggers when the Kameleoon engine completes a Server Synchronization Call (SSC) initiated by the Kameleoon.API.Data.performRemoteSynchronization() method. This occurs during 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 fires whenever the legal consent status changes for the current visitor. Changes include acceptance (Kameleoon.API.Core.enableLegalConsent()) or denial (Kameleoon.API.Core.disableLegalConsent()) for the AB Testing or Personalization modules. Access the updated status via Kameleoon.API.Visitor.experimentLegalConsent or Kameleoon.API.Visitor.personalizationLegalConsent; the event object contains the update details.

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 triggers when an experiment triggers (i.e., when the visitor matches the target segment). Extra options, such as traffic exclusion or capping, may allow a visitor to trigger an experiment without activating it (see the next event). If the experiment triggers on multiple pages, the event fires each 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 triggers when an experiment activates (i.e., when the visitor counts toward experiment results). Activation occurs when an experiment triggers and all exposition conditions match. If activation occurs on multiple pages, the event fires each 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 triggers when a personalization triggers (i.e., when the visitor matches the target segment). Extra exposition options, such as capping, may prevent the personalization action (e.g., banner or pop-in display). In this scenario, the personalization does not activate (see the next event). If the personalization triggers on multiple pages, the event fires each 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 triggers when a personalization activates (i.e., when the personalization displays on the page). Activation occurs when a personalization triggers and all exposition conditions match. If activation occurs on multiple pages, the event fires each 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 fires whenever custom data is set (i.e., when its value is provided). This event fires regardless of the acquisition method (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 triggers when a conversion triggers (i.e., when a goal is 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 triggers when an active segment triggers (i.e., when a visitor matches all targeting segment conditions). A segment is active if it is associated with a running experiment, personalization, or the Audiences tool. Kameleoon considers all other segments 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 triggers when a segment defined as a key moment triggers. At this point, machine learning algorithms compute and provide a Kameleoon Conversion Score (KCS).

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.