Elixir SDK - Kameleoon Documentation

With the Kameleoon Elixir SDK, you can run experiments and activate feature flags in your Elixir services and web back-ends. Getting started: For help getting started, see the developer guide. Version: Latest version of the Elixir SDK: 0.9.0 Changelog. SDK methods: For the full reference documentation of the Elixir SDK, see the reference section.

Developer guide

This guide is designed to help you integrate the Elixir SDK quickly and start evaluating feature flags in your Elixir application.

Getting started

Install the Elixir client

The Kameleoon Elixir SDK includes native code powered by the Kameleoon Rust core. During dependency compilation, Mix invokes Cargo to build the native library. Make sure Rust and Cargo are installed and available in your system’s PATH before running mix deps.get or mix compile.Install Rust and Cargo: https://rust-lang.org/tools/installThe Rust core is compiled locally for your target platform and architecture, ensuring optimal compatibility with your environment.We plan to provide prebuilt native libraries for common platforms in future releases to simplify installation. These prebuilt binaries will be suitable for most use cases, while local compilation will remain available for users who prefer to build from source.

Add the SDK as a dependency in your mix.exs file:

mix.exs

def deps do
  [
    {:kameleoon_client, "~> 0.9.0"}
  ]
end

Additional configuration

Create a client-elixir.json configuration file to provide credentials and customize SDK behavior. We recommend saving this file to the default path, /etc/kameleoon/client-elixir.conf. The Elixir SDK can be configured either with a configuration file used by config_path: or by passing a %Kameleoon.ClientConfig{} struct with the config: option. The following table shows the available properties that you can set:

Key (Code / Config File)	Description	Default value
`client_id` / `clientId` required	Required for authentication to the Kameleoon service. To find your `client_id`, see the API credentials documentation.
`client_secret` / `clientSecret` required	Required for authentication to the Kameleoon service. To find your `client_secret`, see the API credentials documentation.
`session_duration_minutes` / `sessionDurationMinutes` optional	Time interval, in minutes, during which the SDK keeps a visitor and their associated data in memory.	`30` minutes
`refresh_interval_minutes` / `refreshIntervalMinutes` optional	Interval, in minutes, used to refresh the active experiments and feature flags configuration.	`60` minutes
`default_timeout_millis` / `defaultTimeoutMillis` optional	Default timeout, in milliseconds, for SDK network requests.	`10000` milliseconds
`tracking_interval_millis` / `trackingIntervalMillis` optional	Interval, in milliseconds, used to batch tracking requests. Values are clamped to the `[1000, 5000]` range.	`1000` milliseconds
`environment` / `environment` optional	Environment from which the feature flag configuration should be used. The value can be `production`, `staging`, or `development`.	`production`
`top_level_domain` / `topLevelDomain` optional	The current top-level domain for your website. Use the format `example.com` without protocol or subdomains.	`nil`
`proxy_host` / `proxyHost` optional	Proxy host for outgoing SDK calls. Supported formats: `https://my.prox`, `https://my.prox:4545`, `socks5://192.168.1.1:9000`.	`nil`
`network_domain` / `networkDomain` optional	Custom domain used by SDKs for outgoing requests, often for proxying. Must be a valid domain (e.g., example.com or sub.example.com). Invalid formats default to Kameleoon’s value.	`nil`

Initialize the Kameleoon client

After you have installed the SDK and configured your credentials, create a %Kameleoon.Client{} by using Kameleoon.ClientFactory.

Config File
Code

alias Kameleoon.Client
alias Kameleoon.ClientFactory

site_code = "a8st4f59bj"

{:ok, client} = ClientFactory.create(site_code, config_path: "/etc/kameleoon/client-elixir.conf")
:ok = Client.initialize(client)

alias Kameleoon.Client
alias Kameleoon.ClientConfig
alias Kameleoon.ClientFactory

site_code = "a8st4f59bj"

config = %ClientConfig{
  client_id: "<client-id>",               # mandatory
  client_secret: "<client-secret>",       # mandatory
  refresh_interval_minutes: 60,           # optional (60 minutes by default)
  session_duration_minutes: 30,           # optional (30 minutes by default)
  default_timeout_millis: 10_000,         # optional (10000 ms by default)
  tracking_interval_millis: 1_000,        # optional (1000 ms by default)
  environment: "development",             # optional
  top_level_domain: ".example.com",       # optional mandatory if you use hybrid mode (engine or web experiments)
  proxy_host: "http://192.168.0.25:8080", # optional
  network_domain: "example.com"           # optional
}

{:ok, client} = ClientFactory.create(site_code, config: config)
:ok = Client.initialize(client)

A %Kameleoon.Client{} is the main object used to evaluate feature flags, add visitor data, and send tracking requests.

It is recommended to use %Kameleoon.Client{} as a singleton object, as it serves as the bridge between your application and the Kameleoon platform. It exposes all required methods and properties to run experiments efficiently.
The Elixir SDK initializes asynchronously. You should call initialize() before relying on feature evaluation in production code.

Activating a feature flag

Assigning a unique ID to a user

To assign a unique ID to a user, you can use the get_visitor_code method. If a visitor code doesn’t exist (from the request headers cookie), the method generates a random unique ID or uses a default_visitor_code that you would have generated. The ID is then set in a response headers cookie. If you are using Kameleoon in Hybrid mode, calling the get_visitor_code method ensures that the unique ID (visitor code) is shared between the application file engine.js (previously named, kameleoon.js) and the SDK.

Retrieving a flag configuration

To implement a feature flag in your code, you must first create the feature flag in your Kameleoon account. To determine the status or variation of a feature flag for a specific user, you should use the get_variation or is_feature_active? method to retrieve the configuration based on the feature_key. The get_variation method handles both simple feature flags with ON/OFF states and more complex flags with multiple variations. The method retrieves the appropriate variation for the user by checking the feature rules, assigning the variation, and returning it based on the feature_key and visitor_code. The is_feature_active? method can be used if you want to retrieve the configuration of a simple feature flag that has only an ON or OFF state, as opposed to more complex feature flags with multiple variations or targeting options. If your feature flag has associated variables (such as specific behaviors tied to each variation) get_variation also enables you to access the Variation object, which provides details about the assigned variation and its associated experiment. This method checks whether the user is targeted, finds the visitor’s assigned variation, and saves it to storage. When track=true, the SDK will send the exposure event to the specified experiment on the next tracking request, which is automatically triggered based on the SDK’s tracking_interval_millis. By default, this interval is set to 1000 milliseconds (1 second). The get_variation method allows you to control whether tracking is done. If track=false, no exposure events will be sent by the SDK. This is useful if you prefer not to track data through the SDK and instead rely on client-side tracking managed by the Kameleoon engine, for example. Additionally, setting track=false is helpful when using the get_variations method, where you might only need the variations for all flags without triggering any tracking events. If you want to know more about how tracking works, view this article

Adding data points to target a user or filter / breakdown visits in reports

To target a user, ensure you’ve added relevant data points to their profile before retrieving the feature variation or checking if the flag is active. Use the Client.add_data method to add these data points to the user’s profile. To retrieve data points collected on other devices or to access past user data (collected client-side when using Kameleoon in Hybrid mode), use the get_remote_visitor_data method. This method asynchronously fetches data from the servers. It is important to call get_remote_visitor_data before retrieving the variation or checking if the feature flag is active, as this data might be required to assign a user to a given variation. To learn more about available targeting conditions, see the detailed article on the subject. Additionally, the data points you add to the visitor profile will be available when analyzing your experiments, allowing you to filter and break down your results by factors like device and browser. Kameleoon Hybrid mode automatically collects a variety of data points on the client-side, making it easy to break down your results based on these pre-collected data points. See the complete list here. If you need to track additional data points beyond what’s automatically collected, you can use Kameleoon’s Custom Data feature. Custom Data allows you to capture and analyze specific information relevant to your experiments. Don’t forget to call the flush method to send the collected data to Kameleoon servers for analysis.

To ensure your results are accurate, it’s recommended to filter out bots by using the UserAgent data type.

Tracking goal conversions

When a user completes a desired action (such as making a purchase), it is recorded as a conversion. To track conversions, use the track_conversion method and provide the required visitor_code and goal_id parameters. The conversion tracking request will be sent along with the next scheduled tracking request, which the SDK sends at regular intervals (defined by tracking_interval_millis). If you prefer to send the request immediately, use the Client.flush_instant method.

Sending events to analytics solutions

To track conversions and send exposure events to your customer analytics solution, you must first implement Kameleoon in Hybrid mode. Then, use the get_engine_tracking_code method. The get_engine_tracking_code method retrieves the unique tracking code required to send exposure events to your analytics solution. Using this method allows you to record events and send them to your desired analytics platform.

