Python SDK

pip install kameleoon-client-python

from kameleoon import KameleoonClient, KameleoonClientConfig, KameleoonClientFactory

SITE_CODE = 'a8st4f59bj'

# Option 1
kameleoon_client = KameleoonClientFactory.create(SITE_CODE, config_path='/etc/kameleoon/client-python.yaml')

# Option 2
configuration_object = KameleoonClientConfig.read_from_yaml('/etc/kameleoon/client-python.yaml')
configuration_object.set_top_level_domain("example.com")
kameleoon_client = KameleoonClientFactory.create(SITE_CODE, configuration_object)

# Option 3
configuration_object = KameleoonClientConfig(
    "client_id",  # required
    "client_secret",  # required
    refresh_interval_minute=60,  # (in minutes) optional, default: 60 minutes
    session_duration_minute=30,  # (in minutes) optional, default: 30 minutes
    default_timeout_millisecond=10000,  # (in milliseconds) optional, default: 10000 milliseconds
    tracking_interval_millisecond=1000,  # (in milliseconds) optional, default: 1000 milliseconds
    environment="production",  # optional, possible values: "production" / "staging" / "development" / "staging", default: None
    top_level_domain="example.com",
    multi_threading=False,  # optional, default: False
    logger=my_logger,  # optional, default: standard kameleoon logger. This field is deprecated and will be removed in SDK version `4.0.0`. Use `KameleoonLogger.set_logger` instead.
    network_domain="example.com",  # optional
)
kameleoon_client = KameleoonClientFactory.create(SITE_CODE, configuration_object)

def ready(self):
    if os.environ.get('RUN_MAIN', None) == 'true':
        configuration_path = os.path.join(ROOT_DIR, 'path_to_config', 'config.yml')
        self.kameleoon_client = KameleoonClientFactory.create(SITE_CODE, config_path=configuration_path)

from django.apps import apps

my_application = apps.get_app_config('your_app')
client = my_application.kameleoon_client

# In this example, `91` represents the Custom Data's index configured as a unique identifier in Kameleoon.
MAPPING_INDEX = 91
FEATURE_KEY = "ff123"

# 1. Before the visitor is authenticated

# Retrieve the variation for an unauthenticated visitor.
# Assume `anonymous_visitor_code` is the randomly generated ID for that visitor.
anonymous_variation = kameleoon_client.get_variation(anonymous_visitor_code, FEATURE_KEY)

# 2. After the visitor is authenticated

# Assume `user_id` is the visitor code of the authenticated visitor.
kameleoon_client.add_data(anonymous_visitor_code, CustomData(MAPPING_INDEX, user_id))
kameleoon_client.flush(anonymous_visitor_code, instant=True)

# Indicate that `user_id` is a unique identifier.
kameleoon_client.add_data(user_id, UniqueIdentifier(True))

# 3. After the visitor has been authenticated

# Retrieve the variation for the `user_id`, which will match the anonymous visitor code's variation.
user_variation = kameleoon_client.get_variation(user_id, FEATURE_KEY)
is_same_variation = user_variation.key == anonymous_variation.key  # True

# The `user_id` and `anonymous_visitor_code` are now linked and tracked as a single visitor.
kameleoon_client.track_conversion(user_id, 123, 10.0)

# Additionally, the linked visitors will share all fetched remote visitor data.
kameleoon_client.get_remote_visitor_data(user_id)

from kameleoon.data import CustomData

kameleoon_client.add_data(visitor_code, CustomData(index, "new_visitor_code"))

from kameleoon.logging.log_level import LogLevel
from kameleoon.logging.kameleoon_logger import KameleoonLogger

# The `NONE` log level does not allow logging.
KameleoonLogger.set_log_level(LogLevel.NONE)

# The `ERROR` log level only allows logging issues that may affect the SDK's main behaviour.
KameleoonLogger.set_log_level(LogLevel.ERROR)

# The `WARNING` log level allows logging issues which may require additional attention.
# It extends the `ERROR` log level.
# The `WARNING` log level is a default log level.
KameleoonLogger.set_log_level(LogLevel.WARNING)

# The `INFO` log level allows logging general information on the SDK's internal processes.
# It extends the `WARNING` log level.
KameleoonLogger.set_log_level(LogLevel.INFO)

