Skip to main content
Use the Kameleoon Application script for web experiments created using the Graphic editor or Code editor. Use the web SDK for feature flags and feature experiments.Note that Kameleoon can run in Hybrid mode. Hybrid mode uses both Web SDKs and the Kameleoon JavaScript application file. Hybrid mode allows you to use the optimal approach for individual tasks. For example, you can implement and deploy variations more easily on the server side, while the JavaScript file tracks more effectively.
Kameleoon uses CDN servers during initialization. Once the SDK receives and caches the configuration, retrieval and updates happen quickly, typically 50-70 ms depending on the latency of the server from the nearest CDN.
There are two methods to get the configuration: Polling and Streaming.
Streaming uses the Server Side Events (SSE or EventSource) protocol.
Kameleoon purges the CDN every time you update a feature flag configuration (for example, variations, traffic expositions, and targeting), or every 24 hours.
If you use a client-side SDK and the website restricts the loading of resources (scripts, images, media, CSS) via the standard Content-Security-Policy (CSP) HTTP header, update the site’s CSP to allow Kameleoon resources to load:
If you use Kameleoon in Hybrid mode, the domain for your Kameleoon scripts https://[your-site-code].kameleoon.xx may vary from one project to another. Kameleoon may host your projects on either kameleoon.eu or kameleoon.io depending on their creation date. Make sure you use the domain displayed in your project in the Kameleoon App. Replace [your-site-code] with your Kameleoon site code in each line that it appears and add this to your configuration.
Since each server instance has its own memory, it stores all collected visitor data on that instance. You need to use a framework that processes requests from the same visitor on the same server instance. Otherwise, you must add visitor data completely before each tracking request, or load it using the getRemoteVisitorData method.If the problem is in the SDK configuration difference, use the Streaming option.
All evaluations happen locally to eliminate latency. Tracking requests then go asynchronously to Kameleoon Data API servers.
To assign a visitor to an experiment variation, Kameleoon first builds an identifier using the visitor code, the experiment ID, and a potential additional element in case of respooling. Then, a synchronous implementation of the hash function SHA-256 computes a hash of this identifier. The integer obtained through hashing is then mapped to a floating number between zero and one to assign it to an experiment variation. The SHA-256 function is deterministic, so the same user (with the same visitor code) always receives the same variation for an experiment, unless you explicitly request a recomputation of the assignment.
Follow the methodology detailed here.
This article explains all possible cases.
The results page might display no data for several reasons:
  • If you enabled bot filtering in the project settings, the SDK might set the user-agent value incorrectly. Refer to this article for more details.
  • You configured Legal Consent as Required in the project settings, but haven’t called the setLegalConsent SDK method. Refer to this documentation for more details.
  • You didn’t use any of the SDK methods that send a tracking request to Kameleoon servers.
The following article provides additional help in debugging the issue.
If you see a large number of visits from visitors, they could be bots. To prevent bots from affecting your experiment, enable the Bot filtering option in your project settings. To indicate that a visitor isn’t a bot, you need to pass the Kameleoon UserAgent data by using the SDK method. Calling the method prevents Kameleoon from filtering the user.
If your reports show unexpected allocation (for example, 10/90 instead of 50/50) or if visitors are missing, it might be due to one of the following reasons:
  • Narrowing the visitor pool for specific variations: If you first call getVariations(onlyActive: true, track: false), the SDK only returns visitors assigned to active (ON) variations. If you then only display experiment pages and call getVariation(track: true) for these specific visitors, Kameleoon tracks only the ON variation, which results in a report that only shows one variation.
  • Insufficient time for tracking requests: Kameleoon sends data at a specific interval. If a visitor stays on a page with an integrated Kameleoon client for the ON variation, but moves to a page without it for the OFF variation, the client might not have enough time to send the tracking request for the OFF variation.
  • Missing configuration for specific variations: You might have omitted the UserAgent or setLegalConsent for some variations. For example, if you only provide consent on the page for the ON variation, Kameleoon can’t track visitors in the OFF variation.
  • Missing visitor data: The SDK doesn’t collect visitor data automatically; you must add it explicitly for targeting and tracking to work correctly.