Using a custom bucketing key

By default, Kameleoon uses a unique, anonymous visitor ID (visitor_code) to assign users to feature flag variations. This ID is typically generated and stored on the user’s device (in a browser cookie for client-side and server-side SDKs—in persistent storage for mobile SDKs). However, in certain scenarios you may need to ensure all users of the same organization see the same variant of a feature flag. The Custom Bucketing Key option allows you to override this default behavior by providing your own custom identifier for bucketing. This override ensures that Kameleoon’s assignment logic uses your specified key instead of the default visitor_code.

Use cases

Using a custom bucketing key is essential for maintaining consistency and accuracy in your feature flag assignments, particularly in these situations:

Account-level or organizational experiments: For B2B products or scenarios where you want to assign all users from the same organization to the same variation, you can use an identifier like an account_id. Custom bucketing keys are crucial for A/B testing features that impact an entire team or company.

By implementing a custom bucketing key, you ensure greater consistency and accuracy in your experiments, leading to more reliable results and a better user experience.

Technical details

When you configure a custom bucketing key for a feature flag, you provide Kameleoon with a specific identifier from your application’s data:

alias Kameleoon.Client
alias Kameleoon.Data.CustomData

:ok = Client.add_data(client, visitor_code, CustomData.new!(42, ["new_visitor_code"]))

Providing the custom key: You provide your custom identifier to the Kameleoon SDK using the Client.add_data method. In this method, you will pass your chosen custom bucketing key as a CustomData object. Here, new_visitor_code refers to the identifier you wish to use for your bucketing (for example, the new user_id or account_id).

For the custom bucketing key to function correctly, it must also be defined and configured for the feature flag during the flag creation or editing process. Without this corresponding configuration, the SDK’s bucketing will not apply your custom key. For detailed instructions on how to set this up in Kameleoon, refer to this article.

Bucketing logic: Once a custom bucketing key is provided through the Client.add_data method, all hash calculations for assigning users to variations will use this new_visitor_code (your custom key) instead of the default visitor_code. Using the new_visitor_code means that the bucketing decision is tied to your custom identifier, ensuring consistent assignments across various contexts where that identifier is present.
Data tracking and analytics: It’s crucial to note that while the new_visitor_code (your custom key) is used for bucketing decisions, all subsequent data (tracking events and conversions, for example) is sent and associated with the original visitor_code. This separation ensures that your analytics accurately reflect individual user journeys and interactions within your experiment’s broader context, even when bucketing is performed at a higher level (like an account) or across multiple devices/sessions. Your original visitor data remains intact for comprehensive reporting.

Technical requirements

To effectively use a custom bucketing key:

The key must be a String.t().
It must be unique for the entity you intend to bucket (for example, if using a user_id, each user’s ID should be unique).
The key must be available to the SDK at the exact moment the feature flag decision is evaluated for that user or request.

Targeting conditions

The Kameleoon SDKs support a variety of predefined targeting conditions that you can use to target users in your campaigns. For the list of conditions this SDK supports, see use visit history to target users. You can also use your own external data to target users.

Cross-device experimentation

To support visitors who access an app from multiple devices, Kameleoon allows the synchronization of previously collected visitor data across each of the visitor’s devices and reconciliation of their visit history across devices through cross-device experimentation. Case studies and detailed information on how Kameleoon handles data across devices are available in the article on cross-device experimentation.

Synchronizing custom data across devices

Although custom mapping synchronization is used to align visitor data across devices, it is not always necessary. Below are two scenarios where custom mapping sync is not required: Same user ID across devices If the same user ID is used consistently across all devices, synchronization is handled automatically without a custom mapping sync. It is enough to call the get_remote_visitor_data method when you want to sync the data collected between multiple devices. Multi-server instances with consistent IDs In complex setups involving multiple servers (for example, distributed server instances), where the same user ID is available across servers, synchronization between servers (with get_remote_visitor_data) is sufficient without additional custom mapping sync. Customers who need additional data can refer to the get_remote_visitor_data method description for further guidance. In the below code, it is assumed that the same unique identifier (in this case, the visitor_code, which can also be referred to as userId) is used consistently between the two devices for accurate data retrieval.

If you want to sync collected data in real time, you need to choose the scope Visitor for your custom data.

Device A

# In this example, a Custom data with index `90` was set to "Visitor" scope in Kameleoon.
alias Kameleoon.Client
alias Kameleoon.Data.CustomData

visitor_scope_custom_data_index = 90

:ok = Client.add_data(client, visitor_code, CustomData.new!(visitor_scope_custom_data_index, ["your data"]))

:ok = Client.flush_instant(client, visitor_code)

Device B

# Before working with the data, call the `get_remote_visitor_data` method.
:ok = Client.get_remote_visitor_data(client, visitor_code)

# After calling the method, the SDK on Device B will have access to CustomData of Visitor scope defined on Device A.
# So, "your data" will be available for targeting and tracking the visitor.

Using custom data for session merging

Cross-device experimentation allows for combining a visitor’s history across each of their devices (history reconciliation). History reconciliation allows merging different visitor sessions into one. To reconcile visit history, use CustomData to provide a unique identifier for the visitor. For more information, see the dedicated documentation. After cross-device reconciliation is enabled, calling get_remote_visitor_data with the parameter userId retrieves all known data for a given user. Sessions with the same identifier will always be shown the same variation in an experiment. In the Visitor view of your experiment’s results pages, these sessions will appear as a single visitor. The SDK configuration ensures that associated sessions always see the same variation of the experiment. However, there are some limitations regarding cross-device variation allocation. These limitations are outlined here. Follow the activating cross-device history reconciliation guide to set up your custom data on the Kameleoon platform. Afterwards, you can use the SDK normally. The following methods that may be helpful in the context of session merging:

get_remote_visitor_data with added UniqueIdentifier(true) - to retrieve data for all linked visitors.
track_conversion or flush with added UniqueIdentifier(true) data - to track some data for specific visitor that is associated with another visitor.

As the custom data you use as the identifier must be set to Visitor scope, you need to use cross-device custom data synchronization to retrieve the identifier with the get_remote_visitor_data method on each device.

Here’s an example of how to use custom data for session merging.

# In this example, 91 represents the Custom Data's index configured as a unique identifier in Kameleoon.
alias Kameleoon.Client
alias Kameleoon.Data.CustomData
alias Kameleoon.Data.UniqueIdentifier

mapping_index = 91
feature_key = "ff123"

anonymous_visitor_code = "anonymous-visitor"
user_id = "authenticated-user"

# 1. Before the visitor is authenticated

# Retrieve the variation for an unauthenticated visitor.
# Assume anonymousVisitorCode is the randomly generated ID for that visitor.
{:ok, anonymous_variation} = Client.get_variation(client, anonymous_visitor_code, feature_key)

# 2. After the visitor is authenticated

# Assume `userId` is the visitor code of the authenticated visitor.
:ok = Client.add_data(client, anonymous_visitor_code, CustomData.new!(mapping_index, [user_id]))
:ok = Client.flush_instant(client, anonymous_visitor_code)

# Indicate that `userId` is a unique identifier.
:ok = Client.add_data(client, user_id, UniqueIdentifier.new!(true))

# 3. After the visitor was authorized

# Retrieve the variation for the `userId`, which will match the anonymous visitor code's variation.
{:ok, user_variation} = Client.get_variation(client, user_id, feature_key)
is_same_variation = user_variation.key == anonymous_variation.key # true

# `userId` and `anonymousVisitorCode` are now linked and can be tracked as a single visitor.
:ok = Client.track_conversion(client, user_id, 123)

# Additionally, the linked visitors share all fetched previously tracked remote data.
:ok = Client.get_remote_visitor_data(client, user_id)

In this example, the application has a login page. Since the user ID is unknown at the moment of login, an anonymous visitor identifier generated by the get_visitor_code method is used. After the user logs in, the anonymous visitor is associated with the user ID and used as a unique identifier for the visitor.

Logging

The SDK generates logs to reflect various internal processes and issues.

Log levels

The SDK supports configuring limiting logging by a log level.

alias Kameleoon.Logger

# The `:none` log level does not allow logging.
:ok = Logger.set_log_level(:none)

# The `:error` log level only allows logging issues that may affect the SDK's primary behaviour.
:ok = Logger.set_log_level(:error)

# The `:warning` log level allows logging issues which may require attention.
# It extends the `:error` log level.
# The `:warning` log level is the default log level.
:ok = Logger.set_log_level(:warning)

# The `:info` log level allows logging general information on the SDK's internal processes.
# It extends the `:warning` log level.
:ok = Logger.set_log_level(:info)

# The `:debug` level logs additional details about the SDK's internal processes.
:ok = Logger.set_log_level(:debug)