# The `DEBUG` level logs additional details about the SDK’s internal processes and extends the `INFO` level
# with more granular. diagnostic output.
# This information is not intended for end-user interpretation but can be sent to our support team
# to assist with internal troubleshooting.
KameleoonLogger.set_log_level(LogLevel.DEBUG)

from loguru import logger
from kameleoon.logging.log_level import LogLevel
from kameleoon.logging.logger import Logger


class CustomLogger(Logger):
    """Custom logger implementation using loguru."""

    def log(self, level: LogLevel, message: str) -> None:
        """Accepts logs from the SDK"""
        if level == LogLevel.ERROR:
            logger.error(message)
        elif level == LogLevel.WARNING:
            logger.warning(message)
        elif level == LogLevel.INFO:
            logger.info(message)
        elif level == LogLevel.DEBUG:
            logger.debug(message)


from kameleoon.logging.kameleoon_logger import KameleoonLogger

# 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.
# Ensure the log level is set correctly.
KameleoonLogger.set_logger(CustomLogger())
KameleoonLogger.set_log_level(LogLevel.DEBUG)  # Optional, defaults to `LogLevel.WARNING`.

kameleoon_config = KameleoonClientConfig("client_id", "client_secret")
kameleoon_client = KameleoonClientFactory.create("a8st4f59bj", kameleoon_config)

kameleoon_client = KameleoonClientFactory.create("a8st4f59bj", config_path="/etc/kameleoon/client-ruby.yaml")

kameleoon_client = KameleoonClientFactory.create('a8st4f59bj')

if await kameleoon_client.wait_init_async():
    # The SDK has been initialized; you can fetch a feature flag / experiment configuration here.

kameleoon_client = KameleoonClientFactory.create('a8st4f59bj')

if kameleoon_client.wait_init():
    # The SDK has been initialized; you can fetch a feature flag / experiment configuration here.

visitor_code = kameleoon_client.get_visitor_code(request.COOKIES)
feature_key = "new_checkout"
has_new_checkout = False

try
    has_new_checkout = kameleoon_client.is_feature_active(visitor_code, feature_key)
    # disabling tracking
    has_new_checkout = kameleoon_client.is_feature_active(visitor_code, feature_key, track=False)
except FeatureNotFound as ex:
    # The user will not be counted in the experiment,
    # but should see the reference variation.
    has_new_checkout = False
except VisitorCodeInvalid as ex:
    # The visitor code you passed to the method isn't valid and can't be accepted by SDK.
    has_new_checkout = False

if has_new_checkout
    # Implement new checkout code here

feature_key = "new_checkout"

try:
    variation = kameleoon_client.get_variation(visitor_code, feature_key)
    # disabling tracking
    variation = kameleoon_client.get_variation(visitor_code, feature_key, False)
except FeatureNotFound as ex:
    # The error has occurred; the feature flag isn't found in current configuration.
except FeatureEnvironmentDisabled as ex:
    # The feature flag is disabled for the environment.
except VisitoCodeNotValid as ex:
    # The visitor code you passed to the method is invalid and can't be accepted by SDK.

# Fetch a variable value for the assigned variation
title = variation.variables["title"].value

if variation.key == "on":
    # Main variation key is selected for visitorCode
elif variation.key == "alternative_variation":
    # Alternative variation key
else:
    # Default variation key

try:
    variations = kameleoon_client.get_variations(visitor_code)
    # only active variations
    variations = kameleoon_client.get_variations(visitor_code, only_active=True)
    # disable tracking
    variations = kameleoon_client.get_variations(visitor_code, track=False)
except VisitorCodeInvalid as ex:
    # Handle exception

data_file = kameleoon_client.get_data_file()
date_modified = data_file.date_modified

experiment_id = 9516
try:
    # Forcing the variation "on" for the experiment 9516 for the visitor
    kameleoon_client.set_forced_variation(visitor_code, experiment_id, "on")

    # Forcing the variation "on" while preserving segmentation and targeting conditions during the experiment
    kameleoon_client.set_forced_variation(visitor_code, experiment_id, "on", False)

    # Resetting the forced variation for the experiment 9516 for the visitor
    kameleoon_client.set_forced_variation(visitor_code, experiment_id, None)
except KameleoonError as e:
    # Handling the error

try:
    kameleoon_client.evaluate_audiences(visitor_code)
except KameleoonError as e:
    # Handling the error

