Skip to main content

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.

Use the Kameleoon Application script for web experiments created using the graphic 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 tracking can be performed more effectively with the JavaScript file.
Kameleoon uses CDN servers during initialization. Once the configuration is received and cached, retrieval and updating occur quickly (50-70ms depending on the latency of the server from the nearest CDN).
There are two methods to get the configuration: Polling and Streaming.
The Server Side Events (SSE or EventSource) protocol is used.
The CDN is purged 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:
script-src https://[your-site-code].kameleoon.io https://[your-site-code].kameleoon.eu https://client-config.kameleoon.com https://sdk-config.kameleoon.eu 'unsafe-eval';
connect-src https://[your-site-code].kameleoon.io https://[your-site-code].kameleoon.eu https://eu-data.kameleoon.eu https://eu-data.kameleoon.io https://na-data.kameleoon.eu https://na-data.kameleoon.io https://editor.kameleoon.com https://api.kameleoon.com https://customers.kameleoon.com https://logger.kameleoon.io https://client-config.kameleoon.com https://sdk-config.kameleoon.eu;
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. Your projects may be hosted 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, all collected visitor data will be stored on a given instance. You need to use a framework where requests from the same visitor are processed by the same server instance. Otherwise, visitor data must be added completely before each tracking request, or loaded 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) will always be assigned to the same variation for an experiment, unless recomputation of the assignment is explicitly requested.
Follow the methodology detailed here.
All possible cases are explained in this article.
There are several reasons no data is displayed on the results page:
  • Wait 30-60 minutes for the Kameleoon server to confirm a visit. Every time the same visitor lands on the website, Kameleoon creates a new visit. The visit ends as soon as Kameleoon doesn’t receive new activity events (for example, exposure to a campaign, page view, scroll, clicks) in the last 30 minutes. Kameleoon creates a new visit after 30 minutes of inactivity.
  • If you have enabled bot filtering in the project settings, there might be an error with the user-agent value being set on the SDK. Refer to this article for more details.
  • Legal Consent is set to Required in the project settings, but the setLegalConsent SDK method has not been called. Refer to this documentation for more details.
  • None of the SDK methods that send a tracking request to Kameleoon servers were used.
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 is not a bot, you need to pass the Kameleoon UserAgent data by using the SDK method. Calling the method will prevent 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 cannot track visitors in the OFF variation.
  • Missing visitor data: The SDK does not 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 visitor’s data is stored in operational memory during the visitor’s session. The session’s duration can be set, although the default is 30 minutes.
The longer the session duration using the sessionDuration parameter, the more data SDK holds in memory. More data means increased consumption. The session is extended by an additional 30 minutes each time a visitor is contacted. So, SDK guarantees that data will not be deleted for at least 30 minutes from the last request.
In client SDKs (mobile and web), data is stored in local storages (in web LocalStorage). Data can be stored forever; however, using the dataExpirationInterval or targetingDataCleanupInterval parameter, you can set the data’s expiration date, after which, the data will be deleted.
Generally, there is no need to call the “flush” method manually: data is sent along with other calls to SDK methods. However, if you need to send data to the Data API without triggering the visitor feature flag, then use the “flush” method.
If you have a server-based SDK, data is stored 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 is stored forever (or in accordance with 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 data is included in visitor targeting.
If legal consent is enabled, data can only be collected with visitors’ consent.
If you’re using the Experiment Rule and aren’t receiving visitor statistics, ensure that:
  • In The Kameleoon App
    • The rule is created for the correct environment (production, staging, or development).
    • The rule is enabled (turned on).
    • The rule targets traffic that can actually be exposed.
    • If bot filtering is enabled on your project, add User Agent to the filter.
  • In the SDK
    • The KameleoonClient is created with the correct configuration (siteCode, environment variable, and, if applicable, networkDomain).
    • getVisitorCode is called only once, and its value is reused wherever the visitorCode is needed
    • If using hybrid mode (engine.js on the front), the visitorCode is correctly synced with the front end.
    • For experiment rules, setLegalConsent(true) is called to ensure data collection is allowed.
    • For delivery rules, isFeatureActive() (or getVariation()) is called, and it returns true (or the expected variation).
    • For experiment rules, getVariation() is called, 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.A tracking request will be sent:
  • Periodically: By default, a request is sent every 1000 milliseconds (1 second). You can change this interval by setting the tracking interval value.
  • On demand: Instantly, if a method like flush(instant=true) is called in your code.
Specifically, a tracking request is triggered if any of the following methods are called before the interval expires:
  • getVariation (when track is set to true).
  • getVariations (when track is set to true).
  • isFeatureActive (when track is set to true).
  • trackConversion
  • flush (with or without instant=true)
In addition to the above method calls, client-side SDKs send a tracking request every 15 seconds if no other activity has occurred. This request helps maintain the visitor session. The activity tracking interval can be configured with the Android and iOS SDKs.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.
In different SDKs the methods may be named 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), which are used to display statistics in the 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.
isFeatureActive can be called when you need to know whether the flag is active, but do not need to know the exact variation received for the visitor. When using Experiment rules, it is 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 is essential to call the getVisitorCode method. This ensures consistent visitor recognition between the browser and the server, and guarantees 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.
You should use getVisitorCode in instances where you are using a hybrid integration (web-site <-> server sdk, js sdk <-> server, engine <-> server sdk). When calling getVisitorCode, the visitor code will be obtained, and transmitted using a cookie. If you do not use a hybrid integration, you don’t need to call getVisitorCode; however, you can still call it to generate a random visitor code.
Domain installation is required for getVisitorCode. Otherwise, you may get different variations for one visitor, since it will have different visitor codes on different subdomains of your site.
Kameleoon, like many experience optimization solutions, can be blocked by certain ad blockers. 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 and are unaffected by ad blockers.If you want users with ad blockers to be included 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 will use your custom domain for all outgoing network requests to our servers, whether for tracking purposes or fetching SDK configuration updates.Using a custom domain is not 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 these requests are routed 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 cannot 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.