Custom handling of logs

The SDK writes its logs to the console output by default. This behaviour can be overridden.

Logging limiting by a log level is performed apart from the log handling logic.

defmodule CustomLogger do
  @behaviour Kameleoon.Logger
  require Logger

  @impl true
  def log(level, message) do
    Logger.log(level, message)
  end
end

# Log level filtering is applied separately from log handling logic.
# The custom logger will only accept logs that meet or exceed the specified log level.
:ok = Kameleoon.Logger.set_log_level(:debug)
:ok = Kameleoon.Logger.set_logger(CustomLogger)

Reference

This is the full reference documentation for the Elixir SDK.

Initialization

create()

To use the SDK, create a %Kameleoon.Client{} from a %Kameleoon.ClientConfig{} instance with Kameleoon.ClientFactory.create().

ClientConfig (config:)
Config Path (config_path:)

alias Kameleoon.ClientConfig
alias Kameleoon.ClientFactory

config = %ClientConfig{
  client_id: "<client-id>",               # mandatory
  client_secret: "<client-secret>",       # mandatory
  refresh_interval_minutes: 60,           # optional (60 minutes by default)
  session_duration_minutes: 30,           # optional (30 minutes by default)
  default_timeout_millis: 10_000,         # optional (10000 ms by default)
  tracking_interval_millis: 1_000,        # optional (1000 ms by default)
  environment: "development",             # optional
  top_level_domain: ".example.com",       # optional mandatory if you use hybrid mode (engine or web experiments)
  proxy_host: "http://192.168.0.25:8080", # optional
  network_domain: "example.com"           # optional
}

{:ok, client} = ClientFactory.create(site_code, config: config)

alias Kameleoon.ClientFactory

{:ok, client} = ClientFactory.create("a8st4f59bj", config_path: "/etc/kameleoon/client-elixir.conf")

Parameters

Name	Type	Description
`site_code` required	`String.t()`	Unique key of the Kameleoon project used by the SDK.
`config_path` optional	`String.t()`	Path to the configuration file.
`config` optional	`Kameleoon.ClientConfig.t()`	SDK configuration struct.

Return value

Type	Description
`{:ok, Kameleoon.Client.t()} \| {:error, Error.t()}`	A client instance on success, otherwise an initialization error.

Errors

Type	Description
`ConfigCredentialsInvalid`	The SDK credentials are missing.
`SiteCodeIsEmpty`	The provided site code is empty.

initialize()

Waits for the Kameleoon client to initialize, using either the configured default_timeout_millis or a provided timeout. This method ensures that the client is fully initialized before performing any further operations.

alias Kameleoon.Client

# Initializes the client using the configured default timeout
:ok = Client.initialize(client)

# Initializes the client with a custom timeout of 5 seconds
:ok = Client.initialize(client, timeout: 5_000)

Parameters

Name	Type	Description
`timeout` optional	`non_neg_integer()`	Maximum time to wait for initialization, in milliseconds.

Return value

Type	Description
`:ok \| {:error, Error.t()}`	Indicates whether initialization completed successfully or an error occurred.

Errors

Type	Description
`Initialization`	Indicates that the SDK is not yet fully initialized.

is_ready()

Checks whether the client has been initialized.

alias Kameleoon.Client

ready? = Client.is_ready?(client)

if ready? do
  # The client is ready
end

Return value

Type	Description
`boolean()`	`true` if the client is ready to be used, `false` if it is not ready.

forget()

Removes the cached SDK client associated with the specified site_code.

alias Kameleoon.ClientFactory

# Removes the cached client for the given site code
:ok = ClientFactory.forget("a8st4f59bj")

# Removes the cached client for the given site code and environment
:ok = ClientFactory.forget("a8st4f59bj", environment: "production")

Parameters

Name	Type	Description
`site_code` required	`String.t()`	Unique identifier of the Kameleoon project.
`environment` optional	`String.t()`	Environment key associated with the cached client.

Return value

Type	Description
`:ok \| {:error, Error.t()}`	Indicates whether the cached client was successfully removed or an error occurred.

Feature flags and variations

is_feature_active()

📨 Sends tracking data to Kameleoon (depending on the track option)

Determines whether a feature flag is active for a given user. If the visitor has not yet been evaluated for this feature flag, the SDK evaluates the targeting rules and returns the result. If the visitor already has a stored evaluation for the feature, the SDK reuses the existing result to ensure consistency.

Kameleoon uses tracking to count sessions and visitors when you call certain methods, such as is_feature_active?, get_variation or get_variations.Use the default true value for the track parameter when you expose visitors to a variation and need to count them. Set the track parameter to false only if you call these methods before you expose visitors.For example, if you call get_variations to retrieve all variations before you expose visitors, set the track parameter to false. This setting prevents Kameleoon from prematurely counting a session. You can then trigger tracking later when you explicitly expose the visitor.Kameleoon sends tracking data every second by default. You can configure this interval up to five seconds using the tracking interval configuration option. Kameleoon groups tracking events into a single session as long as the interval between events is less than 30 minutes. If more than 30 minutes elapse between tracking events, Kameleoon counts the events as separate sessions. A visit appears in your reports 30 minutes after the last recorded event in the session.

The is_feature_active? method evaluates the served variant, not the master flag state. If you exclude rules, the method uses the Then, for everyone else serve default state. If you select Off for this default state, the method always returns false even when the master feature flag is On.

alias Kameleoon.Client

feature_key = "new_checkout"

# Evaluates the feature flag and sends tracking data (default behavior)
{:ok, active?} = Client.is_feature_active?(client, visitor_code, feature_key)

# Evaluates the feature flag without sending tracking data
{:ok, active_without_tracking?} = Client.is_feature_active?(client, visitor_code, feature_key, track: false)

Parameters

Name	Type	Description	Default
`visitor_code` required	`String.t()`	Unique identifier of the user.
`feature_key` required	`String.t()`	Key of the feature to evaluate for the user.
`track` optional	`boolean()`	Enables or disables tracking of the feature evaluation.	`true`

Return value

Type	Description
`{:ok, boolean()} \| {:error, Error.t()}`	Indicates whether the feature flag is active for the specified `visitor_code`, or returns an error.

Errors

Type	Description
`Initialization`	Indicates that the SDK is not yet fully initialized.
`FeatureNotFound`	Exception indicating that the requested feature key wasn’t found in the internal configuration of the SDK. This usually means that the feature flag is not activated in the Kameleoon app (but code implementing the feature is already deployed in the application).
`VisitorCodeInvalid`	Exception indicating that the provided visitor code is not valid. It is either empty or longer than 255 characters.

get_variation()

📨 Sends Tracking Data to Kameleoon (depending on the track parameter)

Retrieves the Variation assigned to a given visitor for a specific feature flag. This method takes a visitor_code and feature_key as mandatory arguments. The track argument is optional and defaults to true. It returns the assigned Variation for the visitor. If the visitor is not associated with any feature flag rules, the method returns the default Variation for the given feature flag. Ensure that proper error handling is implemented in your code to manage potential exceptions.

The default variation refers to the variation assigned to a visitor when they do not match any predefined delivery rules for a feature flag. In other words, it is the fallback variation applied to all users who are not targeted by specific rules. It’s represented as the variation in the “Then, for everyone else…” section in a management interface.

alias Kameleoon.Client

feature_key = "new_checkout"

# Retrieves the variation assigned to the visitor (with tracking enabled by default)
{:ok, variation} = Client.get_variation(client, visitor_code, feature_key)

# Retrieves the variation without sending tracking data
{:ok, variation_without_tracking} =
  Client.get_variation(client, visitor_code, feature_key, track: false)

Parameters

Name	Type	Description	Default
`visitor_code` required	`String.t()`	Unique identifier of the visitor.
`feature_key` required	`String.t()`	Key of the feature you want to expose to a visitor.
`track` optional	`boolean()`	An optional parameter to enable or disable tracking of the feature evaluation.	`true`

Return value

Type	Description
`{:ok, Variation.t()} \| {:error, Error.t()}`	An assigned `Variation` to a given visitor for a specific feature flag on success, otherwise an error.

Errors

Type	Description
`Initialization`	Indicates that the SDK is not yet fully initialized.
`VisitorCodeInvalid`	Exception indicating that the provided visitor code is not valid. It is either empty or longer than 255 characters.
`FeatureNotFound`	Exception indicating that the requested feature key wasn’t found in the internal configuration of the SDK. This usually means that the feature flag is not activated in the Kameleoon app (but code implementing the feature is already deployed in the application).
`FeatureEnvironmentDisabled`	Exception indicating that feature flag is disabled for the visitor’s current environment (for example, production, staging, or development).
`FeatureEvaluationBlocked`	Exception indicating that feature evaluation is blocked. The reason is described in the error message. This usually occurs due to GDPR restrictions when the visitor has not provided legal consent.