### if you use KameleoonWSGIMiddleware service
visitor_code = kameleoon_client.get_visitor_code(cookies_readonly=request.COOKIES)
kameleoon_client.set_legal_consent(visitor_code, True)

### if you want to manage cookies manually
simple_cookies = SimpleCookie()
simple_cookies.load(cookie_header)

visitor_code = kameleoon_client.get_visitor_code(cookies=simple_cookies, default_visitor_code=default_visitor_code)

cookie_header = simple_cookies.output()

require "kameleoon"
require "kameleoon/data"

# Add a single data item (tracked by default)
kameleoon_client.add_data(visitor_code, Browser(BrowserType.CHROME))

# Add multiple data items (tracked by default)
kameleoon_client.add_data(
    visitor_code,
    PageView("https://url.com", "title", [3]),
    UserAgent("UserAgent")
)

# Add multiple data items stored locally for targeting only (not sent to the Kameleoon Data API)
kameleoon_client.add_data(
    visitor_code,
    PageView("https://url.com", "title", [3]),
    UserAgent("UserAgent"),
    track=False
)

kameleoon_client.add_data(visitor_code, Browser(BrowserType.CHROME))
kameleoon_client.add_data(
    visitor_code,
    PageView("https://url.com", "title", [3]),
    CustomData(0, "value")
)
kameleoon_client.add_data(visitor_code, Conversion(32, 10, false))

kameleoon_client.flush(visitor_code)  # Interval tracking (most performant way for tracking)

kameleoon_client.flush(visitor_code, instant=True)  # Instant tracking

# If you operate with unique ID
kameleoon_client.add_data(UniqueIdentifier(True))
kameleoon_client.flush(visitor_code)

    kameleoon_client.get_remote_data('key1') # default timeout

    kameleoon_client.get_remote_data('key2', 1.0) # 1 second timeout

    await kameleoon_client.get_remote_data_async('key1') # default timeout

    await kameleoon_client.get_remote_data_async('key2', 1.0) # 1 second timeout

    visitor_code = 'visitorCode'

    # Visitor data will be fetched and automatically added for `visitor_code`
    data_list = kameleoon_client.get_remote_visitor_data(visitor_code)  # default timeout
    data_list = kameleoon_client.get_remote_visitor_data(visitor_code, timeout=1.0)  # 1 second timeout

    # If you only want to fetch data and add it yourself manually, set `add_data` to `False`
    data_list = kameleoon_client.get_remote_visitor_data(visitor_code, False)  # default timeout
    data_list = kameleoon_client.get_remote_visitor_data(visitor_code, False, 1.0)  # 1 second timeout

    # If you want to fetch custom list of data types
    data_filter = RemoteVisitorDataFilter(25, customData=False, conversions=True, experiments=True)
    data_list = kameleoon_client.get_remote_visitor_data(visitor_code, data_filter=data_filter)

    # If you want the SDK to link the extracted data with the visitor associated with the specified identifier.
    kameleoon_client.add_data(UniqueIdentifier(True))
    data_list = kameleoon_client.get_remote_visitor_data(visitor_code)

    visitor_code = 'visitorCode'

    # Visitor data will be fetched and automatically added for `visitor_code`
    data_list = await kameleoon_client.get_remote_visitor_data_async(visitor_code)  # default timeout
    data_list = await kameleoon_client.get_remote_visitor_data_async(visitor_code, timeout=1.0)  # 1 second timeout

    # If you only want to fetch data and add it yourself manually, set `add_data` to `False`
    data_list = await kameleoon_client.get_remote_visitor_data_async(visitor_code, False)  # default timeout
    data_list = await kameleoon_client.get_remote_visitor_data_async(visitor_code, False, 1.0)  # 1 second timeout
    # If you want to fetch custom list of data types
    data_filter = RemoteVisitorDataFilter(25, customData=False, conversions=True, experiments=True)
    data_list = kameleoon_client.get_remote_visitor_data(visitor_code, data_filter=data_filter)

    # If you want the SDK to link the extracted data with the visitor associated with the specified identifier.
    kameleoon_client.add_data(UniqueIdentifier(True))
    data_list = kameleoon_client.get_remote_visitor_data(visitor_code)

