> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt
> Use this file to discover all available pages before exploring further.
# SDK de Python
> Integre el SDK de Python de Kameleoon para ejecutar experimentos y activar feature flags en servidores back-end Python, incluidos entornos Django.
Con el SDK de Python de Kameleoon, puede ejecutar experimentos y activar feature flags en su servidor Python de back-end. Es sencillo integrar nuestro SDK en su aplicación web y su huella (memoria y uso de red) es baja.
**Primeros pasos**: Para obtener ayuda para comenzar, consulte la [guía del desarrollador](#guía-del-desarrollador).
**Changelog**: Última versión del SDK de Python: 3.18.0 [Changelog](https://github.com/Kameleoon/client-python/blob/main/CHANGELOG.md).
**Métodos del SDK**: Para la documentación de referencia completa del SDK de Python, consulte la sección [referencia](#referencia).
## Guía del desarrollador
Esta guía está diseñada para ayudarle a integrar nuestro SDK en unos minutos y comenzar a ejecutar experimentos en sus aplicaciones Python. This tutorial will explain the setup of a simple A/B test to change the number of recommended products based on different variations.
### Primeros pasos
#### Instalación del cliente Python
Puede instalar el SDK utilizando un paquete pip de Python. Nuestro paquete está alojado en el repositorio oficial de pip, así que solo tiene que ejecutar el siguiente comando:
```python theme={null}
pip install kameleoon-client-python
```
#### Configuración adicional
You should provide credentials for the Python SDK via a configuration file, which you can also use to customize the SDK's behavior. A sample configuration file [can be obtained here](/assets/developer-docs/sdks/web-sdks/client-configs/client-python.yaml). We suggest installing this file to the default path `/etc/kameleoon/client-python.yaml`, but you can put it in another location and pass the path as an argument to the `KameleoonClient()` constructor method. With the current version of the Python SDK, these are the available keys:
| Clave | Descripción | Valor predeterminado |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `client_id` (*obligatorio*) | Required for authentication to the Kameleoon service. To find your **client id**, see the [API credentials](/user-manual/account-and-team-management/users-and-teams/api-credentials) documentation. | |
| `client_secret` (*obligatorio*) | Required for authentication to the Kameleoon service. To find your **client secret**, see the [API credentials](/user-manual/account-and-team-management/users-and-teams/api-credentials) documentation. | |
| `session_duration_minute` (*opcional*) | Designa el intervalo de tiempo predefinido durante el cual Kameleoon almacena al visitante y sus datos asociados en memoria (RAM). Tenga en cuenta que aumentar la duración de la sesión incrementa la cantidad de RAM que debe asignarse para almacenar los datos del visitante. | `30` minutos |
| `refresh_interval_minute` (*opcional*) | Especifica el intervalo de actualización, en minutos, con el que el SDK obtiene la configuración de los experimentos activos y los feature flags. El valor determina el tiempo máximo necesario para propagar los cambios, como activar o desactivar feature flags o lanzar experimentos, a sus servidores de producción. Adicionalmente, ofrecemos un [modo streaming](/developer-docs/feature-experimentation/technical-reference/technical-considerations/#streaming-premium-option) que utiliza server-sent events (SSE) para enviar nuevas configuraciones al SDK automáticamente y aplicar las nuevas configuraciones en tiempo real, sin ningún retraso. | `60` minutos |
| `default_timeout_millisecond` (*opcional*) | Especifica el tiempo de espera, en milisegundos, para las solicitudes de red desde el SDK. Establezca el valor en 30 segundos o más si no dispone de una conexión estable. Algunos métodos tienen un parámetro adicional que puede utilizar para anular el tiempo de espera predeterminado para ese método en particular. Si no especifica el tiempo de espera para un método de forma explícita, el SDK utiliza este valor predeterminado. | `10000` milisegundos |
| `tracking_interval_millisecond` (*opcional*) | Especifica el intervalo para las solicitudes de seguimiento en milisegundos. Todos los visitantes que Kameleoon haya evaluado para cualquier feature flag o cuyos datos se hayan vaciado se incluyen en esta solicitud de seguimiento, que el SDK realiza una vez por intervalo. El valor mínimo es `1000` ms, que también es el predeterminado, y el valor máximo es `5000` ms. | `1000` milisegundos |
| `environment` (*opcional*) | Entorno desde el cual se debe utilizar la configuración del feature flag. El valor puede ser `production`, `staging` o `development`. Consulte el artículo de [gestión de entornos](/user-manual/experimentation/feature-experimentation/configure-your-feature-flags/manage-environments) para más detalles. | `production` |
| `top_level_domain` *(obligatorio en modo híbrido)* | El dominio de nivel superior actual de su sitio web. Use el formato: `example.com`. No incluya `https://`, `www` ni otros subdominios. Kameleoon utiliza esta información para establecer la cookie correspondiente en el dominio de nivel superior. | `""` |
| `network_domain` (*opcional*) | Dominio personalizado utilizado por los SDKs para las solicitudes salientes, a menudo para proxy. Debe ser un dominio válido (por ejemplo, example.com o sub.example.com). Los formatos no válidos se sustituyen por el valor de Kameleoon. | `None` |
| `logger` *(deprecated)* | Allows overriding the default Python logger. This field is deprecated and will be removed in SDK version `4.0.0`. Use [`KameleoonLogger.set_logger()`](#registro-de-eventos) instead. | `logging.Logger` |
| `multi_threading` *(deprecated)* | An option of type `bool` indicating whether threads can be used for network requests. By default everything is executed in one thread to avoid performance issues with GIL if (C)Python interpreter is being used. Possible values: `True`, `False`. | `None` |
Alternatively, you can use `configuration_object` of type `KameleoonClientConfig` as a parameter during initialization. It has the same list of arguments as a config file. `configuration_object` takes precedence over the configuration file and overwrites its settings.
#### Inicialización del cliente Kameleoon
After installing the SDK into your application, configuring the correct credentials (in `/etc/kameleoon/client-python.yaml`), and setting up a server-side experiment in Kameleoon's back-office, the next step is creating the Kameleoon client in your application code.
El código de la derecha proporciona un ejemplo claro. Un `KameleoonClient` es un objeto singleton que actúa como puente entre su aplicación y la plataforma Kameleoon. Incluye todos los métodos y propiedades que necesitará para ejecutar un experimento.
Developers are responsible for ensuring the correct logic of their application code when implementing A/B testing with Kameleoon. A best practice is to always assume that a visitor may be excluded from the experiment if it has not yet been launched. This practice is simple to implement, as it aligns with the default or reference variation logic, which should always be in place. The code samples in the next section demonstrate this approach.
```python theme={null}
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)
```
#### Activación de un feature flag
##### Asignación de un ID único a un usuario
To assign a unique ID to a user, you can use the [`get_visitor_code()`](#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.
Si está usando Kameleoon en [modo híbrido](/developer-docs/feature-experimentation/get-started/hybrid-experimentation), llamar al método `get_visitor_code()` garantiza que el ID único (**visitor code**) se comparta entre el archivo de aplicación `engine.js` (anteriormente llamado `kameleoon.js`) y el SDK.
##### Recuperación de la configuración de un flag
Para implementar un feature flag en su código, primero debe crear el feature flag en su cuenta de Kameleoon.
To determine the status or variation of a feature flag for a specific user, you should use the [`get_variation()`](#get_variation) or [`is_feature_active()`](#is_feature_active) method to retrieve the configuration based on the `feature_key`.
El método `get_variation()` gestiona tanto los feature flags simples con estados ON/OFF como los flags más complejos con múltiples variaciones. El método recupera la variación adecuada para el usuario comprobando las reglas de la funcionalidad, asignando la variación y devolviéndola en función del `feature_key` y el `visitor_code`.
El método `is_feature_active()` puede utilizarse si desea recuperar la configuración de un feature flag simple que solo tiene un estado ON u OFF, a diferencia de los feature flags más complejos con múltiples variaciones u opciones de segmentación.
If your feature flag has associated variables (such as specific behaviors tied to each variation) `get_variation()` also enables you to access the [`Variation`](#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_millisecond`](#configuración-adicional). De forma predeterminada, 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. Si desea saber más sobre how tracking works, view [this article](/developer-docs/feature-experimentation/technical-reference/faq-global#when-does-the-sdk-send-a-tracking-request-for-analytics)
##### Adición de puntos de datos para segmentar a un usuario o filtrar / desglosar visitas en informes
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 [`add_data()`](#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()`](#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.
Para obtener más información sobre las condiciones de segmentación disponibles, consulte el [artículo detallado sobre este tema](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation).
Además, los puntos de datos que añade al perfil del visitante estarán disponibles al analizar sus experimentos, lo que le permite filtrar y desglosar sus resultados por factores como el dispositivo y el navegador. El modo híbrido de Kameleoon recopila automáticamente una variedad de puntos de datos en el lado del cliente, lo que facilita desglosar sus resultados en función de estos puntos de datos previamente recopilados. Consulte la lista completa [aquí](/es/user-manual/experiment-analytics/analyze-results/results-page/results-page-settings#desglose-de-audiencia).
Si necesita realizar el seguimiento de puntos de datos adicionales más allá de los que se recopilan automáticamente, puede utilizar la [funcionalidad de Custom Data](#customdata) de Kameleoon. Custom Data le permite capturar y analizar información específica relevante para sus experimentos. No olvide llamar al método [`flush()`](#flush) para enviar los datos recopilados a los servidores de Kameleoon para su análisis.
Para asegurarse de que sus resultados sean precisos, se recomienda filtrar los bots utilizando el tipo de dato [`UserAgent`](#useragent).
##### Seguimiento de conversiones de objetivos
Cuando un usuario completa una acción deseada (como realizar una compra), se registra como una conversión. Para hacer seguimiento de las conversiones, utilice el método [`track_conversion()`](#track_conversion) y proporcione los parámetros requeridos `visitor_code` y `goal_id`.
La solicitud de seguimiento de conversiones se enviará junto con la siguiente solicitud de seguimiento programada, que el SDK envía a intervalos regulares (definidos por [`tracking_interval_millisecond`](#configuración-adicional)). Si prefiere enviar la solicitud de inmediato, utilice el método [`flush()`](#flush) con el parámetro `instant=True`.
##### Envío de eventos a soluciones de analítica
To track conversions and send exposure events to your customer analytics solution, you must first implement Kameleoon in [Hybrid mode](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/). Then, use the [`get_engine_tracking_code()`](#get_engine_tracking_code) method.
El método `get_engine_tracking_code()` recupera el código de seguimiento único necesario para enviar eventos de exposición a su solución de analítica. El uso de este método le permite registrar eventos y enviarlos a la plataforma de analítica que desee.
### Uso del SDK de Python de Kameleoon en un entorno Django
Si utiliza Django, le recomendamos inicializar el cliente Kameleoon al arrancar el servidor, en el archivo `apps.py` de su aplicación Django.
Cuando utiliza python manage.py runserver, Django arranca dos procesos: uno para el servidor de desarrollo real y otro para recargar su aplicación cuando cambia el código.
También puede iniciar el servidor sin la opción de recarga, y solo verá un proceso en ejecución. El proceso solo se ejecuta una vez:
`python manage.py runserver --noreload`
También puede comprobar la variable de entorno RUN\_MAIN en el método `ready()`.
```python theme={null}
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)
```
This only applies to local development when you use python manage.py runserver. In a production environment, the code in the `ready()` function will be executed only once when the application is initialized.
```python theme={null}
from django.apps import apps
my_application = apps.get_app_config('your_app')
client = my_application.kameleoon_client
```
A continuación, puede acceder al cliente Kameleoon en su aplicación.
Another advantage of using Django is that the SDK will automaticallyo read and write the **visitor\_code** on the HTTP request/response via a cookie. If you're using another framework in a web environment where you would like to use a cookie mechanism to persist the **visitor\_code**, you must provide implementations of the `read_cookies()` and `write_cookies()` methods.
### Experimentación entre dispositivos
Para dar soporte a los visitantes que acceden a una aplicación desde varios dispositivos, Kameleoon permite sincronizar los datos del visitante previamente recopilados entre cada uno de sus dispositivos y reconciliar su historial de visitas entre dispositivos mediante la experimentación entre dispositivos. Los casos de estudio y la información detallada sobre cómo Kameleoon gestiona los datos entre dispositivos están disponibles en el [artículo sobre experimentación entre dispositivos](/developer-docs/cross-device-experimentation).
#### Sincronización de datos personalizados entre dispositivos
Aunque la sincronización de mapeo personalizado se utiliza para alinear los datos del visitante entre dispositivos, no siempre es necesaria. A continuación se presentan dos escenarios en los que no se requiere la sincronización de mapeo personalizado:
**Mismo ID de usuario en todos los dispositivos**
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.
**Instancias multi-servidor con IDs consistentes**
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()`](#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.
Si desea sincronizar los datos recopilados en tiempo real, debe elegir el ámbito **Visitor** para sus datos personalizados.
```python title="Device A" theme={null}
# In this example, Custom data with index `90` was set to "Visitor" scope in Kameleoon.
VISITOR_SCOPE_CUSTOM_DATA_INDEX = 90
kameleoon_client.add_data(visitor_code, CustomData(VISITOR_SCOPE_CUSTOM_DATA_INDEX, "your data"))
kameleoon_client.flush(visitor_code)
```
```python title="Device B" theme={null}
# Before working with the data, call `get_remote_visitor_data`.
kameleoon_client.get_remote_visitor_data(visitor_code)
# After calling, the SDK on Device B will have access to CustomData of Visitor scope defined on Device A.
# So, "your data" will be available to target and track the visitor.
```
#### Uso de datos personalizados para la fusión de sesiones
La [experimentación entre dispositivos](/developer-docs/cross-device-experimentation) permite combinar el historial de un visitante en cada uno de sus dispositivos (reconciliación de historial). La reconciliación de historial permite fusionar diferentes sesiones de un visitante en una sola. Para reconciliar el historial de visitas, utilice [`CustomData`](#customdata) para proporcionar un identificador único del visitante. Para más información, consulte la [documentación dedicada](/developer-docs/cross-device-experimentation/#activating-cross-device-history-reconciliation).
After cross-device reconciliation is enabled, calling [`get_remote_visitor_data()`](#get_remote_visitor_data) with the parameter `userId` retrieves all known data for a given user.
Las sesiones con el mismo identificador siempre verán la misma variación en un experimento. En la vista Visitor de las páginas de resultados de su experimento, estas sesiones aparecerán como un único visitante.
La configuración del SDK garantiza que las sesiones asociadas siempre vean la misma variación del experimento. Sin embargo, existen algunas limitaciones en cuanto a la asignación de variaciones entre dispositivos. Estas limitaciones se describen [aquí](/developer-docs/cross-device-experimentation#critical-points-and-practical-insights).
Siga la guía de [activación de la reconciliación de historial entre dispositivos](#experimentación-entre-dispositivos) para configurar sus datos personalizados en la plataforma Kameleoon.
Posteriormente, puede usar el SDK de forma normal. Los siguientes métodos pueden ser útiles en el contexto de la fusión de sesiones:
* `get_remote_visitor_data()` with added `UniqueIdentifier(True)` - to retrieve data for all linked visitors.
* [`track_conversion()`](#track_conversion) or [`flush()`](#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](/developer-docs/cross-device-experimentation) to retrieve the identifier with the [`get_remote_visitor_data()`](#get_remote_visitor_data) method on each device.
A continuación se muestra un ejemplo de cómo usar datos personalizados para la fusión de sesiones.
```python theme={null}
# 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)
```
En este ejemplo, la aplicación tiene una página de inicio de sesión. Como el ID de usuario es desconocido en el momento del inicio de sesión, se utiliza un identificador de visitante anónimo generado por el método [`get_visitor_code()`](#get_visitor_code). Después de que el usuario inicia sesión, el visitante anónimo se asocia con el ID de usuario y se utiliza como identificador único del visitante.
### Uso de una clave de bucketing personalizada
De forma predeterminada, 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.
La opción **Custom Bucketing Key** le permite anular este comportamiento predeterminado proporcionando su propio identificador personalizado para el bucketing. Esta anulación garantiza que la lógica de asignación de Kameleoon utilice la clave que usted especifique en lugar del `visitor_code` predeterminado.
#### Casos de uso
El uso de una clave de bucketing personalizada es esencial para mantener la consistencia y precisión en las asignaciones de sus feature flags, especialmente en estas situaciones:
* **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.
Al implementar una clave de bucketing personalizada, garantiza una mayor consistencia y precisión en sus experimentos, lo que se traduce en resultados más fiables y en una mejor experiencia de usuario.
#### Detalles técnicos
Cuando configura una clave de bucketing personalizada para un feature flag, proporciona a Kameleoon un identificador específico de los datos de su aplicación:
```python theme={null}
from kameleoon.data import CustomData
kameleoon_client.add_data(visitor_code, CustomData(index, "new_visitor_code"))
```
* **Providing the custom key:** You provide your custom identifier to the Kameleoon SDK using the [`add_data()`](#add_data) method. In this method, you will pass your chosen custom bucketing key as a [`CustomData`](#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`).
Para que la clave de bucketing personalizada funcione correctamente, también debe definirse y configurarse para el feature flag durante el proceso de creación o edición del flag. Sin esta configuración correspondiente, el bucketing del SDK no aplicará su clave personalizada. Para obtener instrucciones detalladas sobre cómo configurar esto en Kameleoon, consulte este [artículo](/user-manual/experimentation/feature-experimentation/create-and-manage-flags/create-a-feature-flag#Advanced_Flag_Settings).
* **Bucketing logic:** Once a custom bucketing key is provided through the `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.
#### Requisitos técnicos
Para utilizar eficazmente una clave de bucketing personalizada:
* The key must be a `str`.
* 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).
* La clave debe estar disponible para el SDK en el momento exacto en que se evalúa la decisión del feature flag para ese usuario o solicitud.
### Condiciones de segmentación
Los SDKs de Kameleoon admiten una variedad de condiciones de segmentación predefinidas que puede usar para segmentar a los usuarios en sus campañas. Para ver la lista de condiciones que admite este SDK, consulte [usar el historial de visitas para segmentar a los usuarios](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation).
También puede utilizar sus propios [datos externos para segmentar a los usuarios](/developer-docs/apis/data-api-rest/tutorials/storing-and-retrieving-external-data-to-target-users).
### Registro de eventos
El SDK genera registros que reflejan diversos procesos internos y problemas.
#### Niveles de registro
El SDK admite la configuración para limitar el registro mediante un nivel de log.
```python theme={null}
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)
```
#### Gestión personalizada de los registros
El SDK escribe sus registros en la salida de la consola de forma predeterminada. Este comportamiento puede anularse.
El filtrado por nivel de log se realiza de forma independiente de la lógica de gestión de los registros.
```python theme={null}
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`.
```
## Referencia
This is a full reference documentation of the Python SDK.
#### create()
To start using the SDK, you must complete the initialization. All interactions with the SDK are completed through an object called `Kameleoon::KameleoonClient`, so the first thing you must do is create this object.
```python theme={null}
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")
```
##### Argumentos
| Nombre | Tipo | Descripción |
| ------------ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| site\_code | str | Es la [clave única](/user-manual/faq#how-do-i-find-my-sitecode) del proyecto de Kameleoon que está utilizando con el SDK. Este campo es obligatorio. |
| config | KameleoonClientConfig | Objeto de configuración del SDK que puede pasar en lugar de utilizar un archivo de configuración. Este campo es opcional. |
| config\_path | str | Ruta al archivo de configuración del SDK. Este campo es opcional. El valor predeterminado es `/etc/kameleoon/client-ruby.yaml` |
##### Excepciones lanzadas
| Tipo | Descripción |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| SiteCodeIsEmpty | Exception indicating that the specified site code is an empty string, which is an invalid value. |
| ConfigFileNotFound | Exception indicating that the configuration file was not found. |
#### wait\_init\_async()
`wait_init_async` asynchronously waits for the Kameleoon client's initialization. This method lets you check if the client has been successfully initialized before proceeding with other operations.
```python theme={null}
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.
```
##### Valor de retorno
| Tipo | Descripción |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Coroutine\[Any, Any, bool] | A coroutine that returns `True` if the Kameleoon client instance was successfully initialized, otherwise `False`. |
#### wait\_init()
`wait_init` synchronously waits for the Kameleoon client's initialization. This method lets you check if the client has been successfully initialized before proceeding with other operations.
```python theme={null}
kameleoon_client = KameleoonClientFactory.create('a8st4f59bj')
if kameleoon_client.wait_init():
# The SDK has been initialized; you can fetch a feature flag / experiment configuration here.
```
##### Valor de retorno
| Tipo | Descripción |
| ------ | ---------------------------------------------------------------------------------------- |
| `bool` | `True` if the Kameleoon client instance was successfully initialized, otherwise `False`. |
### Feature flags y variaciones
#### is\_feature\_active()
* 📨 *Envía datos de seguimiento a Kameleoon (dependiendo del parámetro `track`)*
Previously called `activate_feature`—deprecated since SDK version `2.1.0` and will be removed in a future releases.
To check if feature flag is active for a visitor, call the `is_feature_active()` method.
Este método toma un **visitor\_code** and **feature\_key** as mandatory arguments to check if the feature will be active for a given user.
If such a user has never been associated with this feature flag, the SDK returns a boolean value randomly (**true** if feature will be active for the user, or **false** if not). If a user with a given **visitor\_code** is already registered with this feature flag, it will detect the previous **feature flag** value.
Debe asegurarse de que se haya configurado un manejo de errores adecuado en su código, como se muestra en el ejemplo a la derecha, para capturar posibles excepciones.
Si especifica un `visitor_code`, el método `is_feature_active()` usa el `visitor_code` como identificador único del visitante, lo cual es útil para la [experimentación entre dispositivos](/developer-docs/cross-device-experimentation). Cuando especifica un `visitor_code` y establece el parámetro `is_unique_identifier` en `true`, el SDK vincula los datos vaciados con el visitante asociado al identificador especificado.
The parameter `is_unique_identifier` is deprecated. Please use [`UniqueIdentifier`](#uniqueidentifier) instead.
`is_unique_identifier` también puede ser útil en otros escenarios excepcionales, como cuando no puede acceder al `visitor_code` anónimo asignado originalmente al visitante, pero sí tiene acceso a un ID interno conectado al visitante anónimo mediante la fusión de sesiones.
Kameleoon uses tracking to count sessions and visitors when you call certain methods, such as `is_feature_active()`, `get_variation()` or `get_variations()`.
Use el valor predeterminado `True` para el parámetro `track` cuando exponga a los visitantes a una variación y necesite contarlos. Establezca el parámetro `track` en `False` solo si llama a estos métodos antes de exponer a los visitantes.
Por ejemplo, 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.
```python theme={null}
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
```
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**.
##### Argumentos
| Nombre | Tipo | Descripción |
| --------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------- |
| visitor\_code | str | Identificador único del usuario. Este campo es obligatorio. |
| feature\_key | str | ID or Clave de la funcionalidad que desea exponer a un usuario. Este campo es obligatorio. |
| is\_unique\_identifier (Obsoleto) | Optional\[bool] | When set to `True`, the SDK links the flushed data to the visitor associated with the specified identifier. |
| track | bool | An optional parameter to enable or disable tracking of the feature evaluation (`True` by default). |
##### Valor de retorno
| Tipo | Descripción |
| ---- | ---------------------------------------------------------------------- |
| bool | Value of the feature that is registered for a given **visitor\_code**. |
##### Excepciones lanzadas
| Tipo | Descripción |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| FeatureNotFound | Exception indicating that the requested feature ID has not been found in the SDK's internal configuration. This exception is usually normal and means that the feature flag has not yet been activated on Kameleoon's side (but code implementing the feature is already deployed on the web-application's side). |
| VisitorCodeInvalid | Exception indicating that the provided visitor code is not valid (empty or longer than 255 characters). |
#### get\_variation()
* 📨 *Envía datos de seguimiento a Kameleoon (dependiendo del parámetro `track`)*
Recupera la [`Variation`](#variation) asignada a un visitante dado para un feature flag específico.
Este método toma un `visitor_code` and `feature_key` as mandatory arguments. The `track` argument is optional and defaults to `True`.
Devuelve la `Variation` asignada al visitante. Si el visitante no está asociado con ninguna regla de feature flag, el método devuelve la `Variation` predeterminada para el feature flag dado.
Asegúrese de implementar un manejo de errores adecuado en su código para gestionar las posibles excepciones.
La variación predeterminada se refiere a la variación asignada a un visitante cuando no coincide con ninguna regla de entrega predefinida para un feature flag. In other words, it is the fallback variation applied to all users who are not targeted by specific rules. Se representa como la variación en la sección "Then, for everyone else..." de la interfaz de administración.
```python theme={null}
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
```
##### Argumentos
| Name | Type | Description | Default |
| ----------------------------- | ------ | ----------------------------------------------------------------------------------------------------- | ------- |
| visitor\_code (*obligatorio*) | `str` | Identificador único del visitante. | |
| feature\_key (*obligatorio*) | `str` | Clave de la funcionalidad que desea exponer a un visitante. | |
| track (*opcional*) | `bool` | Parámetro opcional para habilitar o deshabilitar el seguimiento de la evaluación de la funcionalidad. | `True` |
##### Valor de retorno
| Tipo | Descripción |
| ----------- | ------------------------------------------------------------------------------------- |
| `Variation` | An assigned [`Variation`](#variation) to a given visitor for a specific feature flag. |
##### Excepciones lanzadas
| Tipo | Descripción |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `VisitorCodeInvalid` | Excepción que indica que el visitor code proporcionado no es válido. It is either empty or longer than 255 characters. |
| `FeatureNotFound` | Excepción que indica que la clave de funcionalidad solicitada no se encontró en la configuración interna del SDK. Esto suele significar que el feature flag no está activado en la aplicación de Kameleoon (pero el código que implementa la funcionalidad ya está desplegado en la aplicación). |
| `FeatureEnvironmentDisabled` | Excepción que indica que el feature flag está deshabilitado para el entorno actual del visitante (por ejemplo, production, staging o development). |
#### get\_variations()
* 📨 *Envía datos de seguimiento a Kameleoon (dependiendo del parámetro `track`)*
Recupera un map de objetos [`Variation`](#variation) asignados a un visitante dado para todos los feature flags.
Este método itera sobre todos los feature flags disponibles y devuelve la `Variation` asignada para cada flag asociado con el visitante especificado. 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.
* El parámetro `track` controla si el método realizará el seguimiento de las asignaciones de variación. De forma predeterminada, it is set to `True`. If set to `False`, the tracking will be disabled.
El map devuelto consta de claves de feature flags como claves y su `Variation` correspondiente como valores. Si no se asigna ninguna variación para un feature flag, el método devuelve la `Variation` predeterminada para ese flag.
Se debe implementar un manejo de errores adecuado para gestionar las posibles excepciones.
La variación predeterminada se refiere a la variación asignada a un visitante cuando no coincide con ninguna regla de entrega predefinida para un feature flag. In other words, it is the fallback variation applied to all users who are not targeted by specific rules. Se representa como la variación en la sección "Then, for everyone else..." de la interfaz de administración.
```python theme={null}
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
```
##### Argumentos
| Name | Type | Description | Default |
| ----------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | ------- |
| visitor\_code (*obligatorio*) | `str` | Identificador único del visitante. | |
| only\_active (*opcional*) | `bool` | An optional parameter indicating whether to return variations for active (`True`) or all (`False`) feature flags. | `False` |
| track (*opcional*) | `bool` | Parámetro opcional para habilitar o deshabilitar el seguimiento de la evaluación de la funcionalidad. | `True` |
##### Valor de retorno
| Tipo | Descripción |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Dict[str, Variation]` | Map que contiene los objetos [`Variation`](#variation) asignados de los feature flags utilizando las claves de las funcionalidades correspondientes. |
##### Excepciones lanzadas
| Tipo | Descripción |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | Excepción que indica que el visitor code proporcionado no es válido. It is either empty or longer than 255 characters. |
#### get\_data\_file()
To evaluate all feature flags, use [`get_variations()`](#get_variations). This method is more efficient than calling `DataFile` and iterating through flags with [`get_variation()`](#get_variation).
Devuelve la configuración actual del SDK como un objeto [`DataFile`](#datafile).
```python theme={null}
data_file = kameleoon_client.get_data_file()
date_modified = data_file.date_modified
```
##### Valor de retorno
| Tipo | Descripción |
| ---------- | ---------------------------------------------------------------- |
| `DataFile` | El [`DataFile`](#datafile) que contiene la configuración del SDK |
#### set\_forced\_variation()
El método permite you to programmatically assign a specific [`Variation`](#variation) to a user, bypassing the standard evaluation process. Esto es especialmente valioso para experimentos controlados donde la lógica de evaluación habitual no es necesaria o debe omitirse. It can also be helpful in scenarios like debugging or custom testing.
Cuando se establece una variación **forzada**, esta anula la lógica de evaluación en tiempo real de Kameleoon. 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.
El método puede lanzar excepciones bajo ciertas condiciones (por ejemplo, parámetros no válidos, contexto del usuario o problemas internos). Proper exception handling is essential to ensure that your application remains stable and resilient.
It’s important to distinguish **forced** variations from **[simulated](#get_visitor_code)** variations:
* **Forced variations**: Are specific to an individual experiment.
* **Simulated variations**: Affect the overall **feature flag** result.
```python theme={null}
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
```
##### Argumentos
| Name | Type | Description | Default |
| ------------------------------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| visitor\_code (*obligatorio*) | `str` | Identificador único del visitante. | |
| experiment\_id (*obligatorio*) | `int` | **Experiment Id** que será segmentado y seleccionado durante el proceso de evaluación. | |
| variation\_key (*obligatorio*) | `Optional[str]` | **Variation Key** correspondiente a una `Variation` que debe forzarse como valor devuelto para el experimento. If the value is `None`, the forced variation will be reset. | |
| force\_targeting (*opcional*) | `bool` | Indicates whether targeting for the experiment should be forced and skipped (`True`) or applied as in the standard evaluation process (`False`). | `True` |
##### Excepciones lanzadas
| Tipo | Descripción |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | Excepción que indica que el visitor code proporcionado no es válido. It is either empty or longer than 255 characters. |
| `FeatureExperimentNotFound` | Excepción que indica que el experiment id solicitado no se encontró en la configuración interna del SDK. Esto suele ser normal y significa que el experimento correspondiente a la regla todavía no se ha activado del lado de Kameleoon. |
| `FeatureVariationNotFound` | Excepción que indica que la variation key (id) solicitada no se ha encontrado en la configuración interna del SDK. Esto suele ser normal y significa que el experimento correspondiente a la variación todavía no se ha activado del lado de Kameleoon. |
In most cases, only the basic error, `KameleoonError`, needs to be handled, as demonstrated in the example. However, if different types of errors require a response, handle each one separately based on specific requirements. Additionally, for enhanced reliability, general language errors can be handled by including `Exception`.
#### evaluate\_audiences()
* 📨 *Envía datos de seguimiento a Kameleoon*
Este método evalúa a los visitantes con respecto a todos los segmentos disponibles de Audiences Explorer y realiza el seguimiento de los que coinciden.
`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. Este enfoque garantiza que el visitante se evalúe con los datos más recientes disponibles, lo que permite una asignación precisa de audiencia basada en todos los criterios.
After calling this method, you can perform a detailed analysis of segment performance in Audiences Explorer.
```python theme={null}
try:
kameleoon_client.evaluate_audiences(visitor_code)
except KameleoonError as e:
# Handling the error
```
##### Argumentos
| Nombre | Tipo | Descripción |
| ----------------------------- | ----- | ---------------------------------- |
| visitor\_code (*obligatorio*) | `str` | Identificador único del visitante. |
##### Excepciones lanzadas
| Tipo | Descripción |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | Excepción que indica que el visitor code proporcionado no es válido. It is either empty or longer than 255 characters. |
In most cases, only the basic error, `KameleoonError`, needs to be handled, as demonstrated in the example. However, if different types of errors require a response, handle each one separately based on specific requirements. Additionally, for enhanced reliability, general language errors can be handled by including `Exception`.
### Datos del visitante
#### get\_visitor\_code()
This method was previously called `obtain_visitor_code`, which was removed in SDK version `3.0.0`.
Se debe llamar al método auxiliar `get_visitor_code()` para obtener el **visitor\_code** de Kameleoon del visitante actual. Este método es especialmente importante al utilizar Kameleoon en un entorno mixto de front-end y back-end, donde se debe garantizar la consistencia en la identificación del usuario. La lógica de implementación se describe a continuación:
1. First we check if a **kameleoonVisitorCode** cookie or query parameter associated with the current HTTP request can be found. If so, we will use this as the visitor identifier.
2. If no cookie/parameter is found in the current request, we either randomly generate a new identifier, or use the **default\_visitor\_code** argument as an identifier if it is passed. This allows our customers to use their own identifiers as visitor codes, should they wish to, which has the added benefit of matching Kameleoon visitors with their own users without any additional look-ups in a matching table.
3. In any case, the server-side (via HTTP header) **kameleoonVisitorCode** cookie is set with the value. Then, this identifier value is finally returned by the method.
If you provide your own `visitor_code`, you must guarantee its uniqueness. The SDK doesn't validate the value passed as an argument. Also note that the length of `visitor_code` is limited to **255** characters. A `VisitorCodeInvalid` exception is raised if this limit is exceeded.
The `get_visitor_code()` method allows you to set **simulated** variations for a visitor. Cuando las cookies (de una **request** o **document**) contienen la clave `kameleoonSimulationFFData`, se omite el proceso de evaluación estándar. En su lugar, el método devuelve directamente una [`Variation`](#variation) basada en los datos proporcionados.
Puede aplicar simulaciones de dos formas:
* **Automatically (recommended):** If using Kameleoon Web Experimentation or the SDK in [Hybrid mode](/developer-docs/feature-experimentation/get-started/hybrid-experimentation#linking-feature-experiments-with-front-end-tracking-code), the cookie is created automatically when simulating a variant's display using the [Simulation Panel](/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/validation-and-rollback/using-simulation-mode).
* **Manualmente:** Establezca la cookie `kameleoonSimulationFFData` manualmente.
It’s important to distinguish **simulated** variations from **[forced](#set_forced_variation)** variations:
* **Simulated variations**: Affect the overall **feature flag** result.
* **Forced variations**: Are specific to an individual experiment.
⚙️ **Manual setup**
Asegúrese de que la cookie `kameleoonSimulationFFData` siga este formato:
* `kameleoonSimulationFFData={"featureKey":{"expId":10,"varId":20}}`: Simula la variación con `varId` del experimento `expId` para el `featureKey` indicado.
* `kameleoonSimulationFFData={"featureKey":{"expId":0}}`: Simula la variación predeterminada (definida en la sección **Then, for everyone else in Production, serve**) para el `featureKey` indicado.
⚠️ To ensure proper functionality, the cookie value must be encoded as a URI component using a method such as [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent).
```python theme={null}
### 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()
```
##### Argumentos
| Nombre | Tipo | Descripción |
| ---------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cookies\_readonly | Optional\[Dict\[str, str]] | Read-only dictionary, usually `request.COOKIES`. Use this parameter if you also use the `KameleoonWSGIMiddleware` service. Este campo es opcional. |
| cookies | Optinal\[Dict\[str, http.cookies.Morsel\[str]]] | Pass cookies on the current HTTP request as a`Dict[str, http.cookies.Morsel[str]]` or `http.cookies.\|SimpleCookie[str]` object if you manage cookies manually without `KameleoonWSGIMiddleware` service. Este campo es opcional. |
| default\_visitor\_code | str | This parameter will be used as the **visitor\_code** if no existing **kameleoonVisitorCode** cookie is found in the request. This field is optional, and by default, a random **visitor\_code** will be generated. |
##### Valor de retorno
| Type | Description |
| ---- | ---------------------------------------------------------------------------------------------------------------------- |
| str | A **visitor\_code** that will be associated with this particular user and should be used with most of our SDK methods. |
##### Excepciones lanzadas
| Type | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------------- |
| VisitorCodeInvalid | Excepción que indica que el visitor code proporcionado no es válido. Está vacío o tiene más de 255 caracteres. |
#### add\_data()
El método `add_data()` añade [datos de segmentación](#tipos-de-datos) al almacenamiento para que otros métodos puedan utilizar los datos para decidir si segmentar o no al visitante actual.
El método `add_data()` no devuelve ningún valor y no interactúa por sí mismo con los servidores backend de Kameleoon. En su lugar, todos los datos declarados se guardan para su transmisión futura mediante el método [`flush()`](#flush). Este enfoque reduce el número de llamadas al servidor, ya que los datos se agrupan habitualmente en una única llamada al servidor que desencadena el `flush()`.
El método [`track_conversion()`](#track_conversion) también envía cualquier dato previamente asociado, al igual que `flush()`. Lo mismo aplica para los métodos [`get_variation()`](#get_variation) y [`get_variations()`](#get_variations) si se desencadena una regla de experimentación.
Cada visitante solo puede tener una instancia de datos asociados para la mayoría de los tipos de datos. However, [`CustomData`](#customdata) is an exception. Visitors can have one instance of associated `CustomData` per index.
```python theme={null}
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
)
```
##### Argumentos
| Nombre | Tipo | Descripción | Valor predeterminado |
| ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| visitor\_code (*obligatorio*) | `str` | Identificador único del visitante. | |
| data (*obligatorio*) | `*Data` | Colección de tipos de datos de Kameleoon. | |
| track (*opcional*) | `bool` | Especifica si los datos añadidos son aptos para el seguimiento. 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` |
##### Excepciones
| Tipo | Descripción |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | Excepción que indica que el visitor code proporcionado no es válido. It is either empty or longer than 255 characters. |
#### flush()
* 📨 *Envía datos de seguimiento a Kameleoon*
`flush()` takes the Kameleoon data associated with the visitor and all of the data that was added previously using the `add_data` method, that has not yet been sent when calling one of [these methods](/developer-docs/feature-experimentation/technical-reference/faq-global#when-does-the-sdk-send-a-tracking-request-for-analytics), and sends a tracking request. `flush()` is non-blocking, as the server call is made asynchronously.
`flush()` lets you control when the data associated with a given `visitor_code` is sent to our servers. For instance, if you call `add_data()` a dozen times, it would be inefficient to send data to the server each time `add_data()` is invoked, so you only have to call `flush()` once at the end.
Si especifica un `visitor_code`, el método `flush()` lo usa como identificador único del visitante, lo cual es útil para la [experimentación entre dispositivos](/developer-docs/cross-device-experimentation). Cuando especifica un `visitor_code` y establece el parámetro `is_unique_identifier` en `true`, el SDK vincula los datos vaciados con el visitante asociado al identificador especificado.
The parameter `is_unique_identifier` is deprecated. Please use [`UniqueIdentifier`](#uniqueidentifier) instead.
`is_unique_identifier` también puede ser útil en otros escenarios excepcionales, como cuando no puede acceder al `visitor_code` anónimo asignado originalmente al visitante, pero sí tiene acceso a un ID interno conectado al visitante anónimo mediante la fusión de sesiones.
```python theme={null}
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)
```
##### Argumentos
| Nombre | Tipo | Descripción |
| --------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| visitor\_code | String | Identificador único del usuario. Este campo es obligatorio. |
| is\_unique\_identifier (Obsoleto) | Optional\[bool] | When `True`, the SDK links the flushed data to the visitor associated with the specified identifier. |
| instant | bool | Boolean flag indicating whether the data should be sent instantly (`True`) or according to the scheduled tracking interval (`False`). If not provided, el valor predeterminado es `False`. Este campo es opcional. |
#### get\_remote\_data()
* Previously called `retrieve_data_from_remote_source`, which was removed in SDK version `3.0.0`.
* If you want to retrieve data asynchronously, use the `get_remote_data_async` method instead (available since version 2.3.0).
The `get_remote_data` method retrieves data synchronously (according to a **key** passed as argument) for a specified **site\_code** (specified with `KameleoonClient.__init__`) stored on a remote Kameleoon server. Data is usually stored in our remote servers via our Data API. This method, along with the availability of our highly scalable servers for this purpose, provides a convenient method for storing massive amounts of data that can be retrieved for each of your visitors/users.
```python theme={null}
kameleoon_client.get_remote_data('key1') # default timeout
kameleoon_client.get_remote_data('key2', 1.0) # 1 second timeout
```
##### Argumentos
| Nombre | Tipo | Descripción |
| ------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | str | The key the data is associated with. Este campo es obligatorio. |
| timeout | Optional\[float] | Timeout (in seconds). This parameter specifies the maximum amount of time the method can block to wait for a result. This field is optional; if not provided, it will use the `default_timeout_millisecond` value from configuration file, or two seconds if it's not specified in the file. |
##### Valor de retorno
| Tipo | Descripción |
| ----------- | ----------------------------------------------------------------- |
| JSON object | JSON object associated with retrieving data for specific **key**. |
#### get\_remote\_data\_async()
The `get_remote_data_async` method lets you retrieve data asynchronously (according to a **key** passed as argument) for specified **site\_code** (specified with `KameleoonClient.__init__`) stored in a remote Kameleoon server. Data is usually stored on our remote servers via our Data API. This method, along with the availability of our highly scalable servers for this purpose, provides a convenient method for storing massive amounts of data that can be retrieved for each of your visitors/users.
```python theme={null}
await kameleoon_client.get_remote_data_async('key1') # default timeout
await kameleoon_client.get_remote_data_async('key2', 1.0) # 1 second timeout
```
##### Argumentos
| Name | Type | Description |
| ------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | str | The key the data is associated with. Este campo es obligatorio. |
| timeout | Optional\[float] | Timeout (in seconds). This parameter specifies the maximum amount of time the method can block to wait for a result. This field is optional; if not provided, it will use the `default_timeout_millisecond` value from configuration file or two seconds if it's not specified in the file. |
##### Valor de retorno
| Tipo | Descripción |
| ----------- | ------------------------------------------------------------------- |
| JSON object | JSON object associated with retrieving data for a specific **key**. |
#### get\_remote\_visitor\_data()
`get_remote_visitor_data()` is an asynchronous method for retrieving Kameleoon Visits Data for the `visitor_code` from the Kameleoon Data API. El método añade los datos al almacenamiento para que otros métodos los utilicen al tomar decisiones de segmentación.
Los datos obtenidos mediante este método desempeñan un papel importante cuando desea:
* use data collected from other devices.
* access a user's history, such as visited pages during past visits.
* use data that is only accessible on the client-side, like datalayer variables and goals that only convert on the front-end.
Read [this article](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation) for a better understanding of possible use cases.
De forma predeterminada, `get_remote_visitor_data()` automatically retrieves the latest stored custom data with `scope=visitor` and attaches them to the visitor without the need to call the `add_data()` method. It is particularly useful for [synchronizing custom data between multiple devices](/developer-docs/sdks/web-sdks/nodejs-sdk#synchronizing-custom-data-across-devices).
The parameter `is_unique_identifier` is deprecated. Please use [`UniqueIdentifier`](#uniqueidentifier) instead.
`is_unique_identifier` también puede ser útil en otros escenarios excepcionales, como cuando no puede acceder al `visitor_code` anónimo asignado originalmente al visitante, pero sí tiene acceso a un ID interno conectado al visitante anónimo mediante la fusión de sesiones.
```python theme={null}
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)
```
##### Argumentos
| Nombre | Tipo | Descripción |
| --------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitor\_code | str | The visitor code for which you want to retrieve the assigned data. Este campo es obligatorio. |
| add\_data | bool | Booleano que indica si el método debe añadir automáticamente los datos recuperados para un visitante. If not specified, el valor predeterminado es **True**. Este campo es opcional. |
| data\_filter | RemoteVisitorDataFilter | Filter that specifies what data should be retrieved from visits. De forma predeterminada, only `CustomData` is retrieved from the current and latest previous visit (`RemoteVisitorDataFilter(previousVisitAmount=1, currentVisit=True, customData=True)` or `RemoteVisitorDataFilter()`). Other filters parameters are set to `False`. Este campo es opcional. |
| is\_unique\_identifier (Obsoleto) | Optional\[bool] | Parámetro opcional para indicar si el `visitorCode` es un identificador único. If not provided, el valor predeterminado es `False`. Este campo es opcional. |
| timeout | Optional\[float] | Timeout (in seconds). This parameter specifies the maximum amount of time the method can block to wait for a result. This field is optional; if not provided, it will use the `default_timeout_millisecond` value from configuration file or two seconds if it's not specified in the file. |
##### Using parameters in get\_remote\_visitor\_data()
El método `get_remote_visitor_data()` ofrece flexibilidad al permitirle definir varios parámetros al recuperar datos de los visitantes. Ya sea que esté segmentando en función de objetivos, experimentos o variaciones, el mismo enfoque se aplica a todos los tipos de datos.
Por ejemplo, suppose you want to retrieve data on visitors who completed the goal "Order transaction". You can specify parameters within the `get_remote_visitor_data()` method to refine your targeting. For instance, if you want to target only users who converted on the goal in their last five visits, you can set the `previous_visit_amount` parameter to 5 and `conversions` to true.
La flexibilidad mostrada en este ejemplo no se limita a los datos de objetivos. Puede usar parámetros dentro del método `get_remote_visitor_data()` para recuperar datos sobre una variedad de comportamientos del visitante.
##### Valor de retorno
| Tipo | Descripción |
| ----------- | --------------------------------------------- |
| List\[Data] | A list of data assigned to the given visitor. |
Here is the list of available `Kameleoon::Configuration::RemoteVisitorDataFilter` options:
| Name | Type | Description | Default |
| ------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| previous\_visit\_amount (*opcional*) | `int` | Número de visitas previas de las que recuperar datos. Number between `1` and `25` | `1` |
| current\_visit (*opcional*) | `bool` | If True, current visit data will be retrieved | `True` |
| custom\_data (*opcional*) | `bool` | If True, custom data will be retrieved. | `True` |
| page\_views (*opcional*) | `bool` | If True, page data will be retrieved. | `False` |
| geolocation (*opcional*) | `bool` | If True, geolocation data will be retrieved. | `False` |
| device (*opcional*) | `bool` | If True, device data will be retrieved. | `False` |
| browser (*opcional*) | `bool` | If True, browser data will be retrieved. | `False` |
| operating\_system (*opcional*) | `bool` | If True, operating system data will be retrieved. | `False` |
| conversions (*opcional*) | `bool` | If True, conversion data will be retrieved. | `False` |
| experiments (*opcional*) | `bool` | If True, experiment data will be retrieved. | `False` |
| kcs (*opcional*) | `bool` | If true, Kameleoon Conversion Score (KCS) will be retrieved. Requires the [AI Predictive Targeting add-on](/user-manual/ai-predictive-targeting/target-users-based-on-likelihood-to-convert) | `False` |
| visitor\_code (*opcional*) | `bool` | If true, Kameleoon will retrieve the `visitorCode` from the most recent visit and use it for the current visit. This is necessary if you want to ensure that the visitor, identified by their `visitorCode`, always receives the same variation across visits for [cross-device experimentation](/developer-docs/cross-device-experimentation). | `True` |
| cbs (*opcional*) | `bool` | If true, Contextual Bandit score data will be retrieved. | `False` |
| personalization (*opcional*) | `bool` | If True, personalization data will be retrieved. This is required for the personalization condition. | `False` |
#### get\_remote\_visitor\_data\_async()
El método `get_remote_visitor_data_async` recupera de forma asíncrona los datos personalizados almacenados en los servidores remotos de Kameleoon para un visitante (especificado mediante el argumento **visitor\_code**). Si **add\_data** es **True**, este método añade automáticamente los datos recuperados al visitante sin necesidad de realizar una llamada `add_data` por separado.
Debe haber almacenado previamente datos en nuestros servidores remotos, los cuales puede añadir con cualquiera de las siguientes llamadas de seguimiento del SDK:
* `flush`
* `get_feature_variation_key`
* `get_feature_variable`
* `is_feature_active`
Using the `get_remote_visitor_data` method along with the availability of our highly scalable servers provides a convenient method for accessing and synchronizing large amounts of data across all of the visitor's devices.
If you specify a `visitor_code`, the `get_remote_visitor_data_async` method uses the `visitor_code` as the unique visitor identifier, which is useful for [cross-device experimentation](/developer-docs/cross-device-experimentation). When you specify a `visitor_code` and set the `is_unique_identifier` parameter to `true`, the SDK links the flushed data to the visitor associated with the specified identifier.
The parameter `is_unique_identifier` is deprecated. Please use [`UniqueIdentifier`](#uniqueidentifier) instead.
`is_unique_identifier` también puede ser útil en otros escenarios excepcionales, como cuando no puede acceder al `visitor_code` anónimo asignado originalmente al visitante, pero sí tiene acceso a un ID interno conectado al visitante anónimo mediante la fusión de sesiones.
```python theme={null}
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)
```
##### Argumentos
| Nombre | Tipo | Descripción |
| --------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitor\_code | str | The visitor code for which you want to retrieve the assigned data. Este campo es obligatorio. |
| add\_data | bool | Booleano que indica si el método debe añadir automáticamente los datos recuperados para un visitante. If not specified, el valor predeterminado es **True**. Este campo es opcional. |
| data\_filter | RemoteVisitorDataFilter | Filter that specifies which data should be retrieved from visits. De forma predeterminada, only `CustomData` is retrieved from the current and latest previous visit (`RemoteVisitorDataFilter(previousVisitAmount=1, currentVisit=True, customData=True)` or `RemoteVisitorDataFilter()`). Other filters parameters are set to `False`. Este campo es opcional. |
| is\_unique\_identifier (Obsoleto) | Optional\[bool] | Parámetro opcional para indicar si el `visitorCode` es un identificador único. If not provided, el valor predeterminado es `False`. The field is optional. |
| timeout | Optional\[float] | Timeout (in seconds). This parameter specifies the maximum amount of time the method can block to wait for a result. This field is optional; if not provided, it will use the `default_timeout_millisecond` value from configuration file or two seconds if it's not specified in the file. |
##### Valor de retorno
| Tipo | Descripción |
| ----------- | --------------------------------------- |
| List\[Data] | A list of data assigned to the visitor. |
##### Using parameters in get\_remote\_visitor\_data\_async()
El método `get_remote_visitor_data_async()` ofrece flexibilidad al permitirle definir varios parámetros al recuperar datos de los visitantes. Ya sea que esté segmentando en función de objetivos, experimentos o variaciones, el mismo enfoque se aplica a todos los tipos de datos.
Por ejemplo, suppose you want to retrieve data on visitors who completed the goal "Order transaction". You can specify parameters within the `get_remote_visitor_data_async()` method to refine your targeting. For instance, if you want to target only users who converted on the goal in their last five visits, you can set the `previous_visit_amount` parameter to 5 and `conversions` to true.
La flexibilidad mostrada en este ejemplo no se limita a los datos de objetivos. Puede usar parámetros dentro del método `get_remote_visitor_data_async()` para recuperar datos sobre una variedad de comportamientos del visitante.
Here is the list of available `Kameleoon::Configuration::RemoteVisitorDataFilter` options:
| Name | Type | Description | Default |
| ------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| previous\_visit\_amount (*opcional*) | `int` | Número de visitas previas de las que recuperar datos. Number between `1` and `25` | `1` |
| current\_visit (*opcional*) | `bool` | If True, current visit data will be retrieved | `True` |
| custom\_data (*opcional*) | `bool` | If True, custom data will be retrieved. | `True` |
| page\_views (*opcional*) | `bool` | If True, page data will be retrieved. | `False` |
| geolocation (*opcional*) | `bool` | If True, geolocation data will be retrieved. | `False` |
| device (*opcional*) | `bool` | If True, device data will be retrieved. | `False` |
| browser (*opcional*) | `bool` | If True, browser data will be retrieved. | `False` |
| operating\_system (*opcional*) | `bool` | If True, operating system data will be retrieved. | `False` |
| conversions (*opcional*) | `bool` | If True, conversion data will be retrieved. | `False` |
| experiments (*opcional*) | `bool` | If True, experiment data will be retrieved. | `False` |
| kcs (*opcional*) | `bool` | If true, Kameleoon Conversion Score (KCS) will be retrieved. Requires the [AI Predictive Targeting add-on](/user-manual/ai-predictive-targeting/target-users-based-on-likelihood-to-convert) | `False` |
| visitor\_code (*opcional*) | `bool` | If true, Kameleoon will retrieve the `visitorCode` from the most recent visit and use it for the current visit. This is necessary if you want to ensure that the visitor, identified by their `visitorCode`, always receives the same variation across visits for [Cross-device experimentation](/developer-docs/cross-device-experimentation). | `True` |
| cbs (*opcional*) | `bool` | If true, Contextual Bandit score data will be retrieved. | `False` |
#### get\_visitor\_warehouse\_audience()
Synchronously retrieves all audience data associated with the visitor in your data warehouse using the specified **visitor\_code** and **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. You can refer to the [warehouse targeting documentation](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting) for additional details. El método devuelve a `CustomData` object, confirming that the data has been added to the visitor and is available for targeting purposes.
If you want to retrieve the data asynchronously, use the `get_visitor_warehouse_audience_async` method instead.
```python theme={null}
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
```
##### Argumentos
| Nombre | Tipo | Descripción |
| ------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitor\_code | str | A unique visitor identification string, can't exceed 255 characters length. Este campo es obligatorio. |
| custom\_data\_index | int | Entero que representa el índice del dato personalizado que desea utilizar para segmentar sus BigQuery Audiences. Este campo es obligatorio. |
| warehouse\_key | Optional\[str] | A unique key identifying the warehouse data (usually your internal user ID). Este campo es opcional. |
| timeout | Optional\[float] | Timeout (in seconds). This parameter specifies the maximum amount of time to wait for a result. Este campo es opcional. If not provided, el valor predeterminado es 10 seconds. |
##### Valor de retorno
| Tipo | Descripción |
| --------------------- | ------------------------------------------------------------------------------- |
| Optional\[CustomData] | A `CustomData` instance confirming that the data has been added to the visitor. |
##### Excepciones lanzadas
| Tipo | Descripción |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| VisitorCodeInvalid | Excepción que indica que el visitor code proporcionado no es válido. It is either empty or longer than 255 characters. |
#### get\_visitor\_warehouse\_audience\_async()
Asynchronously retrieves all audience data associated with the visitor in your data warehouse using the specified **visitor\_code** and **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. You can refer to the [warehouse targeting documentation](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting) for additional details. El método devuelve a `CustomData` object, confirming that the data has been added to the visitor and is available for targeting purposes.
```python theme={null}
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
```
##### Argumentos
| Nombre | Tipo | Descripción |
| ------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitor\_code | str | A unique visitor identification string, can't exceed 255 characters length. Este campo es obligatorio. |
| custom\_data\_index | int | Entero que representa el índice del dato personalizado que desea utilizar para segmentar sus BigQuery Audiences. Este campo es obligatorio. |
| warehouse\_key | Optional\[str] | A unique key identifying the warehouse data (usually your internal user ID). Este campo es opcional. |
| timeout | Optional\[float] | Timeout (in seconds). This parameter specifies the maximum amount of time to wait for a result. Este campo es opcional. If not provided, el valor predeterminado es 10 seconds. |
##### Valor de retorno
| Type | Description |
| --------------------- | ------------------------------------------------------------------------------- |
| Optional\[CustomData] | A `CustomData` instance confirming that the data has been added to the visitor. |
##### Excepciones lanzadas
| Tipo | Descripción |
| ------------------ | -------------------------------------------------------------------------------------------------------------- |
| VisitorCodeInvalid | Excepción que indica que el visitor code proporcionado no es válido. Está vacío o tiene más de 255 caracteres. |
#### set\_legal\_consent()
You must use this method to specify whether the visitor has given legal consent to use personal data. Setting the `consent` parameter to `False` limits the types of data that you can include in tracking requests. This method helps you adhere to legal and regulatory requirements while responsibly managing visitor data. You can find more information on personal data in our [consent management policy](/user-manual/project-management/consent-management-policy).
```python theme={null}
### 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()
```
##### Comportamiento al revocar el consentimiento
Cuando llama a `set_legal_consent()` con `consent=False`, el SDK no elimina la cookie `kameleoonVisitorCode`. En su lugar, deja de prorrogar la fecha de expiración de la cookie, permitiendo que esta persista hasta que expire de forma natural.
Si sus requisitos de cumplimiento exigen la eliminación inmediata del archivo de cookie al revocar el consentimiento, debe eliminarlo manualmente utilizando los métodos nativos de gestión de cookies de su framework. El SDK no eliminará el archivo automáticamente.
##### Argumentos
| Nombre | Tipo | Descripción |
| ------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitor\_code | str | Identificador único del usuario. Este campo es obligatorio. |
| consent | bool | Valor booleano que representa el estado del consentimiento legal. `true` indicates the visitor has given legal consent, `false` indicates the visitor has never provided or withdrawn legal consent. Este campo es obligatorio. |
| cookies | Optional\[Dict\[str, http.cookies.Morsel\[str]]] | The cookies to be adjusted based on the legal consent status as `Dict[str, http.cookies.Morsel[str]]` or `http.cookies.SimpleCookie[str]` object. Este campo es opcional. |
##### Excepciones lanzadas
| Tipo | Descripción |
| ------------------ | -------------------------------------------------------------------------------------------------------------- |
| VisitorCodeInvalid | Excepción que indica que el visitor code proporcionado no es válido. Está vacío o tiene más de 255 caracteres. |
#### forget()
El método `forget` elimina una instancia de `KameleoonClient` del `KameleoonClientFactory` con el **site\_code** especificado y libera los recursos utilizados por la instancia de `KameleoonClient`. La instancia de `KameleoonClient` no debe utilizarse después de llamar al método `forget`.
Si especifica un `visitor_code`, el método `track_conversion` usa el `visitor_code` como identificador único del visitante, lo cual es útil para la [experimentación entre dispositivos](/developer-docs/cross-device-experimentation). Cuando especifica un `visitor_code` y establece el parámetro `is_unique_identifier` en `true`, el SDK vincula los datos vaciados con el visitante asociado al identificador especificado.
`is_unique_identifier` también puede ser útil en otros escenarios excepcionales, como cuando no puede acceder al `visitor_code` anónimo asignado originalmente al visitante, pero sí tiene acceso a un ID interno conectado al visitante anónimo mediante la fusión de sesiones.
```python theme={null}
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)
```
##### Argumentos
| Nombre | Tipo | Descripción |
| ---------------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| visitor\_code | String | Identificador único del usuario. Este campo es obligatorio. |
| goal\_id | int | ID del objetivo. Este campo es obligatorio. |
| revenue | float | Ingreso de la conversión. Este campo es opcional. |
| is\_unique\_identifier | bool | When `True`, the SDK links the flushed data to the visitor associated with the specified identifier. |
### Objetivos y analítica de terceros
#### 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.
Consulte [experimentación híbrida](/developer-docs/feature-experimentation/get-started/hybrid-experimentation) para más información sobre cómo implementar este método.
```python theme={null}
engine_tracking_code = kameleoon_client.get_engine_tracking_code(visitor_code)
```
* To use this feature, implement both the Python SDK and Kameleoon [Engine.js](/developer-docs/web-experimentation/implementation-and-deployment/standard-implementation). Because Engine.js is used only for tracking in this flow, you can install the asynchronous tag before the closing `` 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](/developer-docs/sdks/web-sdks/js-sdk). This option works well for [serverless edge compute platforms](/developer-docs/feature-experimentation/implementation-and-deployment/serverless-edge-compute-starter-kits). The JavaScript / TypeScript SDK automatically tracks variations when you call [`getVisitorCode`](/developer-docs/sdks/web-sdks/js-sdk#getvisitorcode), as long as you add the corresponding experiment assignments to `window.kameleoonQueue`..
* You can insert the returned tracking code directly into an HTML `