get_variations()

📨 Sends Tracking Data to Kameleoon (depending on the track parameter)

Retrieves a map of Variation objects assigned to a given visitor across all feature flags. This method iterates over all available feature flags and returns the assigned Variation for each flag associated with the specified visitor. It takes visitor_code as a mandatory argument, while only_active and track are optional.

If only_active is set to true, the method get_variations will return feature flags variations provided the user is not bucketed with the off variation.
The track parameter controls whether or not the method will track the variation assignments. By default, it is set to true. If set to false, the tracking will be disabled.

The returned map consists of feature flag keys as keys and their corresponding Variation as values. If no variation is assigned for a feature flag, the method returns the default Variation for that flag. Proper error handling should be implemented to manage potential exceptions.

alias Kameleoon.Client

# Retrieves all variations assigned to the visitor (with default options)
{:ok, variations} = Client.get_variations(client, visitor_code)

# Retrieves only active variations for the visitor
{:ok, only_active_variations} = Client.get_variations(client, visitor_code, only_active: true)

# Retrieves variations without sending tracking data
{:ok, variations_without_tracking} = Client.get_variations(client, visitor_code, track: false)

Parameters

Name	Type	Description	Default
`visitor_code` required	`String.t()`	Unique identifier of the visitor.
`only_active` optional	`boolean()`	An optional parameter indicating whether to return variations for active (`true`) or all (`false`) feature flags.	`false`
`track` optional	`boolean()`	An optional parameter to enable or disable tracking of the feature evaluation.	`true`

Return value

Type	Description
`{:ok, %{String.t() => Variation.t()}} \| {:error, Error.t()}`	Map that contains the assigned `Variation` objects of the feature flags using the keys of the corresponding features on success, otherwise an error.

Errors

Type	Description
`Initialization`	Indicates that the SDK is not yet fully initialized.
`VisitorCodeInvalid`	Exception indicating that the provided visitor code is not valid. It is either empty or longer than 255 characters.

set_forced_variation()

The method allows you to programmatically assign a specific Variation to a user, bypassing the standard evaluation process. This is especially valuable for controlled experiments where the usual evaluation logic is not required or must be skipped. It can also be helpful in scenarios like debugging or custom testing. When a forced variation is set, it overrides Kameleoon’s real-time evaluation logic. Processes like segmentation, targeting conditions, and algorithmic calculations are skipped. To preserve segmentation and targeting conditions during an experiment, set force_targeting=false instead.

Simulated variations always take precedence in the execution order. If a simulated variation calculation is triggered, it will be fully processed and completed first.

A forced variation is treated the same as an evaluated variation. It is tracked in analytics and stored in the user context like any standard evaluated variation, ensuring consistency in reporting. The method may throw exceptions under certain conditions (e.g., invalid parameters, user context, or internal issues). Proper exception handling is essential to ensure that your application remains stable and resilient.

It’s important to distinguish forced variations from simulated variations:

Forced variations: Are specific to an individual experiment.
Simulated variations: Affect the overall feature flag result.

alias Kameleoon.Client

experiment_id = 202_387

# Forces the visitor into "variation_2" for the given experiment
:ok = Client.set_forced_variation(client, visitor_code, experiment_id, "variation_2")

# Removes any previously forced variation for the visitor in this experiment
:ok = Client.set_forced_variation(client, visitor_code, experiment_id, nil)

# Forces the visitor into "variation_2" with custom options.
# In this case, targeting rules are respected (force_targeting = false).
:ok =
  Client.set_forced_variation(
    client, visitor_code, experiment_id, "variation_2", force_targeting: false
  )

Parameters

Name	Type	Description	Default
`visitor_code` required	`String.t()`	Unique identifier of the visitor.
`experiment_id` required	`non_neg_integer()`	Experiment Id that will be targeted and selected during the evaluation process.
`variation_key` required	`String.t() \| nil`	Variation Key corresponding to a `Variation` that should be forced as the returned value for the experiment. If the value is `nil`, the forced variation will be reset.
`force_targeting` optional	`boolean()`	Indicates whether targeting for the experiment should be forced and skipped (`true`) or applied as in the standard evaluation process (`false`).	`true`

Return value

Type	Description
`:ok \| {:error, Error.t()}`	Indicates whether the forced variation was successfully set or an error occurred.

Errors

Type	Description
`Initialization`	Indicates that the SDK is not yet fully initialized.
`VisitorCodeInvalid`	Exception indicating that the provided visitor code is not valid. It is either empty or longer than 255 characters.
`FeatureExperimentNotFound`	Exception indicating that the requested experiment id has not been found in the SDK’s internal configuration. This is usually normal and means that the rule’s corresponding experiment has not yet been activated on Kameleoon’s side.
`FeatureVariationNotFound`	Exception indicating that the requested variation key(id) has not been found in the internal configuration of the SDK. This is usually normal and means that the variation’s corresponding experiment has not yet been activated on Kameleoon’s side.

evaluate_audiences()

📨 Sends Tracking Data to Kameleoon

This method evaluates visitors against all available Audiences Explorer segments and tracks those who match. evaluate_audiences should be called after all relevant visitor data has been set or updated, and just before getting a feature variation or checking a feature flag. This approach ensures that the visitor is evaluated against the most current data available, allowing for accurate audience assignment based on all criteria. After calling this method, you can perform a detailed analysis of segment performance in Audiences Explorer.

alias Kameleoon.Client

:ok = Client.evaluate_audiences(client, visitor_code)

Parameters

Name	Type	Description
`visitor_code` required	`String.t()`	Unique identifier of the visitor.

Return value

Type	Description
`:ok \| {:error, Error.t()}`	Indicates whether audience evaluation succeeded or an error occurred.

Errors

Type	Description
`VisitorCodeInvalid`	Exception indicating that the provided visitor code is not valid. It is either empty or longer than 255 characters.

get_datafile()

To evaluate all feature flags, use get_variations. This method is more efficient than calling DataFile and iterating through flags with get_variation.

Returns the current SDK configuration as a DataFile object.

alias Kameleoon.Client

{:ok, datafile} = Client.get_datafile(client)

Return value

Type	Description
`{:ok, DataFile.t()} \| {:error, Error.t()}`	The `DataFile` containing the SDK configuration on success, otherwise an error.

Errors

Type	Description
`Initialization`	Indicates that the SDK is not yet fully initialized.

Visitor data

get_visitor_code()

Use get_visitor_code() to obtain the current visitor’s Kameleoon visitor_code. The method works with any cookie store that implements the Kameleoon.CookieAccessor behaviour. The implementation logic is as follows:

The SDK checks whether a kameleoonVisitorCode cookie is already available through the provided accessor.
If the cookie is absent, the SDK uses default_visitor_code when you provide one.
Otherwise, the SDK generates a new visitor code and stores it through the accessor.

For more information, refer to Hybrid experimentation.

If you provide your own visitor_code, its uniqueness must be guaranteed on your side. Also note that the length of visitor_code is limited to 255 characters.

The get_visitor_code method allows you to set simulated variations for a visitor. When cookies (from a request or document) contain the key kameleoonSimulationFFData, the standard evaluation process is bypassed. Instead, the method directly returns a Variation based on the provided data.You can apply simulations in two ways:

Automatically (recommended): If using Kameleoon Web Experimentation or the SDK in Hybrid mode, the cookie is created automatically when simulating a variant’s display using the Simulation Panel.
Manually: Set the kameleoonSimulationFFData cookie manually.

It’s important to distinguish simulated variations from forced variations:

Simulated variations: Affect the overall feature flag result.
Forced variations: Are specific to an individual experiment.

⚙️ Manual setupPlease ensure the kameleoonSimulationFFData cookie follows this format:

kameleoonSimulationFFData={"featureKey":{"expId":10,"varId":20}}: Simulates the variation with varId of experiment expId for the given featureKey.
kameleoonSimulationFFData={"featureKey":{"expId":0}}: Simulates the default variation (defined in the Then, for everyone else in Production, serve section) for the given featureKey.

⚠️ To ensure proper functionality, the cookie value must be encoded as a URI component using a method such as encodeURIComponent.

Custom
Plug.Conn

alias Kameleoon.Client

defmodule MemoryCookies do
  @behaviour Kameleoon.CookieAccessor

  @impl true
  def get(cookies, key), do: Map.get(cookies, key)

  @impl true
  def set(cookies, key, value, _max_age, _top_level_domain) do
    Map.put(cookies, key, value)
  end
end


# Generate or retrieve a visitor code using an auto-generated value.
cookies = %{}
{:ok, visitor_code, cookies} = Client.get_visitor_code(client, {MemoryCookies, cookies})

