Skip to main content

Technical considerations

Feature flags configuration and bucketing​

When a feature flag configuration is updated or turned on or off, SDKs can obtain the updated configuration from the Cloudflare Content Delivery Network (CDN) using either polling or streaming. Polling is the default option while streaming is a premium option.

Kameleoon SDKs are designed to comply with a zero latency policy. This means the SDK doesn't require additional remote server calls to activate and bucket users in a feature flag. Even the fastest remote server call would add a minimum of 20 ms of latency to the application and depending on several factors, this delay can increase to hundreds of milliseconds, or even completely block the loading of the web application for the end user. To prevent this added latency, Kameleoon SDKs assign visitors to experiments locally.

caution

For client-side SDKs, which run on the user's device, the app must fetch the active feature flag configurations at the start of the session. This requires a remote call with an associated callback, which means application code that uses the SDK can't run experiments or apply feature flags before this callback finishes executing.

Polling (default)​

In this mode, the SDK sends a request to the CDN at regular intervals (by default, every 60 minutes) to retrieve the most recent configuration. The interval can be customized in the SDK configuration using the refresh_interval_minute (or refresh_interval) parameter.

tip

When intervals are moderately spaced, updating the configuration consumes very little memory and network resources.

note

For Web Client-Side SDKs, the polling strategy includes local caching logic:

  1. Initial Load: When a web page is opened, the SDK first attempts to load the configuration from the cache (if available).
  2. Background Update: If the refresh_interval has elapsed, the SDK performs a background request to update the configuration and refreshes the cache.
  3. Cache Validity: Cached configuration is considered valid for 1.5 hours from the last successful update. If the visitor opens a page within this 1.5-hour window, the cached version will be used. Otherwise, the cache is ignored and a new request is made immediately.

This caching strategy ensures faster page loads and minimal network usage, while still keeping configuration reasonably fresh.

Let’s say refresh_interval is set to 15 minutes, and a user is exposed to a feature flag. If the feature flag is turned off 10 minutes later, and the same user returns to the website 20 minutes later :

  • The SDK will first load the configuration from cache (still showing the flag as active).
  • Simultaneously, it will make a background request to fetch the updated configuration and refresh the cache.
  • This design prioritizes performance, ensuring quick page loads while asynchronously syncing with the latest config.

So, even though there’s a short window where a user might see stale configuration (depending on the interval), the SDK quickly updates it in the background. The updated configuration will be applied the next time the visitor opens a page.

Streaming (premium option)​

The real-time streaming mode allows the SDK to automatically apply the new configuration without any delay. When streaming is enabled, the Kameleoon SDK is notified of any changes to the configuration in real time, thanks to server-sent events (SSE).

Main benefits:

  • Update the configuration immediately (no waiting for the next polling cycle).
  • Use less network traffic than polling at short intervals. Streaming does not send periodic requests. It opens the connection once and keeps it permanently open and remain ready to receive data.

Availability:

  • This is a premium option that requires a subscription. To activate real-time streaming on a Kameleoon account, contact the Customer Success Manager or email support@kameleoon.com.
  • The PHP SDK does not support streaming due to technical constraints. The PHP SDK currently can't listen for configuration updates in a non-blocking way because the PHP SDK does not persist between requests. Each request creates a new SDK instance that destroys itself as soon as it receives a response.
  • The real-time streaming mode is currently not compatible with serverless edge compute platforms.
  • For other languages, see the SDK compatibility matrix for the minimum supported version in the preferred language.

Data storage​

Kameleoon’s SDKs are designed for optimal performance and user experience. To achieve this, they manage visitor data locally, either on the server or directly on the device, instead of fetching it from a remote source.

All visitor data relevant to Kameleoon experiments and feature flags is stored locally, which includes experiment assignments, segment data, and any custom data added using methods like addData() or fetched from the server with getRemoteVisitorData(). The way this data is stored and its lifespan differs depending on whether a server-side or client-side SDK is used.

Server-side SDKs​

For server-side SDKs, visitor data is stored in the server’s volatile memory (RAM), which provides fast access for experiment and feature flag evaluations. Data is organized as a map, using unique visitorCode values as keys.

  • Session-based storage: Data is retained in memory only for the duration of a user’s active session, which ends, by default, after 30 minutes of inactivity (no page views, clicks, etc.). All data collected during the session expires at the same time.
    • session_duration parameter: The session duration can be adjusted using the session_duration parameter in the SDK configuration. This parameter lets the Kameleoon session align with the application’s server-side management.
danger

Increasing session_duration will require the SDK to allocate more RAM to store the increased visitor data

  • Data loss on server restart: Because data is stored in RAM, it will be lost if the application server restarts. Usually, data loss is not a concern, as important visitor data (like user IDs or attributes) is typically retrieved from a persistent database and reassigned to the visitor upon a new request.
  • Retrieving data from previous visits: The getRemoteVisitorData() method lets you retrieve custom data collected during a visitor’s previous visit. This method automatically associates the latest data entry for a visitor, eliminating the need to call addData() again.

Client-side SDKs​

As opposed to server-side SDKs, client-side SDKs utilize persistent local storage on the user’s device. This mechanism ensures that visitor data can be retained across browser sessions, app restarts, and even device reboots. The specific storage mechanism varies by platform:

  • iOS: UserDefaults
  • Android: SharedPreferences
  • JavaScript/TypeScript: LocalStorage
    • Note for JS SDK: The kameleoonVisitorCode is also shared via cookies to ensure seamless data continuity and communication with the Kameleoon application file (engine.js).
  • React Native: MMKV Storage

Unlike server-side SDKs which use a global session_duration, client-side SDKs do not operate on a session-based expiry for all data. Instead, they use either targetingDataCleanupInterval or data_expiration_interval_minute to control how long individual pieces of data are stored.

  • targetingDataCleanupInterval/data_expiration_interval_minute: These parameters determine the individual lifespan of each specific data entry. By default, data is stored indefinitely (until explicitly cleared) to ensure consistent user experiences across visits. You can set this parameter to a specific number of minutes if you need individual data points to expire after a certain time.
  • Data persistence: This fundamental difference means that data persists even if the user closes the browser tab, navigates away from the site, or closes the mobile application.
  • Naming convention rationale: The difference in parameter terminology (session_duration vs. data_expiration_interval_minute) directly reflects the underlying storage philosophy. session_duration governs the overall lifetime of all data within a server-side session. data_expiration_interval_minute allows granular control over the lifespan of each specific piece of data stored persistently on the client.

Domain list​

The Kameleoon SDKs require access to a set of URIs that provide specific services to the SDK. If you are restricting access and need to explicitly whitelist domains, make sure that our SDKs can reach the following domains:

URIUsed by
https://sdk-config.kameleoon.eu/<sitecode>Configuration file
https://<sitecode>.kameleoon.io/sdk-config / https://client-config.kameleoon.com/mobileConfiguration file (deprecated)
https://events.kameleoon.com:8110/sseReal-time streaming
https://api.kameleoon.com/oauth/tokenAuthentication
https://eu-data.kameleoon.io/ https://na-data.kameleoon.ioTracking
note

The domain for your Kameleoon scripts 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.