​
Check your targeting setup

If you suspect targeting issues, follow these steps:
  1. Create a non-targeting rule with 100% exposure and assign your desired variation.
  2. Add targeting and ensure the user stops receiving the variation.
  3. Add the required Kameleoon data.
The user should receive the variation again. If this fails, try using simpler targeting conditions to isolate the issue.
Yes, data is immediately available for targeting. Data will be available during the visitor session for server-based SDKs and during the set lifetime for client-based SDKs (mobile and web).
It depends on the type of SDK.In server SDKs, the SDK stores visitor data in operational memory during the visitor’s session. You can set the session’s duration, although the default is 30 minutes.
The longer the session duration set with the sessionDuration parameter, the more data the SDK holds in memory, increasing consumption. Each time a visitor sends a request, the session extends by an additional 30 minutes. As a result, the SDK keeps data for at least 30 minutes after the last request.
In client SDKs (mobile and web), the SDK stores data in local storage (web LocalStorage). Data can persist indefinitely. However, using the dataExpirationInterval or targetingDataCleanupInterval parameter, you can set the data’s expiration date, after which the SDK deletes the data.
Generally, you don’t need to call the flush method manually: other calls to SDK methods send data along with them. However, if you need to send data to the Data API without triggering the visitor feature flag, use the flush method.
If you have a server-based SDK, it stores data during a visitor’s session. You don’t need to load the data on every request if the user’s session hasn’t expired. In mobile SDKs, data persists indefinitely (or according to your settings).If the user session is no longer active or if the visitor is moving between devices in the client SDK, call the getRemoteVisitorData method with the appropriate parameters to get data sent to the Data API. After loading, the SDK includes the data in visitor targeting.
An edge worker has no guaranteed memory of a visitor’s previous requests, so it behaves like a server-side SDK evaluating a brand-new visitor session every time. Most targeting conditions have no data to evaluate unless your integration supplies that data explicitly, typically by reading it from a cookie and calling addData() before evaluating the feature flag.getRemoteVisitorData() works at the edge, but its latency (typically 100-200 ms) and the lack of durable, cross-request memory in most edge platforms make it impractical for most edge use cases.See Edge targeting constraints for the full explanation and a code example, and Serverless edge compute starter kits for the frameworks Kameleoon supports.
If you enable legal consent, Kameleoon collects data only with visitors’ consent.
If you’re using the Experiment Rule and aren’t receiving visitor statistics, ensure that:
  • In the Kameleoon App
    • You created the rule for the correct environment (production, staging, or development).
    • The rule is on.
    • The rule targets traffic that Kameleoon can actually expose.
    • If you enabled bot filtering on your project, add User Agent to the filter.
  • In the SDK
    • You created the KameleoonClient with the correct configuration (siteCode, environment variable, and, if applicable, networkDomain).
    • You call getVisitorCode only once, and reuse its value wherever you need the visitorCode.
    • If using hybrid mode (engine.js on the frontend), the visitorCode syncs correctly with the frontend.
    • For experiment rules, you call setLegalConsent(true) to allow data collection.
    • For delivery rules, you call isFeatureActive() (or getVariation()), and it returns true (or the expected variation).
    • For experiment rules, you call getVariation(), and it returns the expected variation.
  • Debugging Tips
    • Log in the console: the consent value, the visitorCode, and the variation values, and verify they match what you see in the browser.
    • Enable SDK logging and check for any errors.
By default, the SDK batches multiple events together and sends a tracking request to Kameleoon servers for analytics purposes on a configurable interval. This approach improves efficiency and reduces server load.The SDK sends a tracking request:
  • Periodically: By default, the SDK sends a request every 1000 milliseconds (1 second). You can change this interval by setting the tracking interval value.
  • On demand: Instantly, if your code calls a method like flush(instant=true).