# Generate or retrieve a visitor code using a predefined user ID.
cookies = %{}
{:ok, visitor_code, cookies} = Client.get_visitor_code(client, {MemoryCookies, cookies}, "user_id")

alias Kameleoon.Client

defmodule PlugConnCookies do
  @behaviour Kameleoon.CookieAccessor

  @impl true
  def get(conn, key), do: conn.req_cookies[key]

  @impl true
  def set(conn, key, value, max_age, top_level_domain) do
    opts = [path: "/", max_age: max_age]
    opts = if top_level_domain, do: Keyword.put(opts, :domain, top_level_domain), else: opts

    Plug.Conn.put_resp_cookie(conn, key, value, opts)
  end
end

def get_visitor_code(conn, client) do
  cookies = {PlugConnCookies, conn}

  with {:ok, visitor_code, conn} <- Client.get_visitor_code(client, cookies) do
    {:ok, visitor_code, conn}
  end
end

Parameters

Name	Type	Description
`cookies` required	`{module(), term()}`	Cookie accessor module and framework-specific state used to read and store the visitor cookie.
`default_visitor_code` optional	`String.t() \| nil`	Visitor code to use when no cookie is present.

Return value

Type	Description
`{:ok, String.t(), term()} \| {:error, Error.t()}`	String representing a unique visitor code used in SDK on success, otherwise an error.

add_data()

The Client.add_data method adds targeting data to storage so other methods can use the data to decide whether or not to target the current visitor. The Client.add_data method does not return any value and does not interact with Kameleoon back-end servers on its own. Instead, all the declared data is saved for future transmission using the flush method. This approach reduces the number of server calls made, as the data is typically grouped into a single server call that is triggered by the flush. The track_conversion method also sends out any previously associated data, just like the flush. The same holds true for get_variation and get_variations methods if an experimentation rule is triggered.

Each visitor can only have one instance of associated data for most data types. However, CustomData is an exception. Visitors can have one instance of associated CustomData per index.

alias Kameleoon.Client
alias Kameleoon.Data.Browser
alias Kameleoon.Data.PageView
alias Kameleoon.Data.UserAgent

:ok = Client.add_data(client, visitor_code, Browser.new!(:chrome, version: 123.0))

:ok =
  Client.add_data(client, visitor_code, [
    PageView.new!("https://example.com/pricing", title: "Pricing", referrers: [3]),
    UserAgent.new!("Mozilla/5.0")
  ])

:ok =
  Client.add_data(
    client,
    visitor_code,
    PageView.new!("https://example.com/checkout", title: "Checkout"),
    track: false
  )

Parameters

Name	Type	Description	Default value
`visitor_code` required	`String.t()`	Unique identifier of the visitor.
`data` required	`struct() \| [struct()]`	Collection of Kameleoon data types.
`track` optional	`boolean()`	Specifies whether the added data is eligible for tracking. When set to `false`, the data is stored locally and used only for targeting evaluation; it is not sent to the Kameleoon Data API.	`true`

Return value

Type	Description
`:ok \| {:error, Error.t()}`	Indicates whether data was successfully added or an error occurred.

Errors

Type	Description
`Initialization`	Indicates that the SDK is not yet fully initialized.
`VisitorCodeInvalid`	Exception indicating that the provided visitor code is not valid. It is either empty or longer than 255 characters.

flush()

📨 Sends tracking data to Kameleoon

The flush() method aggregates all Kameleoon data associated with a visitor and sends a tracking request to the server. This request includes any data previously added via the add_data method that has not yet been transmitted through other tracking mechanisms (see the referenced methods for details). The flush() operation is non-blocking, as the server call is performed asynchronously. This method provides control over when data linked to a specific visitor_code is transmitted. For example, if add_data() is called multiple times, sending a request after each invocation would be inefficient. Instead, you can batch these updates and call flush() once to send all accumulated data in a single request. The flush() method uses the provided visitor_code as the unique visitor identifier.

flush() — Queues a flush operation according to the configured tracking interval.
flush_instant() — Sends tracking data immediately without waiting for the interval.

alias Kameleoon.Client

# Queues a flush operation for the given visitor_code.
# Data will be sent according to the configured tracking interval.
:ok = Client.flush(client, visitor_code)

# Immediately sends all pending tracking data for the given visitor_code.
:ok = Client.flush_instant(client, visitor_code)

Parameters

Name	Type	Description
`visitor_code` required	`String.t()`	Unique identifier of the visitor.

Return value

Type	Description
`:ok \| {:error, Error.t()}`	Indicates whether the operation was successfully scheduled or executed, or if an error occurred.

Errors

Type	Description
`Initialization`	Indicates that the SDK is not yet fully initialized.
`VisitorCodeInvalid`	Exception indicating that the provided visitor code is not valid. It is either empty or longer than 255 characters.

get_remote_data()

The get_remote_data() method lets you retrieve remote data stored on Kameleoon servers for the specified key. In most setups, this data is written through the Kameleoon Data API and can later be fetched by your Elixir service whenever you need additional application context. This method is useful when you want to keep structured information on Kameleoon’s remote infrastructure and reuse it from your back-end without maintaining a separate retrieval mechanism.

alias Kameleoon.Client

{:ok, data} = Client.get_remote_data(client, "test-key")

Parameters

Name	Type	Description
`key` required	`String.t()`	Key associated with the remote data you want to retrieve.

Return value

Type	Description
`{:ok, String.t()\} \| {:error, Error.t()}`	Payload associated with the specified `key` on success, otherwise an error. In most cases, the payload is JSON serialized as a string.

Errors

Type	Description
`Initialization`	Indicates that the SDK is not yet fully initialized.
`Network`	Returned when the remote data request fails or the server responds with a non-success status code.

get_remote_visitor_data()

get_remote_visitor_data() retrieves Kameleoon visit data for the provided visitor_code. The method adds the data to local visitor storage so other SDK methods can use it for targeting decisions. Data obtained using this method is especially useful when you want to:

use data collected from other devices.
access a visitor’s history, such as previously viewed pages from past visits.
use data that is only available on the client side, such as datalayer variables and front-end goal conversions.

Read this article for a better understanding of possible use cases.

By default, get_remote_visitor_data() automatically retrieves the latest stored custom data with scope=Visitor and attaches it to the visitor without the need to call add_data(). This is especially useful for synchronizing custom data across multiple devices.

alias Kameleoon.Client
alias Kameleoon.Types.RemoteVisitorDataFilter

# Fetch remote visitor data without any filter.
# This will return all available data for the given visitor.
:ok = Client.get_remote_visitor_data(client, visitor_code)

# Create a filter to limit the returned data.
filter = %RemoteVisitorDataFilter{
  # Include data from the last 5 visits
  previous_visit_amount: 5,
  # Include conversion events (e.g., goals, transactions)
  conversions: true,
  # Include page view history
  page_views: true
}

# Fetch remote visitor data using the specified filter.
# This will return only the data matching the filter criteria.
:ok = Client.get_remote_visitor_data(client, visitor_code, filter: filter)

Parameters

Name	Type	Description	Default
`visitor_code` required	`String.t()`	Visitor code whose data should be fetched.
`filter` optional	`RemoteVisitorDataFilter.t() \| nil`	Filter describing which remote visitor data should be retrieved.	`%RemoteVisitorDataFilter{}`

Return value

Type	Description
`:ok \| {:error, Error.t()}`	Returns successfully when the data is fetched and added locally, otherwise an error.

Errors

Type	Description
`Initialization`	Indicates that the SDK is not yet fully initialized.
`VisitorCodeInvalid`	Exception indicating that the provided visitor code is not valid. It is either empty or longer than 255 characters.
`Network`	Returned when the remote visitor data request fails, cannot be parsed, or the server responds with a non-success status code.

Using parameters in get_remote_visitor_data()

The get_remote_visitor_data() method lets you control which data is retrieved for a visitor. The same filtering approach works across goals, experiments, variations, and other visitor data. For example, if you want to target users who converted on a goal during their last five visits, you can set previous_visit_amount to 5 and conversions to true. The flexibility shown in this example is not limited to goal data. You can use the filter to retrieve many different visitor behaviors and make them available to targeting and reporting logic in your Elixir application.

`RemoteVisitorDataFilter` fields

