Skip to main content

Engine execution flow

The article explains how our experimentation engine works, providing a comprehensive breakdown of the engine overview, Kameleoon experimentation engine code flow, including loading, tracking, and execution. It aims to give a clear understanding of the process through a concise, step-by-step walkthrough of the code flow.

Experimentation engine overview​

Kameleoon offers a comprehensive single-platform optimization solution with features designed for web and full-stack application experimentations. The platform enables two primary solutions:

  • Conduct A/B testing and other forms of experimentation for websites and web applications through web experimentation.
  • Through feature experimentation, Kameleoon enables full-stack feature flagging and experimentation. It also serves additional APIs and tools to eliminate flickering in A/B experiments, seamlessly integrate with your existing tools, and automate specific tasks.

Code flow: loading​

Engine Flow

The Kameleoon experimentation engine involves running the Kameleoon.js tag, a JavaScript tag meant to be invoked through the HTML source code of your application's pages.

At the entry point, the following processes occur:

  1. Activation: The Kameleoon.js tag will invoke an Activation API call through Kameleoon.Analyst.load().

  2. Command queue execution: After Kameleoon has loaded, its engine will look into the kameleoonQueue array , and execute any commands in the order they were pushed, if you have code that needs to be triggered urgently before Kameleoon instantiates any function.

note

Kameleoon will only execute functions that have been added to the queue with the IMMEDIATE parameter.

  1. Anti-flicker and global variables: Flickering is a problem commonly occurring with JavaScrip-based A/B testing solutions. When your webpage is loading, it is possible that the original page displays briefly, instead of the variation. This twinkling is called the flicker effect or flickering. This may display an inaccurate experiment result; therefore, our platform includes built-in advanced techniques to eradicate flickering completely. If you want to configure your experiment with anti-flicker, the method loads the Kameleoon script asynchronously with an anti-flickering code.

Once Kameleoon has loaded on the page, the variable window.KameleoonEndLoadTime will store the timestamp of its completion.

note

You can adjust the timeout using the kameleoonLoadingTimeout JavaScript variable in the installation snippet, but it is recommended to keep it at the default value of 1000 milliseconds. This variable determines the maximum time that the Kameleoon installation tag can delay the display of your site while waiting for the Kameleoon application file.

  1. Check for blocking reasons: Before passing the initialization stage, any blocking reasons for the session are checked:

    • Storage: If there is no local or session storage, the experiment will quit, and the event listener Kameleoon::Aborted will return STORAGE as the blocking reason.

    • Timeout: If the application file (kameleoon.js) takes more than 1000ms to load, and if a timeout occurs while the project is configured to either Disable Kameleoon for this page or Disabled Kameleoon for the entire visit, the blocking reason is TIMEOUT.

    • Prerender: To execute the entry point, the document must be ready (if document.visibilityState == “prerender”). Otherwise, the Kameleoon script will abort, but will re-load if the visibility is changed, and the event listener Kameleoon::Aborted will return PRERENDER as the reason for blocking.

    • Custom script: If the visitor adds a custom script for abortion, the experiment will terminate, returning a Boolean value of TRUE with SCRIPT being the blocking reason.

    • Parameter: If the URL has KameleoonDisabled == true, the blocking reason returned will be PARAMETER before terminating the Kameleoon script.

    • Disabled: When a customer disables the project linked to the application file, the engine returns the code DISABLED. Please refer to this article for more information.

note

At this time, a custom script for abortion can be configured only by a Kameleoon technical account manager.

  1. Deferrals: All code and campaigns will be postponed for a second call. In the event of a second call, the configuration and campaigns will be fetched in SYNC mode from https://SITECODE.kameleoon.eu/kameleoon-configuration.js and https://SITECODE.kameleoon.eu/kameleoon-action.js, respectively.
note

At this time, the option to defer all campaigns can only be configured by a Kameleoon technical account manager. However, you can defer any given experiment by using the “DELAYED” tag (see Code flow: execution).

If there are no blocking reasons, the logic will move to the visitor data tracking stage.

Code flow: tracking​

