FAQ
This list is regularly updated with questions we often receive from our customers.
What is the function of the web SDK versus the Kameleoon Application script?
Use the Kameleoon Application script when you create web experiments using our graphic or code editor. Use the web SDK for working with 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.
How long does an SDK initialization take?
We use CDN servers during initialization. Once the configuration is received and cached, its retrieval and updating occur very quickly (50-70ms depending on the latency of your server from the nearest CDN).
How is the SDK config synchronized with the server?
There are two methods to get the configuration: Polling and Streaming.
What technology does the streaming method use?
We use Server Side Events (SSE or EventSource) protocol.
When does the Kameleoon CDN provide a new configuration to the SDK?
The CDN is purged every time you update a feature flag configuration (for example, variations, traffic expositions, and targeting), or every 24 hours.
What are the Kameleoon domains that I need to whitelist?
If you use a client-side SDK and your website restricts the loading of resources (scripts, images, media, CSS) via the standard Content-Security-Policy (CSP) HTTP header, you'll need to update your 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://data.kameleoon.eu https://data.kameleoon.io https://na-data.kameleoon.io https://na-data.kameleoon.eu 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;
Note: 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.
When does the SDK send a tracking request to our servers for analytics purposes?
By default, the SDK sends a tracking request to our servers for analytics every 1000 milliseconds (configurable via tracking_interval_millisecond in the SDK settings) and if any of the following methods were called in your code before the tracking request is sent:
getVariation(whentrackis set totrue)getVariations(whentrackis set totrue)isFeatureActive(whentrackis set totrue)flushtrackConversion
For server-side SDKs, this functionality is particularly useful as each tracking request can consolidate multiple visitors into a single request. This approach aggregates information on all affected visitors, sending it once per interval, improving efficiency and reducing server load.
If you prefer to send the request immediately, use the flush method with the parameter instant = true.
Please note that the method names can vary slightly depending on the SDK you are using. Refer to the documentation for each specific SDK to confirm the exact method names.
How do I set up the SDK if the server has several instances?
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.
Does the variation attribution/traffic allocation happen locally or on a server?
All evaluations happen locally to eliminate latency. Tracking requests then go asynchronously to our Data API servers.
How does the SDK ensure visitors are exposed to the same variation?
To assign a visitor to an experiment variation, Kameleoon first builds an identifier using the vistor code, the experiment ID, and a potential additional element in case of respooling. Then, we use our synchronous implementation of the hash function SHA-256 to compute 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, unles we explicitly ask to recompute the assignment.
How do I show a specific variation first in a feature flag simulation?
We recommend following the methodology detailed here.
If I change the traffic distribution/exposition, will visitors still see their allocated variation?
All possible cases are explained in this article.
Why are there no visits displayed on the results page?
There are several reasons no data is displayed on the results page:
- You must wait 30-60 minutes before our server confirms a visit. Usually, a first visit will be displayed once the visit has ended on the user device (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. You can refer to this article for more details.
- Legal Consent is set to Required in the project settings, but you haven't been calling the setLegalConsent SDK method. Refer to this documentation for more details.
- You did not use one of the SDK methods that send a tracking request to our servers.
This article should provide some additional help in debugging the issue.
Why don't the number of visits align with my actual traffic?
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.
Why aren't users being targeted by my feature flag?
SDK doesn't collect visitor data automatically; it needs to be added explicitly for targeting to work.
Check your targeting setup following these steps:
- Make a non-targeting rule with 100% exposure and assign your desired variation to the user.
- Add targeting and ensure the user stops receiving the varation.
- Add Kameleoon data.
The user should get the variation again. If this doesn’t work, try using simple targeting conditions to understand why yours isn’t working.
When I use addData(), is the data available for targeting right away?
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).
Where is data stored?
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.
When is it a good time to flush data?
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 our Data API without triggering the visitor feature flag, then you should use the "flush" method.
How do I use previously collected data for targeting?
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 you're not sure that the user session is still active or you are moving between devices in the client SDK, you need to call the getRemoteVisitorData method with the appropriate parameters to get data sent to our Data API. After loading, the data will be included in visitor targeting.
Why isn't my experiment collecting data?
If you're using the Experiment Rule and aren't receiving visitor statistics, ensure that:
- Feature flag is enabled on the correct environment.
- Feature flag rule is exposed to visitorsm and targeting is set correctly.
- You add User Agent link article if bot filtering is enabled on your project.
Additionally, if legal consent is enabled, data can only be collected with visitors' consent.
What data needs consent to be sent?
According to the GDPR rules, without the consent of the visitor, we can only use the technical information necessary for the correct operation of the functionality of our product.
Without consent, we send variations for Targeted Delivery rules (but not for Experiment rules). All other information (for example, CustomData, Page Views, and Geolocation) is sent only with the consent of the visitor (when they have given permission)
You can read about consent management in more detail here.
Which methods trigger HTTP requests? Are they synchronous or asynchronous?
In different SDKs the methods may be named differently due to language peculiaritites
This 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.
When should I use isFeatureActive or getFeatureVariationKey
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."
Do I need to call getVisitorCode?
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.
Is the domain mandatory the SDK or getVisitorCode
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.
If I'm using a hybrid integration, do I need to handle consent twice?
If you use server and client SDKs at the same time, you need to set the consent for both SDKs.
Please refer to this article for more details.
How do ad blockers affect Kameleoon?
Kameleoon, like many experience optimization solutions, can be blocked by certain ad blockers. These primarily affect Web Experimentation application file (kameleoon.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, we offer 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.
To enable this option, contact your Customer Success Manager. You will need to provide a full domain (e.g., experiments-mydomain.com), not a subdomain (e.g., experiments.mydomain.com). Additionally, the domain name cannot contain the substring "kameleoon."
For Client-Side SDKs, you will need to use the networkDomain parameter in the SDK initialization.
For Web Experimentation, replace references to the default Kameleoon domain (kameleoon.) with your custom domain.
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.