Name	Type	Description	Default
`previous_visit_amount`	`non_neg_integer()`	Number of previous visits to retrieve data from.	`1`
`current_visit`	`boolean()`	If `true`, current visit data will be retrieved.	`true`
`custom_data`	`boolean()`	If `true`, custom data will be retrieved.	`true`
`visitor_code`	`boolean()`	If `true`, the most recent visitor code will be reused.	`true`
`page_views`	`boolean()`	If `true`, page view data will be retrieved.	`false`
`geolocation`	`boolean()`	If `true`, geolocation data will be retrieved.	`false`
`device`	`boolean()`	If `true`, device data will be retrieved.	`false`
`browser`	`boolean()`	If `true`, browser data will be retrieved.	`false`
`operating_system`	`boolean()`	If `true`, operating system data will be retrieved.	`false`
`conversions`	`boolean()`	If `true`, conversion data will be retrieved.	`false`
`experiments`	`boolean()`	If `true`, experiment data will be retrieved.	`false`
`kcs`	`boolean()`	If `true`, Kameleoon Conversion Score data will be retrieved.	`false`
`personalizations`	`boolean()`	If `true`, personalization data will be retrieved.	`false`
`cbs`	`boolean()`	If true, Contextual Bandit score data will be retrieved.	`false`

get_visitor_warehouse_audience()

This method retrieves audience data associated with a visitor in your warehouse integration by using the specified visitor_code and, optionally, a warehouse_key. The warehouse_key is typically your internal user ID. The custom_data_index parameter corresponds to the Kameleoon custom data that Kameleoon uses to target your visitors. When the call succeeds, the SDK converts the returned audience list into CustomData, adds it to the visitor locally, and makes it available for targeting purposes. For more background, see the warehouse targeting documentation.

alias Kameleoon.Client

# Fetch audience data for a visitor using only the visitor_code.
:ok = Client.get_visitor_warehouse_audience(client, visitor_code, 98)

# Fetch audience data for a visitor using both visitor_code and warehouse_key.
# Useful when your warehouse uses a different identifier than visitor_code.
:ok = Client.get_visitor_warehouse_audience(client, visitor_code, 98, warehouse_key: "internal-user-id")

Parameters

Name	Type	Description	Default
`visitor_code` required	`String.t()`	Visitor whose warehouse audiences should be retrieved.
`custom_data_index` required	`non_neg_integer()`	Custom data index configured in Kameleoon for warehouse audience targeting.
`warehouse_key` optional	`String.t() \| nil`	External warehouse key, usually your internal user ID.	`visitor_code`

Return value

Type	Description
`:ok \| {:error, Error.t()}`	Success when the warehouse audience data is retrieved and stored locally as `CustomData`.

Errors

Type	Description
`Initialization`	Indicates that the SDK is not yet fully initialized.
`VisitorCodeInvalid`	Exception indicating that the provided visitor code is not valid. It is either empty or longer than 255 characters.
`Network`	Returned when the warehouse audience request fails, cannot be parsed, or the server responds with a non-success status code.

set_legal_consent()

You must use this method to specify whether the visitor has given legal consent to use personal data. Setting legal_consent to false limits the types of data that can be included in tracking requests. This helps you adhere to legal and regulatory requirements while responsibly managing visitor data. For more information, see the consent management policy. The Elixir SDK updates visitor cookies through the required Kameleoon.CookieAccessor adapter and returns the updated adapter state.

alias Kameleoon.Client

cookies = {PlugConnCookies, conn}

# Set consent and update cookies.
{:ok, conn} = Client.set_legal_consent(client, visitor_code, true, cookies)

# Set consent without updating cookies
{:ok, _} = Client.set_legal_consent(client, visitor_code, true, nil)

Parameters

Name	Type	Description	Default
`visitor_code` required	`String.t()`	The user’s unique identifier.
`consent` required	`boolean()`	`true` indicates the visitor has given legal consent, `false` indicates the visitor has never provided, or has withdrawn, legal consent.
`cookies` optional	`{module(), term()}`	Cookie accessor module and framework-specific state used to update cookies.	`nil`

Return value

Type	Description
`{:ok, term()} \| {:error, Error.t()}`	Returns the updated cookie state when the visitor consent state was updated successfully, otherwise an error.

Errors

Type	Description
`Initialization`	Indicates that the SDK is not yet fully initialized.
`VisitorCodeInvalid`	Exception indicating that the provided visitor code is not valid. It is either empty or longer than 255 characters.

Consent revocation behavior

When you call set_legal_consent with legal_consent=false, the SDK does not delete the kameleoonVisitorCode cookie. Instead, it stops extending the cookie’s expiration date, allowing the cookie to persist until it naturally expires. If your compliance requirements demand the immediate removal of the cookie file upon opt-out, you must delete it manually using your framework’s native cookie management methods. The SDK will not remove the file automatically.

Goals and third-party analytics

track_conversion()

📨 Sends Tracking Data to Kameleoon

Use this method to track a conversion for a specific goal and user. This method requires visitor_code and goal_id. In addition, this method also accepts an optional revenue, negative and metadata arguments. The visitor_code is usually identical to the one that was used when triggering the experiment.

This method is non-blocking as the server call is made asynchronously.

alias Kameleoon.Client
alias Kameleoon.Data.CustomData

# Track a goal.
:ok = Client.track_conversion(client, visitor_code, goal_id)

# Track a goal with revenue.
:ok = Client.track_conversion(client, visitor_code, goal_id, revenue: 100.0)

# Track a goal with negative revenue.
:ok = Client.track_conversion(client, visitor_code, goal_id, revenue: 100.0, negative: true)

# Track a goal with custom metadata.
:ok =
  Client.track_conversion(
    client,
    visitor_code,
    goal_id,
    metadata: [CustomData.new!(4, ["true"])]
  )

Parameters

Name	Type	Description	Default
`visitor_code` required	`String.t()`	Unique identifier of the visitor.
`goal_id` required	`non_neg_integer()`	ID of the goal.
`revenue` optional	`number() \| nil`	Revenue of the conversion.	`0`
`negative` optional	`boolean()`	Defines if the revenue is positive or negative.	`false`
`metadata` optional	`[CustomData.t()]`	Metadata of the conversion. Must be defined beforehand in the Kameleoon App.	`[]`

metadata values are accessible through raw data exports and the results page.If the metadata parameter is provided, Kameleoon will use these specified values for the current conversion instead of what was previously collected using the Client.add_data method. If the parameter is omitted, Kameleoon will use the last tracked values for those CustomData prior to the conversion and within the same visit.Kameleoon will only consider the metadata values that are explicitly passed as parameters to the track_conversion method.In the example below, Kameleoon will associate the conversion only with the custom data value explicitly provided as a parameter (here: index 5 with the value ‘Amex Credit Card’).

:ok =
  Client.add_data(client, visitor_code, [
    CustomData.new!(5, ["Credit Card"]),
    CustomData.new!(9, ["Express Delivery"])
  ])

:ok =
  Client.track_conversion(
    client, visitor_code, goal_id, metadata: [CustomData.new!(5, ["Amex Credit Card"])]
  )

Return value

Type	Description
`:ok \| {:error, Error.t()}`	Indicates whether the conversion was successfully queued for asynchronous tracking, otherwise an error.

Errors

Type	Description
`Initialization`	Indicates that the SDK is not yet fully initialized.
`VisitorCodeInvalid`	Exception indicating that the provided visitor code is not valid. It is either empty or longer than 255 characters.

get_engine_tracking_code()

Kameleoon integrates with several analytics solutions, including Mixpanel, Google Analytics 4, and Segment. To track server-side experiments correctly, call the get_engine_tracking_code method after the visitor triggers an experiment. The SDK returns JavaScript queue commands for the experiments that the visitor triggered during the previous five seconds. When you insert this code into the page, Engine.js processes the commands and sends the exposure events through the active analytics integration. Refer to hybrid experimentation for more information on implementing this method.

alias Kameleoon.Client

{:ok, tracking_code} = Client.get_engine_tracking_code(client, visitor_code)

To use this feature, implement both the Elixir SDK and Kameleoon Engine.js. Because Engine.js is used only for tracking in this flow, you can install the asynchronous tag before the closing </body> tag.
If you only want to track experiments in Kameleoon and do not need to send exposure events to third-party analytics tools, use the JavaScript / TypeScript SDK. This option works well for serverless edge compute platforms. The JavaScript / TypeScript SDK automatically tracks variations when you call getVisitorCode, as long as you add the corresponding experiment assignments to window.kameleoonQueue.
You can insert the returned tracking code directly into an HTML <script> tag.

<html lang="en">
  <body>
    <script>
      const engineTrackingCode = `
        window.kameleoonQueue = window.kameleoonQueue || [];
        window.kameleoonQueue.push(['Experiments.assignVariation', 123456, 7890, true]);
        window.kameleoonQueue.push(['Experiments.trigger', 123456, true]);
        window.kameleoonQueue.push(['Experiments.assignVariation', 234567, 8901, true]);
        window.kameleoonQueue.push(['Experiments.trigger', 234567, true]);
      `;
      const script = document.createElement('script');

      script.textContent = engineTrackingCode;
      document.body.appendChild(script);
    </script>

  </body>