Engine Flow Upon completing the initialization process, Kameleoon will ethically obtain visitor data before triggering any campaigns. The following happens during the parsing:

  1. Kameleoon collects technical data such as the visitor’s browser and operating system.

  2. If the customer has the option to unify session data across subdomains, Kameleoon will retrieve past visitor data by using its iFrame that is stored on the main local storage domain.

  3. If the real-time sync of visits or the cross-device option is enabled, the visitor’s usage history will be fetched from Kameleoon servers.

note

Real-time sync is enabled by default if you have subscribed to our Feature experimentation or for Safari browser to manage Intelligent tracking prevention (ITP) impacts on data stored in local storage.

  1. Once all data is retrieved, a visitor will be initialized; if none has been found in the kameleoonVisitorCode cookie or in local Storage, a new visitor code will be assigned, and all visits will be parsed and sent to the engine.

  2. Data such as the Page URL, device, operating system, date, time, geolocation, browser language, goals, and other activities will be parsed and stored.

note

If the client has the product recommendation add-on, Kameleoon will instantiate the product recommendation engine.

  1. Any JavaScript code inserted will be executed before initializing experiments and personalizations, via the global custom script.

  2. Kameleoon executes any pending commands from the CommandQueue that were not of type IMMEDIATE.

  3. The Kameleoon::Started event is triggered when the Kameleoon engine completes its initialization and data is stored locally.

  4. If the client has the Single page application (SPA) management option enabled, Kameleoon will monitor for any URL changes within the SPA. When it detects a change in the URL, it automatically reloads its engine to ensure that all experiments and personalizations continue to function correctly on the new page or view.

  5. Before intializing any campaigns, Kameleoon will:

    • Check for an adBlocker
    • Run mutationObserver to populate all classes and ids present on the page for querySelector optimization.
    • If the experimentation has a segment that uses visitor IP address and geolocation, fetch the data from https://data.kameleoon.io/ip and https://data.kameleoon.io/geolocation respectively.

  6. To load the campaign configuration for real-time data, Kameleoon will fetch the configuration from https://SITECODE.kameleoon.eu/live-experiments/config.js and cached it for 2 minutes.

note

The Live Update Experiments feature quickly refreshes any experiment tagged with LIVE-UPDATE to allow for real-time configuration updates without being affected by browser caching. This is especially useful for campaigns requiring frequent updates.

Code flow: execution​

Engine Flow Once the experimentation loop runs, if the user is targeted, Kameleoon will send an exposure event with a unique Id (nonce), an experimentID and a variationId exposed to a visitor. eg. eventType=experiment&nonce=5800F1BDD0667747&id=250830&variationId=978588.

After, Kameleoon starts data collection and tracking for each campaign, but if personalization was triggered but not displayed or activated, blocking reason for the non-exposure is returned with the possible values:

  • PERSONALIZATION_CAPPING: Personalization has reached its maximum global limit in terms of visitors.

  • SCHEDULE: Personalization is currently turned off based on its current schedule.

  • SCENARIO: The personalization will not be displayed because some scenario conditions are unmet.

  • PRIORITY: Indicates that there is a personalization with a higher priority.

  • VISITOR_CAPPING: The visitor has encountered a limit that prevents the display of personalization.

If there is a DELAYED pre-defined tag associated with the experiment, non-urgent experiments will be triggered after the first page loads, downloading the variation data containing personalizations, campaigns and variations from: https://SITECODE.kameleoon.eu/(personalizations)/$campaign_id/variations/$variation_id.js .

note

Delaying an experiment can be especially beneficial for campaigns such as popups, or experiments that modify elements below the fold, where the likelihood of flicker is minimal.

For the Kameleoon AI Opportunity Detection add-on, Kameleoon downloads the list of segments defined in the customer account from https://SITECODE.kameleoon.eu/audiences/segments.js that will be used to detect possible opportunities in all live experiments.

note

Kameleoon checks all segments created or modified in your account for the past 90 days. It includes segments with names that do not start with [DEV], [TEST], or [QA] and have targeting conditions that do not include page URLs.

Kameleoon gathers supplementary event data for every goal and segment set up. This information is utilized for in-depth analysis and reporting within the results page, displaying critical data and performance metrics such as the conversion rate and potential revenue growth.