Activation API events - Kameleoon Documentation

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 events implemented in the Activation API. If the current Activation API lacks a required event, contact technical support to request an improvement. Kameleoon can add new events to suit specific requirements.

Since a JavaScript environment has only one thread of execution, callback listeners receive events triggered within the same synchronous block of execution simultaneously. Callback listeners execute after the complete Kameleoon code block finishes, rather than at the exact moment the code triggers the event. For example, Kameleoon::Loaded and Kameleoon::Started can arrive simultaneously if the browser loads local storage synchronously (the typical case, except in a cross-domain setup when the current URL isn’t on the main domain). Kameleoon::Started and Kameleoon::ExperimentTriggered also arrive simultaneously for experiments where the engine can evaluate targeting immediately.

List of events

Kameleoon::Loaded

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

This event fires when the Kameleoon app 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 the Kameleoon app file finished loading, in milliseconds since January 1, 1970 (UTC).
timeout	Boolean	true if a timeout occurred during the (asynchronous) load of the Kameleoon app 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 isn’t supported.
PRERENDER: A prerender request, such as a Chrome optimization, triggered the load instead of an actual visit from a person. Kameleoon doesn’t run, to avoid generating false statistics.
STORAGE: The browser can’t meet technical prerequisites for normal operations, such as Local Storage writes.
TIMEOUT: File loading time exceeded the allowed amount, and the configuration requires abortion.
DISABLED: A user turned Kameleoon off in the back-office app. All frontend Kameleoon loads immediately stop when this status is active.
PARAMETER: A special parameter in the URL (for example, kameleoonDisabled=true) causes the engine to stop execution for debugging or verification.
SCRIPT: A custom script returned true, signaling Kameleoon to stop 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 fires 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. Kameleoon activation and tracking loops start following this event. 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 Kameleoon generated a new (random) visitorCode for this visitor (unknown or new to Kameleoon), else false.

Kameleoon::DataGathered

window.addEventListener('Kameleoon::DataGathered', function (event) {
  // At this point, the object is 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 aren’t guaranteed. Listening for this event before performing read operations (especially for visit data such as geolocation or weather) is highly recommended.

Kameleoon::FeatureFlagFileLoaded

window.addEventListener('Kameleoon::FeatureFlagFileLoaded', function (event) {
  // Feature flag rules are now registered in the engine.
});

This event fires when the Kameleoon engine finishes loading the feature flag rules file and registers its rules and variations. The engine loads feature flag rules from a file separate from the main configuration, so these rules can become available after Kameleoon::Started. Listen for this event when your code depends on feature flag rules and must not run before the engine knows about them. The event fires only when your site loads feature flag rules from a separate file and that file contains rules.

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 synchronization occurs during cross-device history reconciliation, Intelligent Tracking Prevention, or custom data updates. See the performRemoteSynchronization() reference for more information about SSCs.

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 you set the currentVisitOnly argument to true when calling `Kameleoon.API.Data.performRemoteSynchronization()`, 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}. This value could equal {“AB_TESTING”: false} if the update denies consent for only the AB Testing module, or {“AB_TESTING”: true, “PERSONALIZATION”: true} if it grants consent 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 (that is, 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 (that is, 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 (that is, when the visitor matches the target segment). Extra exposition options, such as capping, may prevent the personalization action (for example, banner or pop-in display). In this scenario, the personalization doesn’t 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 (that is, 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 you set custom data (that is, when its value becomes available). This event fires regardless of the retrieval 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 (that is, when a visitor reaches a goal).

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 (that is, when a visitor matches all targeting segment conditions). A segment is active if a running experiment, personalization, or the Audiences tool uses it. 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 Kameleoon computes the KCS.

​List of events

​Kameleoon::Loaded

Data available in the event

​Kameleoon::Aborted

Data available in the event

​Kameleoon::Started

Data available in the event

​Kameleoon::DataGathered

​Kameleoon::FeatureFlagFileLoaded

​Kameleoon::RemoteSynchronizationPerformed

Data available in the event

​Kameleoon::LegalConsentUpdated

Data available in the event

​Kameleoon::ExperimentTriggered

Data available in the event

​Kameleoon::ExperimentActivated

Data available in the event

​Kameleoon::PersonalizationTriggered

Data available in the event

​Kameleoon::PersonalizationActivated

Data available in the event

​Kameleoon::CustomDataSet

Data available in the event

​Kameleoon::ConversionTriggered

Data available in the event

​Kameleoon::SegmentTriggered

Data available in the event

​Kameleoon::ConversionScoreComputed

Data available in the event

List of events

Kameleoon::Loaded

Kameleoon::Aborted

Kameleoon::Started

Kameleoon::DataGathered

Kameleoon::FeatureFlagFileLoaded

Kameleoon::RemoteSynchronizationPerformed

Kameleoon::LegalConsentUpdated

Kameleoon::ExperimentTriggered

Kameleoon::ExperimentActivated

Kameleoon::PersonalizationTriggered

Kameleoon::PersonalizationActivated

Kameleoon::CustomDataSet

Kameleoon::ConversionTriggered

Kameleoon::SegmentTriggered

Kameleoon::ConversionScoreComputed