</html>

In this example, 123456 and 234567 are experiment IDs, and 7890 and 8901 are variation IDs. In your implementation, the SDK generates these values in the returned tracking code.

Parameters

Name	Type	Description
`visitor_code` required	`String.t()`	Unique identifier of the visitor.

Return value

Type	Description
`{:ok, String.t()} \| {:error, Error.t()}`	JavaScript code to insert into the page on success; otherwise, an error.

Errors

Type	Description
`Initialization`	Indicates that the SDK is not yet fully initialized.
`VisitorCodeInvalid`	Exception indicating that the provided visitor code is not valid. It is either empty or longer than 255 characters.

Events

on_datafile_update()

The on_datafile_update method allows you to handle the event when configuration has updated data. It takes one input parameter, handler. The handler that will be called when the configuration is updated using a real-time configuration event.

alias Kameleoon.Client

# Register a callback that is invoked whenever the configuration
# is updated through a polling or streaming datafile update event.
:ok =
  Client.on_datafile_update(client, fn ->
    # Custom logic to execute after the datafile has been updated.
    IO.puts("Kameleoon datafile updated")
  end)

# Unregister the datafile update callback.
# No callback will be invoked for future datafile updates.
:ok = Client.on_datafile_update(client, nil)

Parameters

Name	Type	Description
`handler`	`(() -> any()) \| nil`	The handler that will be called when the configuration is updated using a real-time configuration event.

Data types

This section lists the Elixir data types available under Kameleoon.Data.

ApplicationVersion

ApplicationVersion represents the semantic version number of your application.

A visitor can have only one ApplicationVersion. Adding a second instance will overwrite the first one.

Name	Type	Description
`version` required	`String.t()`	The application version. This field must follow semantic versioning. Accepted formats are `major`, `major.minor`, or `major.minor.patch`.

alias Kameleoon.Client
alias Kameleoon.Data.ApplicationVersion

# major
:ok = Client.add_data(client, visitor_code, ApplicationVersion.new!("10"))
# major.minor
:ok = Client.add_data(client, visitor_code, ApplicationVersion.new!("10.20"))
# major.minor.patch
:ok = Client.add_data(client, visitor_code, ApplicationVersion.new!("10.20.30"))

Browser

The Browser data set stored here can be used to filter experiment and personalization reports by any value associated with it.

Name	Type	Description
`type` required	`browser_type()`	List of browsers: `:chrome`, `:internet_explorer`, `:firefox`, `:safari`, `:opera`, `:other`.
`version` optional	`number() \| nil`	Version of the browser, floating point number represents major and minor version of the browser

alias Kameleoon.Client
alias Kameleoon.Data.Browser

# Browser data with a version
:ok = Client.add_data(client, visitor_code, Browser.new!(:safari, version: 26.4))
# Browser data without a version
:ok = Client.add_data(client, visitor_code, Browser.new!(:chrome))

Conversion

The Conversion data set stored here can be used to filter experiment and personalization reports by any goal associated with it.

Each visitor can have multiple Conversion objects.
You can find the goal_id in the Kameleoon app.

Name	Type	Description	Default
`goal_id` required	`non_neg_integer()`	ID of the goal.
`revenue` optional	`number() \| nil`	Revenue of the conversion	`0`
`negative` optional	`boolean()`	Defines if the revenue is positive or negative.	`false`
`metadata` optional	`[CustomData.t()]`	Metadata of the conversion.	`[]`

alias Kameleoon.Client
alias Kameleoon.Data.Conversion
alias Kameleoon.Data.CustomData

# Add a simple conversion with ID 32
:ok = Client.add_data(client, visitor_code, Conversion.new!(32))

# Add conversion with ID 33 including revenue and marked as negative
:ok = Client.add_data(client, visitor_code, Conversion.new!(33, revenue: 10.0, negative: true))

# Add conversion with ID 34 including revenue, negative flag, and custom metadata
:ok =
  Client.add_data(
    client,
    visitor_code,
    Conversion.new!(34,
      revenue: 10.0,
      negative: true,
      metadata: [
        CustomData.new!(3, ["metadata1", "md2"]),
        CustomData.new!(5, ["md3"])
      ]
    )
  )

Cookie contains information about the cookies stored on the visitor’s device.

Name	Type	Description
`cookies`	`%{String.t() => String.t()}`	A string map containing cookie keys and values.

Each visitor can only have one Cookie. Adding a second Cookie overwrites the first one.

alias Kameleoon.Client
alias Kameleoon.Data.Cookie

:ok = Client.add_data(client, visitor_code, Cookie.new!(%{"segment" => "vip"}))

CustomData

CustomData enables the association of any type of data with each visitor, making it an effective tool for targeting conditions in segments. Additionally, it can be used as a filter or breakdown in experiment reports. For more information about custom data, please refer to this article. Define custom data types in the Kameleoon app or the Data API and use them from the SDK.

Name	Type	Description	Default
`index`/`name` required	`non_neg_integer()`/`String.t()`	Index or Name of the custom data. Either `index` or `name` must be provided to identify the data.
`values` required	`[String.t()]`	Values of the custom data to be stored.
`overwrite` optional	`boolean()`	Flag to explicitly control how the values are stored and how they appear in reports. See more	`true`

Each visitor is allowed only one CustomData for each unique index(name). Adding another CustomData with the same index(name) will replace the existing one.
The custom data ‘index’ can be found in the Custom Data dashboard under the “INDEX” column.
To prevent the SDK from sending data with the selected index to Kameleoon servers for privacy reasons, enable the option: Use this data only locally for targeting purposes when creating custom data.
Adding a CustomData instance created with a name when the SDK instance is not initialized or the name is not registered, will result in the data being ignored.

alias Kameleoon.Client
alias Kameleoon.Data.CustomData

:ok = Client.add_data(client, visitor_code, CustomData.new!(1, ["value"]))

# With several values
:ok = Client.add_data(client, visitor_code, CustomData.new!(1, ["value1", "value2"]))

# To set the `overwrite` flag to false
:ok = Client.add_data(client, visitor_code, CustomData.new!(1, ["value"], overwrite: false))

# To use a name instead of the index
:ok = Client.add_data(client, visitor_code, CustomData.new_with_name!("my-custom-data", ["value"]))

# To use a name instead of the index and set the `overwrite` flag to false
:ok =
  Client.add_data(
    client, visitor_code, CustomData.new!("my-custom-data", ["value"], overwrite: false)
  )

Device

You can use device data to filter experiment and personalization reports by any associated value.

Name	Type	Description
`type`	`device_type()`	Device type. Possible values are `:phone`, `:tablet`, and `:desktop`.

alias Kameleoon.Client
alias Kameleoon.Data.Device

:ok = Client.add_data(client, visitor_code, Device.new!(:desktop))

Geolocation

Geolocation contains the visitor’s geolocation details.

Name	Type	Description
`country` required	`String.t()`	The country of the visitor.
`region` optional	`String.t() \| nil`	The region of the visitor.
`city` optional	`String.t() \| nil`	The city of the visitor.
`postal_code` optional	`String.t() \| nil`	The postal code of the visitor.
`latitude` optional	`number() \| nil`	The latitude coordinate representing the location of the visitor. Coordinate number represents decimal degrees.
`longitude` optional	`number() \| nil`	The longitude coordinate representing the location of the visitor. Coordinate number represents decimal degrees.

Each visitor can have only one Geolocation. Adding a second Geolocation overwrites the first one.

alias Kameleoon.Client
alias Kameleoon.Data.Geolocation

geolocation =
  Geolocation.new!("France",
    region: "Ile-de-France",
    city: "Paris",
    postal_code: "75009",
    latitude: 48.8720171,
    longitude: 2.3338352
  )

:ok = Client.add_data(client, visitor_code, geolocation)

OperatingSystem

OperatingSystem contains information about the operating system on the visitor’s device.

Name	Type	Description
`type`	`operating_system_type()`	Operating system family. Possible values are `:windows`, `:mac`, `:ios`, `:linux`, `:android`, and `:windows_phone`.

Each visitor can only have one OperatingSystem. Adding a second OperatingSystem overwrites the first one.

alias Kameleoon.Client
alias Kameleoon.Data.OperatingSystem

:ok = Client.add_data(client, visitor_code, OperatingSystem.new!(:windows))

PageView

Store page view events.

Name	Type	Description	Default
`url`	`String.t()`	URL of the page viewed.
`title`	`String.t() \| nil`	Title of the page viewed.	`nil`
`referrers`	`[integer()]`	Referrer indices of previously viewed pages.	`[]`

The referrer index is available in the Kameleoon app on the acquisition channel configuration page. Be careful: the index starts at 0, so the first acquisition channel you create has the ID 0, not 1.

