Documentation Index

Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Engine execution flow

Learn how the experimentation engine loads, tracks, and executes experiments.

​

Experimentation engine overview

Kameleoon provides a single-platform optimization solution for web and full-stack application experimentation. The platform supports two primary solutions:

• Web Experimentation: Conduct A/B testing and other forms of experimentation for websites and web applications.
• Feature Experimentation: Enable full-stack feature flagging and experimentation. Kameleoon also provides additional APIs and tools to eliminate flickering in A/B experiments, integrate with your existing tools, and automate tasks.

​

Code flow: loading

The Kameleoon engine runs the engine.js tag (previously kameleoon.js). Invoke this JavaScript tag through the HTML source code of your application pages. At the entry point, the engine:

1. Activation: The engine.js tag invokes an Activation API call through Kameleoon.Analyst.load().
2. Command queue execution: After loading, the engine checks the kameleoonQueue array and executes commands in the order you pushed them. Use this for code that must run before Kameleoon instantiates functions.

3. Anti-flicker and global variables: Flickering occurs when the original page displays briefly before the variation appears. This effect can lead to inaccurate results. Kameleoon uses advanced techniques to eliminate flickering. If you configure anti-flicker, the system loads the Kameleoon script asynchronously with anti-flicker code.

Once Kameleoon finishes loading, the window.KameleoonEndLoadTime variable stores the completion timestamp.

4. Check for blocking reasons: Before completing initialization, the engine checks for these blocking reasons:
   • Storage: If local or session storage is unavailable, the engine terminates and returns the Kameleoon::Aborted event with the STORAGE code.
   • Timeout: If engine.js takes more than 750ms to load and you configured the project to disable Kameleoon for the page or visit, the engine returns TIMEOUT.
   • Prerender: Kameleoon requires the document to be ready (document.visibilityState == "prerender"). If it is not, the script terminates and returns PRERENDER. It reloads when the visibility state changes.
   • Custom script: If a custom script aborts the session, the engine returns SCRIPT.
   • Parameter: If the URL contains KameleoonDisabled == true, the engine returns PARAMETER and terminates.
   • Disabled: If you disable the project in the dashboard, the engine returns DISABLED. See this article for details.

5. Deferrals: The engine postpones code and campaigns for a second call if necessary. In this case, the engine fetches configuration and campaigns in SYNC mode from https://SITECODE.kameleoon.com/kameleoon-configuration.js and https://SITECODE.kameleoon.com/kameleoon-action.js.

If no blocking reasons exist, the engine proceeds to the visitor data tracking stage.

​

Code flow: tracking

After initialization, Kameleoon retrieves visitor data:

1. Kameleoon collects technical data such as the visitor’s browser and operating system.
2. If you enable unify session data across subdomains, Kameleoon retrieves past data using an iFrame on the main local storage domain.
3. If you enable real-time sync of visits or the cross-device option, the engine fetches usage history from Kameleoon servers.

4. The engine initializes a visitor. If no code exists in the kameleoonVisitorCode cookie or local storage, the engine assigns a new visitor code and parses all visits.
5. The engine parses and stores data such as the Page URL, device, operating system, geolocation, and goals.

6. The global custom script executes any inserted JavaScript before initializing experiments.
7. The global experiment script runs after the custom global script. This script executes regardless of targeting and stops when the experiment pauses. See this guide for details.
8. The engine executes pending commands from the CommandQueue that do not use the IMMEDIATE parameter.
9. The Kameleoon::Started event triggers when initialization completes and the engine stores the data.
10. If you enable SPA management, Kameleoon monitors URL changes. When the URL changes, the engine reloads to ensure campaigns function correctly on the new view.
11. Before initializing campaigns, Kameleoon:
    • Checks for an ad blocker.
    • Runs mutationObserver to optimize querySelector operations.
    • Fetches geolocation data from https://eu-data.kameleoon.io/ip if the segment requires it.
12. To load campaign configuration, Kameleoon fetches data from https://SITECODE.kameleoon.com/live-experiments/config.js and caches it for 2 minutes.

​

Code flow: execution

When the experimentation loop runs, the engine:

1. If the visitor is part of a “holdout” group, the engine sends a holdout inclusion event.
2. The engine triggers an exposure event containing a nonce, experimentID, and variationId. For example: eventType=experiment&nonce=5800F1BDD0667747&id=250830&variationId=978588.
3. If the visitor is not in a holdout group, the engine sends a “Holdout exclusion event.”

The engine then starts data collection. If a personalization triggers but does not display, the engine returns one of the following blocking reasons:

• PERSONALIZATION_CAPPING: The personalization reached its global visitor limit.
• SCHEDULE: The personalization is off based on its schedule.
• SCENARIO: Some scenario conditions remain unmet.
• PRIORITY: A higher-priority personalization exists.
• VISITOR_CAPPING: The visitor reached a limit preventing display.

If you associate a DELAYED tag with an experiment, the engine triggers it after the first page load. The engine downloads variation data from https://SITECODE.kameleoon.com/(personalizations)/$campaign_id/variations/$variation_id.js. For the AI Opportunity Detection add-on, Kameleoon downloads segment definitions from https://SITECODE.kameleoon.com/audiences/segments.js to detect opportunities. Analyze this information on the results page to track conversion rates and potential revenue growth.