try:
    warehouse_audience_data = kameleoon_client.\
        get_visitor_warehouse_audience(visitor_code, custom_data_index)  # default timeout
    warehouse_audience_data = kameleoon_client.\
        get_visitor_warehouse_audience(visitor_code, custom_data_index, timeout=1.0)  # 1 second timeout

    warehouse_audience_data = kameleoon_client.\
        get_visitor_warehouse_audience(visitor_code, custom_data_index, warehouse_key)  # default timeout
    warehouse_audience_data = kameleoon_client.\
        get_visitor_warehouse_audience(visitor_code, custom_data_index, warehouse_key, 1.0)  # 1 second timeout

    # Your custom code
except VisitorCodeInvalid as e:
    # Handle exception

try:
    warehouse_audience_data = await kameleoon_client.\
        get_visitor_warehouse_audience_async(visitor_code, custom_data_index)  # default timeout
    warehouse_audience_data = await kameleoon_client.\
        get_visitor_warehouse_audience_async(visitor_code, custom_data_index, timeout=1.0)  # 1 second timeout

    warehouse_audience_data = await kameleoon_client.\
        get_visitor_warehouse_audience_async(visitor_code, custom_data_index, warehouse_key)  # default timeout
    warehouse_audience_data = await kameleoon_client.\
        get_visitor_warehouse_audience_async(visitor_code, custom_data_index, warehouse_key, 1.0)  # 1 second timeout

    # Your custom code
except VisitorCodeInvalid as e:
    # Handle exception

### if you use KameleoonWSGIMiddleware service
visitor_code = kameleoon_client.get_visitor_code(cookies_readonly=request.COOKIES)
kameleoon_client.set_legal_consent(visitor_code, True)

### if you want to manage cookies manually
cookies = http.cookies.SimpleCookie()
cookies.load(cookie_header)

visitor_code = kameleoon_client.get_visitor_code(cookies=cookies)
kameleoon_client.set_legal_consent(visitor_code, True, cookies)

cookie_header = cookies.output()

require "kameleoon"
require "kameleoon/data"

visitor_code = kameleoon_client.get_visitor_code(request.COOKIES)
goal_id = 83023

kameleoon_client.add_data(visitor_code, Browser(BrowserType.CHROME))
kameleoon_client.add_data(
    visitor_code,
    PageView("https://url.com", "title", [3]),
    CustomData(2, "value")
)
kameleoon_client.add_data(visitor_code, Conversion(32, 10, false))
kameleoon_client.track_conversion(visitor_code, goal_id)

engine_tracking_code = kameleoon_client.get_engine_tracking_code(visitor_code)

visitor_code = "visitorCode"
goal_id = 83023

kameleoon_client.add_data(visitor_code, Browser(BrowserType.CHROME))
kameleoon_client.add_data(
    visitor_code,
    PageView("https://url.com", "title", [3]),
    CustomData(2, "value")
)
kameleoon_client.add_data(visitor_code, Conversion(32, 10, False))

# Add metadata
cd = CustomData(1, "metadata")
kameleoon_client.track_conversion(visitorCode, goalId, metadata=[cd])

kameleoon_client.on_update_configuration(
    // configuration was updated
)

kameleoon_client.add_data(visitor_code, Browser(BrowserType.CHROME))

kameleoon_client.add_data(visitor_code, Browser(BrowserType.SAFARI, 10))

kameleoon_client.add_data(visitor_code, PageView("https://url.com", "title", [3]))

kameleoon_client.add_data(visitor_code, Conversion(32, 10))

kameleoon_client.add_data(visitor_code, Conversion(33, negative=True))

kameleoon_client.add_data(
    visitor_code,
    Conversion(34, 5, metadata=[
        CustomData(3, "metadata1", "md2"),
        CustomData(5, "md3"),
    ])
)

from kameleoon.data import CustomData

kameleoon_client.add_data(visitor_code, CustomData(1, "value"))

# With several values
kameleoon_client.add_data(visitor_code, CustomData(1, "value1", "value2"))

# To set the 'overwrite' flag to false
kameleoon_client.add_data(visitor_code, CustomData(1, "value", overwrite=False))

# To use a name instead of the index
kameleoon_client.add_data(visitor_code, CustomData("my-custom-data", "value"))

from kameleoon import Device, DeviceType

kameleoon_client.add_data(visitor_code, Device(DeviceType.DESKTOP))

from kameleoon.data import UserAgent

kameleoon_client.add_data(visitor_code, UserAgent('userAgent'))