alias Kameleoon.Client
alias Kameleoon.Data.PageView

# Full constructor with url, optional title, and referrers.
:ok = Client.add_data(client, visitor_code, PageView.new!("https://example.com", title: "Homepage", referrers: [3]))

# Minimal constructor, only requires a URL.
:ok = Client.add_data(client, visitor_code, PageView.new!("https://example.com"))

UniqueIdentifier

If you do not add UniqueIdentifier for a visitor, visitor_code is used as the unique visitor identifier, which is useful for cross-device experimentation. When you add UniqueIdentifier.new!(true), the SDK links flushed data with the visitor associated with the specified identifier. This can be useful in situations where you cannot access the anonymous visitor_code originally assigned to a visitor, but you do have access to an internal identifier connected to that visitor through session merging.

Name	Type	Description
`value`	`boolean()`	Whether the current `visitor_code` should be treated as a unique identifier.

alias Kameleoon.Client
alias Kameleoon.Data.UniqueIdentifier

:ok = Client.add_data(client, visitor_code, UniqueIdentifier.new!(true))

UserAgent

Server-side experiments are more likely to be affected by bot traffic than client-side experiments. Kameleoon uses the IAB/ABC International Spiders and Bots List to recognize known bots and spiders, and it also uses the UserAgent field to filter out other unwanted traffic that might distort your conversion metrics. For more information, see the help article on bot filtering. If you use internal bots, we recommend sending the user-agent value curl/8.0 to exclude them from analytics.

Name	Type	Description
value	`String.t()`	User-Agent value sent with tracking requests.

alias Kameleoon.Client
alias Kameleoon.Data.UserAgent

:ok = Client.add_data(client, visitor_code, UserAgent.new!("Mozilla/5.0"))

Returned types

DataFile

The DataFile contains the SDK configuration details. It can be extended with additional information if required by clients. If you need more details, please contact your Customer Success Manager.

Name	Type	Description
`feature_flags`	`%{String.t() => FeatureFlag.t()}`	A map of `FeatureFlag` objects, keyed by feature flag keys.
`date_modified`	`non_neg_integer() \| nil`	The timestamp (in milliseconds) indicating when the `DataFile` was last modified.

# Retrieves the map of feature flags from the DataFile.
# The map is keyed by feature flag identifiers, with each value being a FeatureFlag struct.
feature_flags = datafile.feature_flags

# Retrieves the last modification timestamp of the DataFile.
# The value is an integer representing milliseconds since the Unix epoch.
date_modified = datafile.date_modified

FeatureFlag

The FeatureFlag represents a set of properties that define a feature flag itself — for example, its Variations, Rules, environment status, and other related details. It can be extended with additional information if required by clients. If you need more details, please contact your Customer Success Manager.

Name	Type	Description
`environment_enabled`	`boolean()`	Indicating whether the feature flag is enabled in the current environment.
`default_variation_key`	`String.t()`	The key of the default variation associated with the feature flag.
`variations`	`%{String.t() => Variation.t()}`	A map of `Variation` objects, keyed by variation keys.
`rules`	`[Rule.t()]`	A list of `Rule` objects

alias Kameleoon.Types.FeatureFlag

# Check whether the feature flag is enabled in the current environment.
environment_enabled = feature_flag.environment_enabled

# Retrieve the key of the default variation.
default_variation_key = feature_flag.default_variation_key

# Retrieve the default variation struct.
default_variation = FeatureFlag.default_variation(feature_flag)

# Retrieve all variations of the feature flag as a map (key = variation key, value = Variation struct).
variations = feature_flag.variations

# Retrieve all targeting rules associated with the feature flag.
rules = feature_flag.rules

Rule

The Rule represents a set of properties that define a rule itself — for example, its Variations. It can be extended with additional information if required by clients. If you need more details, please contact your Customer Success Manager.

Name	Type	Description
`variations`	`%{String.t() => Variation.t()}`	A map of `Variation` objects, keyed by variation keys.

# Retrieve all variations of the rule as a map (key = variation key, value = Variation struct).
variations = rule.variations

Variation

Variation contains information about the visitor’s assigned variation, or the default variation when no specific assignment exists.

Name	Type	Description
`name`	`String.t()`	The name of the variation.
`key`	`String.t()`	The unique key identifying the variation.
`id`	`non_neg_integer() \| nil`	The ID of the assigned variation, or `nil` for a default variation.
`experiment_id`	`non_neg_integer() \| nil`	The ID of the experiment associated with the variation, or `nil` for a default variation.
`variables`	`[Kameleoon.Types.Variable.t()]`	Variables associated with the variation. This collection can be empty when no variables are attached.

Variation describes the assigned or default variation, while Variable contains the details of each individual variable.
id and experiment_id can be nil, which indicates a default variation that is not tied to a specific experiment assignment.

Additional helper methods:

Method	Return type	Description
`Variation.active?`	`boolean()`	Returns `false` for the `off` variation.
`Variation.get_variable`	`Variable.t() \| nil`	Returns a variable by key, or `nil` if not found.

alias Kameleoon.Types.Variation

# Retrieving the variation name.
variation_name = variation.name

# Retrieving the variation key.
variation_key = variation.key

# Retrieving the variation id.
variation_id = variation.id

# Retrieving the experiment id.
experiment_id = variation.experiment_id

# Retrieving the variables list.
variables = variation.variables

# Checking if the variation is active.
active? = Variation.active?(variation)

# Retrieving a variable by its key, returning nil if not found.
variable = Variation.get_variable(variation, "title")

Variable

Variable contains information about a variable associated with the assigned variation.

Name	Type	Description
`key`	`String.t()`	The unique key identifying the variable.
`kind`	`String.t()`	The variable type. Possible values include `BOOLEAN`, `NUMBER`, `STRING`, `JSON`, `JS`, and `CSS`.
`value`	`boolean() \| number() \| String.t()`	The value of the variable. Depending on `kind`, it can hold a boolean, number, string, JSON string, JavaScript snippet, or CSS snippet.

# Retrieve the list of variables associated with the variation.
variables = variation.variables

# Access the variable type (kind) for conditional handling.
kind = variable.kind

# Extract the value as a number.
number = variable.value

# Extract the value as a boolean.
apply_discount? = variable.value

# Extract the value as a string.
title = variable.value

​Developer guide

​Getting started

​Install the Elixir client

​Additional configuration

​Initialize the Kameleoon client

​Activating a feature flag

Assigning a unique ID to a user

Retrieving a flag configuration

Adding data points to target a user or filter / breakdown visits in reports

Tracking goal conversions

Sending events to analytics solutions

​Using a custom bucketing key

​Use cases

​Technical details

​Technical requirements

​Targeting conditions

​Cross-device experimentation

​Synchronizing custom data across devices

​Using custom data for session merging

​Logging

​Log levels

​Custom handling of logs

​Reference

​Initialization

​create()

Parameters

Return value

Errors

​initialize()

Parameters

Return value

Errors

​is_ready()

Return value

​forget()

Parameters

Return value

​Feature flags and variations

​is_feature_active()

Parameters

Return value

Errors

​get_variation()

Parameters

Return value

Errors

​get_variations()

Parameters

Return value

Errors

​set_forced_variation()

Parameters

Return value

Errors

​evaluate_audiences()

Parameters

Return value

Errors

​get_datafile()

Return value

Errors

​Visitor data

​get_visitor_code()

Parameters

Return value

​add_data()

Parameters

Return value

Errors

​flush()

Parameters

Return value

Errors

​get_remote_data()

Parameters

Return value

Errors

​get_remote_visitor_data()

Parameters

Return value

Developer guide

Getting started

Install the Elixir client

Additional configuration

Initialize the Kameleoon client

Activating a feature flag

Using a custom bucketing key

Use cases

Technical details

Technical requirements

Targeting conditions

Cross-device experimentation

Synchronizing custom data across devices

Using custom data for session merging

Logging

Log levels

Custom handling of logs

Reference

Initialization

create()

initialize()

is_ready()

forget()

Feature flags and variations

is_feature_active()

get_variation()

get_variations()

set_forced_variation()

evaluate_audiences()

get_datafile()

Visitor data

get_visitor_code()

add_data()

flush()

get_remote_data()

get_remote_visitor_data()

`RemoteVisitorDataFilter` fields

get_visitor_warehouse_audience()

set_legal_consent()

Goals and third-party analytics

track_conversion()

get_engine_tracking_code()

Events

on_datafile_update()

Data types

ApplicationVersion

Browser

Conversion

Cookie

CustomData

Device

Geolocation

OperatingSystem

PageView

UniqueIdentifier

UserAgent

Returned types

DataFile

FeatureFlag

Rule

Variation

Variable