Specifically, calling any of the following methods before the interval expires triggers a tracking request:
  • getVariation (when you set track to true).
  • getVariations (when you set track to true).
  • isFeatureActive (when you set track to true).
  • trackConversion
  • flush (with or without instant=true)
In addition to the preceding method calls, client-side SDKs send a tracking request every 60 seconds by default if no other activity has occurred, helping maintain the visitor session. You can change this default by setting the activityTrackingIntervalMillisecond (or activity_tracking_interval_millisecond) parameter in your SDK configuration.For server-side SDKs, event batching is particularly useful as each tracking request can consolidate multiple visitors’ data into a single request. This approach aggregates information on all affected visitors and sends it once per interval, improving efficiency, and reducing server load.
Tracking requests are subject to Data API rate limits.For client-side SDKs, in environments where multiple visitors share the same network (for example, in an office), they may appear to originate from the same IP address, which can exceed the rate limit and cause a 429 - Too Many Requests error.
Different SDKs may name these methods differently due to language peculiarities.
The following is a list of SDK methods that make HTTP requests:
  • isFeatureActive / getFeatureVariationKey / getFeatureVariable / trackConversion / flush
    • These methods make asynchronous requests to the Data API to store all information about the visitor (including variations received by the user). Kameleoon uses this information to display statistics in app.kameleoon.com
  • getRemoteData / getRemoteVisitorData / getWarehouseAudience
    • These methods make synchronous requests to the Data API to obtain information about the visitor
  • Additionally, SDK makes asynchronous requests to obtain the configuration necessary for internal work.
Call isFeatureActive when you need to know whether the flag is active but don’t need to know the exact variation the visitor received. When using Experiment rules, it’s better to call getFeatureVariationKey if you have two or more variations other than off.
Yes, you can implement a hybrid integration using both a client-side SDK (such as the Kameleoon JavaScript SDK or the engine.js application file) and a server-side SDK. In this setup, it’s essential to call the getVisitorCode method. Calling this method ensures consistent visitor recognition between the browser and the server, and provides consistent variation allocation when running both client-side code (for example, event tracking) and server-side code (such as feature execution) for a given feature flag.
Use getVisitorCode in instances where you use a hybrid integration (web-site <-> server sdk, js sdk <-> server, engine <-> server sdk). When you call getVisitorCode, it obtains the visitor code and transmits it using a cookie. If you don’t use a hybrid integration, you don’t need to call getVisitorCode. However, you can still call it to generate a random visitor code.
getVisitorCode requires domain installation. Otherwise, you may get different variations for one visitor, since it will have different visitor codes on different subdomains of your site.
Certain ad blockers can block Kameleoon, like many experience optimization solutions. These primarily affect the Web Experimentation application file (engine.js) and client-side SDKs, which rely on JavaScript code loaded on your website. Server-side SDKs, however, operate within your servers, unaffected by ad blockers.If you want to include users with ad blockers in your experiments, Kameleoon offers a premium option that allows you to use a custom domain instead of Kameleoon’s default domain. Custom domains prevent ad blockers from detecting and blocking Kameleoon. Once configured, Kameleoon uses your custom domain for all outgoing network requests to Kameleoon’s servers, whether for tracking purposes, or fetching SDK configuration updates.Using a custom domain isn’t the same as self-hosting. When you use a custom domain, Kameleoon’s infrastructure still hosts and serves all the content (for example, engine.js, SDK configuration, tracking calls). The difference is that Kameleoon routes these requests through a domain you control, like experiments.mydomain.com.To enable this option, contact your Technical Account Manager. You must provide a full domain (for example, experiments-mydomain.com), not a subdomain (for example, experiments.mydomain.com). The domain name can’t contain the substring kameleoon.
  • For Web Experimentation, replace references to the default Kameleoon domain (kameleoon.) with your custom domain.
    • Example: //SITE_CODE.{your-domain}/engine.js
  • For client-side SDKs, use the networkDomain parameter in the SDK initialization.
If you want to self-host instead of using a custom domain, follow this guide.