from kameleoon.data import UniqueIdentifier

kameleoon_client.add_data(visitor_code, UniqueIdentifier(True))

from kameleoon.data import OperatingSystem, OperatingSystemType

kameleoon_client.add_data(visitor_code, OperatingSystem(OperatingSystemType.ANDROID))

from kameleoon.data import Cookie

cookie = Cookie({"k1": "v1", "k2": "v2"})
kameleoon_client.add_data(visitor_code, cookie)

from kameleoon.data import Geolocation

kameleoon_client.add_data(visitor_code, Geolocation("France", "Île-de-France", "Paris"))

kameleoon_client_sdk.add_data(visitorCode, ApplicationVersion("10")) # major

kameleoon_client_sdk.add_data(visitorCode, ApplicationVersion("10.20")) # major.minor

kameleoon_client_sdk.add_data(visitorCode, ApplicationVersion("10.20.30")) # major.minor.patch

# Retrieves the dict of feature flags from the DataFile.
# The dict is keyed by feature flag identifiers, with each value being a FeatureFlag object.
feature_flags: Dict[str, FeatureFlag] = data_file.feature_flags

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

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

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

# Retrieve the default variation object
default_variation: Variation = feature_flag.default_variation

# Retrieve all variations of the feature flag as a dict (key = variation key, value = Variation object)
variations: Dict[str, Variation] = feature_flag.variations

# Retrieve all targeting rules associated with the feature flag
rules: Iterable[Rule] = feature_flag.rules

# Retrieving the variation key
variation_key: str = variation.key

# Retrieving the variation id
variation_id: Optional[int] = variation.id_

# Retrieving the experiment id
experiment_id: Optional[int] = variation.experiment_id

# Retrieving the variables map
variables: Dict[str, Variable] = variation.variables

# Retrieving the variable key
variables: Dict[str, Variable] = variation.variables

# Variable type can be retrieved for further processing
variable_type: str = variables["isDiscount"].type

# Retrieving the variable value by key
is_discount: Optional[bool] = variables["isDiscount"].value

# Variable value can be of different types
title: Optional[str] = variables["title"].value

visitor_code = kameleoon_client.get_visitor_code(request.COOKIES)

feature_key = "feature_key"
variation_key = ""

try
    variation_key = kameleoon_client.get_feature_variation_key(visitor_code, feature_key)
    if variation_key == 'on':
        # main variation key is selected for visitorCode
    elif variation_key == 'alternative_variation':
        # alternative variation key
    else:
        # default variation key
except FeatureNotFound as ex:
    # The user will not be counted in the experiment, but should see the reference variation.
except VisitorCodeInvalid as ex:
    # The visitor code you passed to the method isn't valid and can't be accepted by SDK.
except FeatureEnvironmentDisabled as ex:
    # The feature flag is disabled for certain environments.

try:
    active_features = kameleoon_client_sdk.get_active_features(visitor_code)
except VisitorCodeInvalid as e:
    # Handle exception

active_feature_flag_for_visitor = kameleoonClient.get_active_feature_list_for_visitor(visitor_code)

visitor_code = kameleoon_client.get_visitor_code(request.COOKIES)

feature_key = "feature_key"
variable_key = "variable_key"
variation_value = ""

try:
    variable_value = kameleoon_client.get_feature_variable(visitor_code, feature_key, variable_key)
except FeatureNotFound as ex:
    # The user will not be counted in the experiment, but should see the reference variation.
except FeatureVariableNotFound as ex:
    # Requested variable not defined on Kameleoon's side
except VisitorCodeInvalid as ex:
    # The visitor code you passed to the method isn't valid and can't be accepted by SDK.
except FeatureEnvironmentDisabled as ex:
    # The feature flag is disabled for certain environments.

# your custom code depending of variable_value, e.g.
if variable_value == "value-1":
    # your custom code if variable == 'value-1'
elif variable_value == "value-2":
    # your custom code if variable == 'value-2'
else:
    # ...

feature_key = "myFeature"

try
    data = kameleoon_client.get_feature_variation_variables(feature_key)
except FeatureNotFound as ex:
    # The feature is not activated on Kameleoon's side.
except FeatureEnvironmentDisabled as ex:
    # The feature flag is disabled for certain environments.

all_feature_list = kameleoon_client.get_feature_list()