SDK de Python - Kameleoon Documentation

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. Changelog: Última versión del SDK de Python: 3.18.0 Changelog. Métodos del SDK: Para la documentación de referencia completa del SDK de Python, consulte la sección referencia.

Guía del desarrollador

Esta guía le ayuda a integrar el SDK en unos minutos y comenzar a ejecutar experimentos en sus aplicaciones Python. Este tutorial explicará la configuración de una prueba A/B simple para cambiar el número de productos recomendados en función de diferentes variaciones.

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:

pip install kameleoon-client-python

Configuración adicional

Debe proporcionar las credenciales del SDK de Python mediante un archivo de configuración, que también puede utilizar para personalizar el comportamiento del SDK. Un archivo de configuración de ejemplo puede obtenerse aquí. Le sugerimos instalar este archivo en la ruta predeterminada /etc/kameleoon/client-python.yaml, pero puede colocarlo en otra ubicación y pasar la ruta como argumento al método constructor KameleoonClient(). Con la versión actual del SDK de Python, estas son las claves disponibles:

Clave	Descripción	Valor predeterminado
`client_id` obligatorio	Obligatorio para la autenticación en el servicio Kameleoon. Para encontrar su client id, consulte la documentación Credenciales de API.
`client_secret` obligatorio	Obligatorio para la autenticación en el servicio Kameleoon. Para encontrar su client secret, consulte la documentación Credenciales de API.
`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 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 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` (Obsoleto)	Permite anular el registrador de Python predeterminado. Este campo es obsoleto y se eliminará en la versión `4.0.0` del SDK. Utilice `KameleoonLogger.set_logger()` en su lugar.	`logging.Logger`
`multi_threading` (Obsoleto)	Una opción de tipo `bool` que indica si los hilos pueden utilizarse para solicitudes de red. De forma predeterminada, todo se ejecuta en un hilo para evitar problemas de rendimiento con GIL si se está utilizando el intérprete de Python (C). Valores posibles: `True`, `False`.	`None`

Alternativamente, puede utilizar configuration_object de tipo KameleoonClientConfig como parámetro durante la inicialización. Tiene la misma lista de argumentos que un archivo de configuración. configuration_object tiene prioridad sobre el archivo de configuración e invalida su configuración.

Inicialización del cliente Kameleoon

Después de instalar el SDK en su aplicación, configurar las credenciales correctas (en /etc/kameleoon/client-python.yaml) y configurar un experimento del lado del servidor en el back-office de Kameleoon, el siguiente paso es crear el cliente Kameleoon en el código de su aplicación. 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.

Los desarrolladores son responsables de garantizar la lógica correcta de su código de aplicación al implementar pruebas A/B con Kameleoon. Una práctica recomendada es asumir siempre que un visitante puede excluirse del experimento si aún no se ha lanzado. Esta práctica es simple de implementar, ya que se alinea con la lógica de variación predeterminada o de referencia, que siempre debe estar en su lugar. Los ejemplos de código de la siguiente sección demuestran este enfoque.

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

Para asignar un ID único a un usuario, puede utilizar el método get_visitor_code(). Si un visitor code no existe (desde la cookie del encabezado de solicitud), el método genera un ID único aleatorio o utiliza un default_visitor_code que habría generado. El ID se establece luego en una cookie del encabezado de respuesta. Si está usando Kameleoon en modo híbrido, 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. Para determinar el estado o la variación de un feature flag para un usuario específico, debe utilizar el método get_variation() o is_feature_active() para recuperar la configuración basada en el 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. Si su feature flag tiene variables asociadas (como comportamientos específicos vinculados a cada variación), get_variation() también le permite acceder al objeto Variation, que proporciona detalles sobre la variación asignada y su experimento asociado. Este método verifica si el usuario está dirigido, encuentra la variación asignada del visitante y la guarda en el almacenamiento. Cuando track=True, el SDK enviará el evento de exposición al experimento especificado en la siguiente solicitud de seguimiento, que se activa automáticamente según el tracking_interval_millisecond del SDK. De forma predeterminada, este intervalo se establece en 1000 milisegundos (1 segundo). El método get_variation() le permite controlar si se realiza el seguimiento. Si track=False, el SDK no enviará eventos de exposición. Esto es útil si prefiere no rastrear datos a través del SDK y en su lugar confiar en el seguimiento del lado del cliente gestionado por el motor Kameleoon, por ejemplo. Además, establecer track=False es útil cuando se utiliza el método get_variations(), donde solo puede necesitar las variaciones para todos los flags sin desencadenar ningún evento de seguimiento. Si desea saber más sobre cómo funciona el seguimiento, consulte este artículo

Adición de puntos de datos para segmentar a un usuario o filtrar / desglosar visitas en informes

Para dirigirse a un usuario, asegúrese de haber añadido puntos de datos relevantes a su perfil antes de recuperar la variación de la característica o verificar si el flag está activo. Utilice el método add_data() para añadir estos puntos de datos al perfil del usuario. Para recuperar puntos de datos recopilados en otros dispositivos o para acceder a datos de usuario anteriores (recopilados del lado del cliente al utilizar Kameleoon en modo híbrido), utilice el método get_remote_visitor_data(). Este método obtiene datos de los servidores de forma asincrónica. Es importante llamar a get_remote_visitor_data() antes de recuperar la variación o verificar si el feature flag está activo, ya que estos datos podrían ser necesarios para asignar un usuario a una variación determinada. Para obtener más información sobre las condiciones de segmentación disponibles, consulte el artículo detallado sobre este tema. 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í. 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 de Kameleoon. Custom Data le permite capturar y analizar información específica relevante para sus experimentos. No olvide llamar al método 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.

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() 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). Si prefiere enviar la solicitud de inmediato, utilice el método flush() con el parámetro instant=True.

Envío de eventos a soluciones de analítica

Para rastrear conversiones y enviar eventos de exposición a su solución de analítica de clientes, primero debe implementar Kameleoon en modo híbrido. Luego, utilice el método get_engine_tracking_code(). 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().

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)

Esto solo se aplica al desarrollo local cuando utiliza python manage.py runserver. En un entorno de producción, el código en la función ready() se ejecutará solo una vez cuando se inicialice la aplicación.

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.

Otra ventaja de utilizar Django es que el SDK leerá y escribirá automáticamente el visitor_code en la solicitud/respuesta HTTP a través de una cookie. Si está utilizando otro framework en un entorno web donde desea utilizar un mecanismo de cookie para persistir el visitor_code, debe proporcionar implementaciones de los métodos read_cookies() y write_cookies().

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.

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 Si el mismo ID de usuario se utiliza de forma coherente en todos los dispositivos, la sincronización se gestiona automáticamente sin una sincronización de mapeo personalizada. Es suficiente llamar al método get_remote_visitor_data() cuando desee sincronizar los datos recopilados entre varios dispositivos. Instancias multi-servidor con IDs consistentes En configuraciones complejas con múltiples servidores (por ejemplo, instancias de servidor distribuidas), donde el mismo ID de usuario está disponible en todos los servidores, la sincronización entre servidores (con get_remote_visitor_data()) es suficiente sin sincronización de mapeo personalizada adicional. Los clientes que necesitan datos adicionales pueden consultar la descripción del método get_remote_visitor_data() para obtener más orientación. En el código siguiente, se asume que el mismo identificador único (en este caso, el visitor_code, que también puede denominarse userId) se utiliza de forma coherente entre los dos dispositivos para la recuperación precisa de datos.

Si desea sincronizar los datos recopilados en tiempo real, debe elegir el ámbito Visitor para sus datos personalizados.

Device A

# 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)

Device B

# 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 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 para proporcionar un identificador único del visitante. Para más información, consulte la documentación dedicada. Después de habilitar la reconciliación entre dispositivos, llamar a get_remote_visitor_data() con el parámetro userId recupera todos los datos conocidos de un usuario determinado. 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í. Siga la guía de activación de la reconciliación de historial 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() con UniqueIdentifier(True) añadido—para recuperar datos de todos los visitantes vinculados.
track_conversion() o flush() con datos UniqueIdentifier(True) añadidos—para rastrear algunos datos de un visitante específico que está asociado a otro visitante.

Como los datos personalizados que utiliza como identificador deben establecerse en Visitor scope, debe utilizar sincronización de datos personalizados entre dispositivos para recuperar el identificador con el método get_remote_visitor_data() en cada dispositivo.

A continuación se muestra un ejemplo de cómo usar datos personalizados para la fusión de sesiones.

# 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(). 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 utiliza un ID de visitante único y anónimo (visitor_code) para asignar usuarios a variaciones de feature flag. Este ID se genera y almacena típicamente en el dispositivo del usuario (en una cookie del navegador para SDKs del lado del cliente y del lado del servidor; en almacenamiento persistente para SDKs móviles). Sin embargo, en ciertos escenarios puede ser necesario garantizar que todos los usuarios de la misma organización vean la misma variante de un 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:

Experimentos de nivel de cuenta u organizacionales: Para productos B2B o escenarios donde desea asignar todos los usuarios de la misma organización a la misma variación, puede utilizar un identificador como account_id. Las claves de bucketing personalizadas son cruciales para probar funciones que impactan a un equipo o empresa completa.

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:

from kameleoon.data import CustomData

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

Proporcionar la clave personalizada: Proporciona su identificador personalizado al SDK de Kameleoon utilizando el método add_data(). En este método, pasará su clave de bucketing personalizada elegida como un objeto CustomData. Aquí, new_visitor_code se refiere al identificador que desea utilizar para su bucketing (por ejemplo, el nuevo user_id o 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.

Lógica de bucketing: Una vez que se proporciona una clave de bucketing personalizada a través del método add_data(), todos los cálculos hash para asignar usuarios a variaciones utilizarán este new_visitor_code (su clave personalizada) en lugar del visitor_code predeterminado. Utilizar new_visitor_code significa que la decisión de bucketing está vinculada a su identificador personalizado, garantizando asignaciones coherentes en varios contextos donde ese identificador está presente.
Seguimiento de datos y analítica: Es crucial tener en cuenta que aunque el new_visitor_code (su clave personalizada) se utiliza para decisiones de bucketing, todos los datos posteriores (eventos de seguimiento y conversiones, por ejemplo) se envían y asocian con el visitor_code original. Esta separación garantiza que su analítica refleje con precisión los viajes de usuario individuales e interacciones dentro del contexto más amplio de su experimento, incluso cuando el bucketing se realiza a un nivel superior (como una cuenta) o entre múltiples dispositivos/sesiones. Sus datos de visitante originales permanecen intactos para informes completos.

Requisitos técnicos

Para utilizar eficazmente una clave de bucketing personalizada:

La clave debe ser un str.
Debe ser única para la entidad que desea agrupar (por ejemplo, si utiliza un user_id, el ID de cada usuario debe ser único).
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. También puede utilizar sus propios datos externos para segmentar a los usuarios.

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.

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.

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

Esta es una documentación de referencia completa del SDK de Python.

create()

Para empezar a utilizar el SDK, debe completar la inicialización. Todas las interacciones con el SDK se realizan a través de un objeto llamado Kameleoon::KameleoonClient, por lo que lo primero que debe hacer es crear este objeto.

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 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	Excepción que indica que el código de sitio especificado es una cadena vacía, que es un valor inválido.
ConfigFileNotFound	Excepción que indica que no se encontró el archivo de configuración.

wait_init_async()

Utilice wait_init_async() cuando su aplicación deba esperar de forma asincrónica a que el cliente de Kameleoon termine su inicialización antes de evaluar feature flags. La llamada devuelve el resultado de la recuperación de la configuración: True cuando el cliente termina su inicialización, y False si la recuperación inicial de la configuración falla antes de que el cliente esté listo. Los reintentos en segundo plano continúan después de ese primer fallo. Una vez que un reintento se realiza correctamente, las llamadas posteriores devuelven True. Si no hay ningún resultado de inicialización disponible antes de que expire el tiempo de espera, la llamada devuelve False. Si no proporciona un valor de timeout_milliseconds, el SDK utiliza el tiempo de espera predeterminado de default_timeout_millisecond. El fallo que impidió que el SDK se inicializase se comunica al registro.

# Waits up to the default timeout of the client configuration
if await kameleoon_client.wait_init_async():
    # The SDK has been initialized

# Waits no longer than the specified timeout
if await kameleoon_client.wait_init_async(1000):
    # The SDK has been initialized

Parámetros

Nombre	Tipo	Descripción	Valor predeterminado
`timeout_milliseconds` opcional	`Optional[int]`	El tiempo máximo de espera para un resultado de inicialización, en milisegundos.	`default_timeout_millisecond`

Valor de retorno

Tipo	Descripción
`bool`	`True` si el SDK está listo, o `False` si la recuperación inicial de la configuración falló o el tiempo de espera expiró primero.

wait_init()

Utilice wait_init() cuando su aplicación deba esperar a que el cliente de Kameleoon termine su inicialización antes de evaluar feature flags. La llamada devuelve el resultado de la recuperación de la configuración: True cuando el cliente termina su inicialización, y False si la recuperación inicial de la configuración falla antes de que el cliente esté listo. Los reintentos en segundo plano continúan después de ese primer fallo. Una vez que un reintento se realiza correctamente, las llamadas posteriores devuelven True. Si no hay ningún resultado de inicialización disponible antes de que expire el tiempo de espera, la llamada devuelve False. Si no proporciona un valor de timeout_milliseconds, el SDK utiliza el tiempo de espera predeterminado de default_timeout_millisecond. El fallo que impidió que el SDK se inicializase se comunica al registro.

Llame a wait_init() una vez al iniciar la aplicación para esperar hasta que el SDK haya cargado su configuración o expire el tiempo de espera. En cada solicitud entrante, utilice is_ready() como una protección no bloqueante antes de evaluar feature flags. Incluso si wait_init() falla, el SDK sigue reintentando la recuperación de la configuración en segundo plano, por lo que is_ready() comienza a devolver True después de que un reintento se realiza correctamente.

# Waits up to the default timeout of the client configuration
if kameleoon_client.wait_init():
    # The SDK has been initialized

# Waits no longer than the specified timeout
if kameleoon_client.wait_init(1000):
    # The SDK has been initialized

Parámetros

Nombre	Tipo	Descripción	Valor predeterminado
`timeout_milliseconds` opcional	`Optional[int]`	El tiempo máximo de espera para un resultado de inicialización, en milisegundos.	`default_timeout_millisecond`

Valor de retorno

Tipo	Descripción
`bool`	`True` si el SDK está listo, o `False` si la recuperación inicial de la configuración falló o el tiempo de espera expiró primero.

is_ready()

is_ready() comprueba si el SDK está listo para usar, lo que significa que su configuración se ha cargado correctamente. A diferencia de wait_init(), este método devuelve el resultado inmediatamente sin bloquear ni lanzar excepciones.

Una vez que el SDK esté listo, permanece listo. Si una actualización posterior de la configuración falla, el SDK sigue utilizando la configuración descargada previamente y no vuelve a un estado no listo.
Llame a wait_init() una vez al iniciar la aplicación para esperar hasta que el SDK haya cargado su configuración o expire el tiempo de espera. En cada solicitud entrante, utilice is_ready() como una protección no bloqueante antes de evaluar feature flags. Incluso si wait_init() falla, el SDK sigue reintentando la recuperación de la configuración en segundo plano, por lo que is_ready() comienza a devolver True después de que un reintento se realiza correctamente.

ready = kameleoon_client.is_ready()

Valor de retorno

Tipo	Descripción
`bool`	`True` si el SDK se ha inicializado correctamente; `False` en caso contrario (incluso mientras la inicialización sigue pendiente o ha fallado).

Feature flags y variaciones

is_feature_active()

📨 Envía datos de seguimiento a Kameleoon (dependiendo del parámetro track)

Anteriormente llamado activate_feature—obsoleto desde la versión 2.1.0 del SDK y se eliminará en futuras versiones.

Para verificar si un feature flag está activo para un visitante, llame al método is_feature_active(). Este método toma un visitor_code y feature_key como argumentos obligatorios para verificar si la función estará activa para un usuario determinado. Si tal usuario nunca ha sido asociado con este feature flag, el SDK devuelve un valor booleano al azar (true si la función estará activa para el usuario, o false si no). Si un usuario con un visitor_code determinado ya está registrado con este feature flag, detectará el valor anterior del feature flag. 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. 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.

El parámetro is_unique_identifier es obsoleto. Utilice UniqueIdentifier en su lugar.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 utiliza el seguimiento para contar sesiones y visitantes cuando llama a ciertos métodos, como is_feature_active(), get_variation() o 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, si llama a get_variations() para recuperar todas las variaciones antes de exponer a los visitantes, establezca el parámetro track en False. Esta configuración impide que Kameleoon cuente una sesión prematuramente. Luego puede desencadenar el seguimiento después cuando exponga explícitamente al visitante.Kameleoon envía datos de seguimiento cada segundo de forma predeterminada. Puede configurar este intervalo hasta cinco segundos utilizando la opción de configuración del intervalo de seguimiento. Kameleoon agrupa eventos de seguimiento en una sola sesión mientras el intervalo entre eventos sea inferior a 30 minutos. Si transcurren más de 30 minutos entre eventos de seguimiento, Kameleoon cuenta los eventos como sesiones separadas. Una visita aparece en sus informes 30 minutos después del último evento registrado en la sesión.

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

El método is_feature_active() evalúa la variación entregada, no el estado de la marca maestra del feature flag. Si excluye reglas, el método utiliza el estado predeterminado Then, for everyone else serve. Si selecciona Off para este estado predeterminado, el método siempre devuelve false incluso cuando el feature flag maestro es On.

Parámetros

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]	Cuando se establece en `True`, el SDK vincula los datos vaciados al visitante asociado al identificador especificado.
track	bool	Un parámetro opcional para habilitar o deshabilitar el seguimiento de la evaluación de la función (`True` de forma predeterminada).

Valor de retorno

Tipo	Descripción
bool	Valor de la función que está registrada para un visitor_code determinado.

Excepciones lanzadas

Tipo	Descripción
FeatureNotFound	Excepción que indica que el ID de función solicitado no se ha encontrado en la configuración interna del SDK. Esta excepción es normalmente normal e indica que el feature flag aún no se ha activado en el lado de Kameleoon (pero el código que implementa la función ya está implementado en el lado de la aplicación web).
VisitorCodeInvalid	Excepción que indica que el código de visitante proporcionado no es válido (vacío o más de 255 caracteres).

get_variation()

📨 Envía datos de seguimiento a Kameleoon (dependiendo del parámetro track)

Recupera la Variation asignada a un visitante dado para un feature flag específico. Este método toma un visitor_code y feature_key como argumentos obligatorios. El argumento track es opcional y su valor predeterminado es 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. En otras palabras, es la variación de reserva aplicada a todos los usuarios que no están dirigidos por reglas específicas. Se muestra como la variación en la sección “Then, for everyone else…” de una interfaz de gestión.

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

Parámetros

Nombre	Tipo	Descripción	Por defecto
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`	Una `Variation` asignada a un visitante dado para un feature flag específico.

Excepciones lanzadas

Tipo	Descripción
`VisitorCodeInvalid`	Excepción que indica que el visitor code proporcionado no es válido. Está vacío o es más largo de 255 caracteres.
`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 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. Toma visitor_code como argumento obligatorio, mientras que only_active y track son opcionales.

Si only_active se establece en True, el método get_variations() devolverá variaciones de feature flags siempre que el usuario no esté agrupado con la variación off.
El parámetro track controla si el método realizará seguimiento de las asignaciones de variación. De forma predeterminada, se establece en True. Si se establece en False, el seguimiento se deshabilitará.

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.

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

Parámetros

Nombre	Tipo	Descripción	Por defecto
visitor_code (obligatorio)	`str`	Identificador único del visitante.
only_active (opcional)	`bool`	Un parámetro opcional que indica si se devuelven variaciones para feature flags activos (`True`) o todos (`False`).	`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` 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. Está vacío o es más largo de 255 caracteres.

get_data_file()

Para evaluar todos los feature flags, utilice get_variations(). Este método es más eficiente que llamar a DataFile e iterar a través de flags con get_variation().

Devuelve la configuración actual del SDK como un objeto DataFile.

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

Valor de retorno

Tipo	Descripción
`DataFile`	El `DataFile` que contiene la configuración del SDK

set_forced_variation()

El método le permite asignar mediante programación una Variation específica a un usuario, omitiendo el proceso de evaluación estándar. Esto es especialmente valioso para experimentos controlados donde la lógica de evaluación habitual no es necesaria o debe omitirse. También puede ser útil en escenarios como depuración o pruebas personalizadas. Cuando se establece una variación forzada, anula la lógica de evaluación en tiempo real de Kameleoon. Se omiten procesos como segmentación, condiciones de targeting y cálculos algorítmicos. Para preservar la segmentación y las condiciones de targeting durante un experimento, establezca force_targeting=False en su lugar.

Las variaciones simuladas siempre tienen prioridad en el orden de ejecución. Si se activa un cálculo de variación simulada, se procesará y completará completamente primero.

Una variación forzada se trata igual que una variación evaluada. Se rastrea en analítica y se almacena en el contexto del usuario como cualquier variación evaluada estándar, asegurando consistencia en los informes. El método puede lanzar excepciones bajo ciertas condiciones (por ejemplo, parámetros no válidos, contexto del usuario o problemas internos). El manejo adecuado de excepciones es esencial para garantizar que su aplicación permanezca estable y resiliente.

Es importante distinguir las variaciones forzadas de las variaciones simuladas:

Variaciones forzadas: Son específicas de un experimento individual.
Variaciones simuladas: Afectan el resultado general del feature flag.

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

Parámetros

Nombre	Tipo	Descripción	Por defecto
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. Si el valor es `None`, la variación forzada será reiniciada.
force_targeting (opcional)	`bool`	Indica si el targeting del experimento debe forzarse y omitirse (`True`) o aplicarse como en el proceso de evaluación estándar (`False`).	`True`

Excepciones lanzadas

Tipo	Descripción
`VisitorCodeInvalid`	Excepción que indica que el visitor code proporcionado no es válido. Está vacío o es más largo que 255 caracteres.
`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.

En la mayoría de los casos, solo el error básico, KameleoonError, necesita manejarse, como se demuestra en el ejemplo. Sin embargo, si diferentes tipos de errores requieren una respuesta, maneje cada uno por separado en función de requisitos específicos. Además, para una fiabilidad mejorada, los errores generales del lenguaje pueden manejarse incluyendo 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() debe llamarse después de que todos los datos relevantes del visitante se hayan establecido o actualizado, y justo antes de obtener una variación de feature o de verificar un 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. Después de llamar a este método, puede realizar un análisis detallado del rendimiento de segmentos en Audiences Explorer.

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

Parámetros

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. Está vacío o es más largo que 255 caracteres.

Datos del visitante

get_visitor_code()

Este método se llamaba anteriormente obtain_visitor_code, que fue eliminado en la versión 3.0.0 del SDK.

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:

El SDK primero comprueba si se puede encontrar una cookie kameleoonVisitorCode o un parámetro de consulta asociado con la solicitud HTTP actual. Si es así, la utiliza como identificador del visitante.
Si no se encuentra una cookie o parámetro en la solicitud actual, el SDK genera aleatoriamente un nuevo identificador o utiliza el argumento default_visitor_code como identificador si se proporciona. Esto le permite usar sus propios identificadores como códigos de visitante, si lo desea, lo que tiene el beneficio adicional de hacer coincidir los visitantes de Kameleoon con sus propios usuarios sin búsquedas adicionales en una tabla de coincidencias.
En cualquier caso, la cookie kameleoonVisitorCode del lado del servidor (a través del encabezado HTTP) se establece con el valor. A continuación, este valor de identificador se devuelve finalmente por el método.

Si proporciona su propio visitor_code, debe garantizar su singularidad. El SDK no valida el valor pasado como argumento. Tenga en cuenta que la longitud de visitor_code se limita a 255 caracteres. Se genera una excepción VisitorCodeInvalid si se supera este límite.

El método get_visitor_code() le permite establecer variaciones simuladas para un visitante. 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 basada en los datos proporcionados.Puede aplicar simulaciones de dos formas:

Automáticamente (recomendado): Si utiliza Kameleoon Web Experimentation o el SDK en modo híbrido, la cookie se crea automáticamente al simular la visualización de una variante utilizando el Panel de simulación.
Manualmente: Establezca la cookie kameleoonSimulationFFData manualmente.

Es importante distinguir las variaciones simuladas de las variaciones forzadas:

Variaciones simuladas: Afectan el resultado general del feature flag.
Variaciones forzadas: Son específicas de un experimento individual.

⚙️ Manual setupAsegú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 Luego, para todos los demás en Producción, servir) para el featureKey indicado.

⚠️ Para garantizar que el valor de la cookie funcione correctamente, codifíquelo como componente URI utilizando un método como encodeURIComponent.

### 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()

Parámetros

Nombre	Tipo	Descripción
cookies_readonly	Optional[Dict[str, str]]	Diccionario de solo lectura, generalmente `request.COOKIES`. Utilice este parámetro si también utiliza el servicio `KameleoonWSGIMiddleware`. Este campo es opcional.
cookies	Optinal[Dict[str, http.cookies.Morsel[str]]]	Pase las cookies de la solicitud HTTP actual como un objeto `Dict[str, http.cookies.Morsel[str]]` o `http.cookies.\|SimpleCookie[str]` si administra cookies manualmente sin el servicio `KameleoonWSGIMiddleware`. Este campo es opcional.
default_visitor_code	str	Este parámetro se usará como el visitor_code si no existe una cookie kameleoonVisitorCode en la solicitud. Este campo es opcional y, de forma predeterminada, se generará un visitor_code aleatorio.

Valor de retorno

Tipo	Descripción
str	Un visitor_code que será asociado con este usuario particular y debe usarse con la mayoría de los métodos del SDK.

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.

add_data()

El método add_data() añade datos de segmentación 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(). 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() también envía cualquier dato previamente asociado, al igual que flush(). Lo mismo aplica para los métodos get_variation() y 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. Sin embargo, CustomData es una excepción. Los visitantes pueden tener una instancia de CustomData asociada por índice.

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
)

Parámetros

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. Cuando se establece en `False`, los datos se almacenan localmente y se utilizan solo para la evaluación de targeting; no se envían a la API de datos de Kameleoon.	`True`

Excepciones

Tipo	Descripción
`VisitorCodeInvalid`	Excepción que indica que el visitor code proporcionado no es válido. Está vacío o es más largo que 255 caracteres.

flush()

📨 Envía datos de seguimiento a Kameleoon

flush() toma los datos de Kameleoon asociados con el visitante y todos los datos que se añadieron anteriormente usando el método add_data, que no han sido enviados aún al llamar a uno de estos métodos, y envía una solicitud de seguimiento. flush() es sin bloqueo, ya que la llamada al servidor se realiza de forma asincrónica. flush() le permite controlar cuándo se envían los datos asociados con un visitor_code determinado a nuestros servidores. Por ejemplo, si llama a add_data() una docena de veces, sería ineficiente enviar datos al servidor cada vez que se invoca add_data(), por lo que solo tiene que llamar a flush() una vez al final. 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. 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.

El parámetro is_unique_identifier está en desuso. Utilice UniqueIdentifier en su lugar.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_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]	Cuando es `True`, el SDK vincula los datos vaciados con el visitante asociado al identificador especificado.
instant	bool	Indicador booleano que indica si los datos deben enviarse instantáneamente (`True`) o de acuerdo con el intervalo de seguimiento programado (`False`). Si no se proporciona, el valor predeterminado es `False`. Este campo es opcional.

get_remote_data()

Se llamaba anteriormente retrieve_data_from_remote_source, que fue eliminado en la versión 3.0.0 del SDK.
Si desea recuperar datos de forma asincrónica, utilice el método get_remote_data_async en su lugar (disponible desde la versión 2.3.0).

El método get_remote_data recupera datos de forma sincrónica (según una key pasada como argumento) para un site_code especificado (especificado con KameleoonClient.__init__) almacenado en un servidor remoto de Kameleoon. Los datos generalmente se almacenan en servidores remotos a través de la API de datos. Este método, junto con la disponibilidad de servidores altamente escalables para este propósito, proporciona un método conveniente para almacenar cantidades masivas de datos que se pueden recuperar para cada uno de sus visitantes/usuarios.

    kameleoon_client.get_remote_data('key1') # default timeout

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

Parámetros

Nombre	Tipo	Descripción
key	str	La clave con la que se asocian los datos. Este campo es obligatorio.
timeout	Optional[float]	Tiempo de espera (en segundos). Este parámetro especifica la cantidad máxima de tiempo que el método puede bloquearse esperando un resultado. Este campo es opcional; si no se proporciona, utilizará el valor `default_timeout_millisecond` del archivo de configuración, o 2 segundos si no se especifica en el archivo.

Valor de retorno

Tipo	Descripción
JSON object	Objeto JSON asociado con la recuperación de datos para una key específica.

get_remote_data_async()

El método get_remote_data_async le permite recuperar datos de forma asincrónica (según una key pasada como argumento) para un site_code especificado (especificado con KameleoonClient.__init__) almacenado en un servidor remoto de Kameleoon. Los datos generalmente se almacenan en servidores remotos a través de la API de datos. Este método, junto con la disponibilidad de servidores altamente escalables para este propósito, proporciona un método conveniente para almacenar cantidades masivas de datos que se pueden recuperar para cada uno de sus visitantes/usuarios.

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

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

Parámetros

Nombre	Tipo	Descripción
key	str	La clave con la que se asocian los datos. Este campo es obligatorio.
timeout	Optional[float]	Tiempo de espera (en segundos). Este parámetro especifica la cantidad máxima de tiempo que el método puede bloquearse esperando un resultado. Este campo es opcional; si no se proporciona, utilizará el valor `default_timeout_millisecond` del archivo de configuración, o 2 segundos si no se especifica en el archivo.

Valor de retorno

Tipo	Descripción
JSON object	Objeto JSON asociado con la recuperación de datos para una key específica.

get_remote_visitor_data()

get_remote_visitor_data() es un método asincrónico para recuperar datos de visitas de Kameleoon para el visitor_code desde la API de datos de Kameleoon. El método añade los datos al almacenamiento para que otros métodos los utilicen al tomar decisiones de targeting. Los datos obtenidos mediante este método desempeñan un papel importante cuando desea:

usar datos recopilados de otros dispositivos.
acceder al historial de un usuario, como las páginas visitadas durante visitas anteriores.
usar datos que solo son accesibles en el lado del cliente, como variables de datalayer y objetivos que solo se convierten en el front-end.

Lee este artículo para una mejor comprensión de los posibles casos de uso.

Por defecto, get_remote_visitor_data() recupera automáticamente los últimos datos personalizados almacenados con scope=visitor y los adjunta al visitante sin necesidad de llamar al método add_data(). Es particularmente útil para sincronizar datos personalizados entre múltiples dispositivos.

    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)

Parámetros

Nombre	Tipo	Descripción
visitor_code	str	El código de visitante para el cual desea recuperar los datos asignados. 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. Si no se especifica, el valor predeterminado es True. Este campo es opcional.
data_filter	RemoteVisitorDataFilter	Filtro que especifica qué datos deben recuperarse de las visitas. Por defecto, solo se recupera `CustomData` de la visita actual y la visita anterior más reciente (`RemoteVisitorDataFilter(previousVisitAmount=1, currentVisit=True, customData=True)` o `RemoteVisitorDataFilter()`). Otros parámetros de filtros se establecen en `False`. Este campo es opcional.
is_unique_identifier (Obsoleto)	Optional[bool]	Parámetro opcional para indicar si el `visitorCode` es un identificador único. Si no se proporciona, el valor predeterminado es `False`. Este campo es opcional.
timeout	Optional[float]	Tiempo de espera (en segundos). Este parámetro especifica la cantidad máxima de tiempo que el método puede bloquearse esperando un resultado. Este campo es opcional; si no se proporciona, utilizará el valor `default_timeout_millisecond` del archivo de configuración, o 2 segundos si no se especifica en el archivo.

Uso de parámetros en 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, supongamos que desea recuperar datos sobre visitantes que completaron el objetivo “Order transaction”. Puede especificar parámetros dentro del método get_remote_visitor_data() para refinar su targeting. Por ejemplo, si desea dirigirse solo a usuarios que se convirtieron en el objetivo en sus últimas cinco visitas, puede establecer el parámetro previous_visit_amount a 5 y conversions a 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]	Una lista de datos asignados al visitante dado.

Aquí se encuentra la lista de opciones Kameleoon::Configuration::RemoteVisitorDataFilter disponibles:

Nombre	Tipo	Descripción	Por defecto
previous_visit_amount opcional	`int`	Número de visitas previas de las que recuperar datos. Número entre `1` y `25`	`1`
current_visit opcional	`bool`	Si es True, se recuperarán los datos de la visita actual	`True`
custom_data opcional	`bool`	Si es True, se recuperarán los datos personalizados.	`True`
page_views opcional	`bool`	Si es True, se recuperarán los datos de página.	`False`
geolocation opcional	`bool`	Si es True, se recuperarán los datos de geolocalización.	`False`
device opcional	`bool`	Si es True, se recuperarán los datos del dispositivo.	`False`
browser opcional	`bool`	Si es True, se recuperarán los datos del navegador.	`False`
operating_system opcional	`bool`	Si es True, se recuperarán los datos del sistema operativo.	`False`
conversions opcional	`bool`	Si es True, se recuperarán los datos de conversión.	`False`
experiments opcional	`bool`	Si es True, se recuperarán los datos del experimento.	`False`
kcs opcional	`bool`	Si es true, se recuperará la puntuación de conversión de Kameleoon (KCS). Requiere el Contextual Bandit & AI Targeting Premium add-on	`False`
visitor_code opcional	`bool`	Si es true, Kameleoon recuperará el `visitorCode` de la visita más reciente y lo utilizará para la visita actual. Esto es necesario si desea asegurar que el visitante, identificado por su `visitorCode`, siempre reciba la misma variación en las visitas para experimentación entre dispositivos.	`True`
cbs opcional	`bool`	Si es true, se recuperarán los datos de puntuación del Contextual Bandit.	`False`
personalization opcional	`bool`	Si es True, se recuperarán los datos de personalización. Esto es necesario para la condición de personalización.	`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

Usar el método get_remote_visitor_data junto con la disponibilidad de servidores altamente escalables proporciona un método conveniente para acceder y sincronizar grandes cantidades de datos en todos los dispositivos del visitante. Si especifica un visitor_code, el método get_remote_visitor_data_async utiliza el visitor_code como identificador único del visitante, lo cual es útil para experimentos entre dispositivos. Cuando especifica un visitor_code y establece el parámetro is_unique_identifier en true, el SDK vincula los datos vaciados al visitante asociado con el identificador especificado.

El parámetro is_unique_identifier está obsoleto. Use UniqueIdentifier en su lugar.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.

    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)

Parámetros

Nombre	Tipo	Descripción
visitor_code	str	El código del visitante para el cual desea recuperar los datos asignados. 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. Si no se especifica, el valor predeterminado es True. Este campo es opcional.
data_filter	RemoteVisitorDataFilter	Filtro que especifica qué datos deben recuperarse de las visitas. De forma predeterminada, solo se recuperan los `CustomData` de la visita actual y la visita anterior más reciente (`RemoteVisitorDataFilter(previousVisitAmount=1, currentVisit=True, customData=True)` o `RemoteVisitorDataFilter()`). Los otros parámetros de filtro se establecen en `False`. Este campo es opcional.
is_unique_identifier (Obsoleto)	Optional[bool]	Parámetro opcional para indicar si el `visitorCode` es un identificador único. Si no se proporciona, el valor predeterminado es `False`. Este campo es opcional.
timeout	Optional[float]	Tiempo de espera (en segundos). Este parámetro especifica la cantidad máxima de tiempo que el método puede bloquear para esperar un resultado. Este campo es opcional; si no se proporciona, utilizará el valor `default_timeout_millisecond` del archivo de configuración, o 2 segundos si no se especifica en el archivo.

Valor de retorno

Tipo	Descripción
List[Data]	Una lista de datos asignados al visitante.

Uso de parámetros en 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, suponga que desea recuperar datos sobre visitantes que completaron el objetivo “Transacción de pedido”. Puede especificar parámetros dentro del método get_remote_visitor_data_async() para refinar su orientación. Por ejemplo, si desea orientarse únicamente a usuarios que realizaron una conversión en el objetivo en sus últimas cinco visitas, puede establecer el parámetro previous_visit_amount en 5 y conversions en 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.

Aquí se encuentra la lista de opciones Kameleoon::Configuration::RemoteVisitorDataFilter disponibles:

Nombre	Tipo	Descripción	Por defecto
previous_visit_amount opcional	`int`	Número de visitas anteriores de las que recuperar datos. Número entre `1` y `25`	`1`
current_visit opcional	`bool`	Si es True, se recuperarán los datos de la visita actual	`True`
custom_data opcional	`bool`	Si es True, se recuperarán los datos personalizados.	`True`
page_views opcional	`bool`	Si es True, se recuperarán los datos de página.	`False`
geolocation opcional	`bool`	Si es True, se recuperarán los datos de geolocalización.	`False`
device opcional	`bool`	Si es True, se recuperarán los datos del dispositivo.	`False`
browser opcional	`bool`	Si es True, se recuperarán los datos del navegador.	`False`
operating_system opcional	`bool`	Si es True, se recuperarán los datos del sistema operativo.	`False`
conversions opcional	`bool`	Si es True, se recuperarán los datos de conversión.	`False`
experiments opcional	`bool`	Si es True, se recuperarán los datos del experimento.	`False`
kcs opcional	`bool`	Si es true, se recuperará la Puntuación de Conversión de Kameleoon (KCS). Requiere el Contextual Bandit & AI Targeting Premium add-on	`False`
visitor_code opcional	`bool`	Si es true, Kameleoon recuperará el `visitorCode` de la visita más reciente y lo utilizará para la visita actual. Esto es necesario si desea asegurar que el visitante, identificado por su `visitorCode`, siempre reciba la misma variación en las visitas para experimentos entre dispositivos.	`True`
cbs opcional	`bool`	Si es true, se recuperarán los datos de puntuación de Contextual Bandit.	`False`

get_visitor_warehouse_audience()

Recupera de forma sincrónica todos los datos de audiencia asociados con el visitante en su almacén de datos mediante el visitor_code y warehouse_key especificados. El warehouse_key es típicamente su ID de usuario interno. El parámetro custom_data_index corresponde a los datos personalizados de Kameleoon que Kameleoon usa para dirigirse a sus visitantes. Puede consultar la documentación de orientación de almacenes para más detalles. El método devuelve un objeto CustomData, confirmando que los datos se han agregado al visitante y están disponibles para propósitos de targeting.

Si desea recuperar los datos de forma asincrónica, use el método get_visitor_warehouse_audience_async en su lugar.

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

Parámetros

Nombre	Tipo	Descripción
visitor_code	str	Cadena única de identificación del visitante, no puede superar los 255 caracteres. 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]	Una clave única que identifica los datos del almacén de datos (generalmente su ID de usuario interno). Este campo es opcional.
timeout	Optional[float]	Tiempo de espera (en segundos). Este parámetro especifica la cantidad máxima de tiempo para esperar un resultado. Este campo es opcional. Si no se proporciona, el valor predeterminado es 10 segundos.

Valor de retorno

Tipo	Descripción
Optional[CustomData]	Una instancia `CustomData` que confirma que los datos se han añadido al visitante.

Excepciones lanzadas

Tipo	Descripción
VisitorCodeInvalid	Excepción que indica que el código de visitante proporcionado no es válido. Está vacío o tiene más de 255 caracteres.

get_visitor_warehouse_audience_async()

Recupera de forma asincrónica todos los datos de audiencia asociados con el visitante en su almacén de datos mediante el visitor_code y warehouse_key especificados. El warehouse_key es típicamente su ID de usuario interno. El parámetro custom_data_index corresponde a los datos personalizados de Kameleoon que Kameleoon usa para dirigirse a sus visitantes. Puede consultar la documentación de orientación de almacenes para más detalles. El método devuelve un objeto CustomData, confirmando que los datos se han agregado al visitante y están disponibles para propósitos de targeting.

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

Parámetros

Nombre	Tipo	Descripción
visitor_code	str	Cadena única de identificación del visitante, no puede superar los 255 caracteres. 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]	Una clave única que identifica los datos del almacén de datos (generalmente su ID de usuario interno). Este campo es opcional.
timeout	Optional[float]	Tiempo de espera (en segundos). Este parámetro especifica la cantidad máxima de tiempo para esperar un resultado. Este campo es opcional. Si no se proporciona, el valor predeterminado es 10 segundos.

Valor de retorno

Tipo	Descripción
Optional[CustomData]	Una instancia `CustomData` que confirma que los datos se han añadido al visitante.

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()

Debe usar este método para especificar si el visitante ha otorgado consentimiento legal para usar datos personales. Establecer el parámetro consent en False limita los tipos de datos que puede incluir en las solicitudes de seguimiento. Este método lo ayuda a cumplir con los requisitos legales y regulatorios mientras administra responsablemente los datos del visitante. Puede encontrar más información sobre datos personales en la política de gestión de consentimiento.

### 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.

Parámetros

Nombre	Tipo	Descripción
visitor_code	str	Identificador único del usuario. Este campo es obligatorio.
consent	bool	Un valor booleano que representa el estado del consentimiento legal. `true` indica que el visitante ha otorgado consentimiento legal, `false` indica que el visitante nunca ha proporcionado o ha retirado el consentimiento legal. Este campo es obligatorio.
cookies	Optional[Dict[str, http.cookies.Morsel[str]]]	Las cookies a ajustar en función del estado del consentimiento legal como objeto `Dict[str, http.cookies.Morsel[str]]` o `http.cookies.SimpleCookie[str]`. 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. 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.

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	Cuando es `True`, el SDK vincula los datos vaciados al visitante asociado con el identificador especificado.

Objetivos y analítica de terceros

get_engine_tracking_code()

Kameleoon se integra con varias soluciones de análisis, incluyendo Mixpanel, Google Analytics 4 y Segment. Para rastrear correctamente los experimentos del lado del servidor, llame al método get_engine_tracking_code() después de que el visitante active un experimento. El SDK devuelve comandos de cola de JavaScript para los experimentos que el visitante activó durante los últimos cinco segundos. Cuando inserta este código en la página, Engine.js procesa los comandos y envía los eventos de exposición a través de la integración de análisis activa. Consulte experimentación híbrida para más información sobre cómo implementar este método.

engine_tracking_code = kameleoon_client.get_engine_tracking_code(visitor_code)

Para usar esta función, implemente tanto el SDK de Python como el Engine.js de Kameleoon. Debido a que Engine.js se usa solo para rastrear en este flujo, puede instalar la etiqueta asincrónica antes de la etiqueta de cierre </body>.
Si solo desea rastrear experimentos en Kameleoon y no necesita enviar eventos de exposición a herramientas de análisis de terceros, use el SDK de JavaScript / TypeScript. Esta opción funciona bien para plataformas de computación de borde sin servidor. El SDK de JavaScript / TypeScript rastrea automáticamente las variaciones cuando llama a getVisitorCode, siempre y cuando agregue las asignaciones de experimento correspondientes a window.kameleoonQueue.
Puede insertar el código de rastreo devuelto directamente en una etiqueta HTML <script>.

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

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

  </body>
</html>

En este ejemplo, 123456 y 234567 son IDs de experimento, y 7890 y 8901 son IDs de variación. En su implementación, el SDK genera estos valores en el código de seguimiento devuelto.

Parámetros

Nombre	Tipo	Descripción
visitor_code (obligatorio)	`str`	Identificador único del visitante.

Valor de retorno

Tipo	Descripción
`str`	Código JavaScript para insertar en la página.

track_conversion()

📨 Envía datos de seguimiento a Kameleoon

Utilice este método para registrar una conversión para un objetivo específico y usuario. Este método requiere visitor_code y goal_id. Además, este método también acepta argumentos opcionales revenue, negative y metadata. El visitor_code suele ser idéntico al que se usó al desencadenar el experimento. El método track_conversion() no devuelve ningún valor. Este método no es bloqueante, ya que la llamada al servidor se realiza de forma asíncrona.

visitor_code = "visitorCode"
goal_id = 83023

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

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

Parámetros

Nombre	Tipo	Descripción	Por defecto
visitor_code (obligatorio)	`str`	Identificador único del visitante.
goal_id (obligatorio)	`int`	ID del objetivo.
revenue (opcional)	`float`	Ingreso de la conversión.	`0`
negative (opcional)	`bool`	Define si el ingreso es positivo o negativo.	`False`
metadata (opcional)	`Optional[Iterable[CustomData]]`	Le permite establecer valores específicos para los datos personalizados que se hayan definido como metadatos del objetivo en la aplicación de Kameleoon. Ejemplo: `[CustomData{id: 5, value: "Payment Type"}, CustomData{id: 6, value: "Delivery Method"}]`. En este ejemplo, `5` y `9` son los índices de los datos personalizados (5 = “Payment Type”, 9 = “Delivery Method”).	`None`
is_unique_identifier (obsoleto)	`bool`	Un parámetro opcional para especificar si visitor_code es un identificador único.	`False`

Los valores de metadata son accesibles a través de exportaciones de datos sin procesar y la página de resultados.Si se proporciona el parámetro metadata, Kameleoon usará estos valores especificados para la conversión actual en lugar de lo recopilado anteriormente usando el método add_data(). Si se omite el parámetro, Kameleoon usará los últimos valores rastreados para esos CustomData anteriores a la conversión y dentro de la misma visita.Kameleoon solo considerará los valores de metadata que se pasen explícitamente como parámetros al método track_conversion().En el siguiente ejemplo, Kameleoon asociará la conversión solo con el valor de datos personalizados proporcionado explícitamente como parámetro (aquí: índice 5 con el valor “Amex Credit Card”).

kameleoon_client.add_data(visitor_code, CustomData(5, "Credit Card"), CustomData(9, "Express Delivery"))
kameleoon_client.track_conversion(visitor_code, 10, metadata=[CustomData(5, "Amex Credit Card")])

Excepciones

Tipo	Descripción
`VisitorCodeInvalid`	Excepción que indica que el código de visitante proporcionado no es válido. Está vacío o tiene más de 255 caracteres.

Eventos

set_event_handler()

Utilice este método para registrar un handler para eventos del SDK. El SDK llama al handler cuando se produce el evento seleccionado. Registrar un nuevo handler para el mismo tipo de evento reemplaza al handler anterior. Pasar None como handler elimina el handler actual para el tipo de evento seleccionado.

DATAFILE_UPDATE
HTTP_REQUEST

from kameleoon.events import DataFileUpdateEvent, EventType


class DataFileUpdateHandler:
    def on_update(self, update_event: DataFileUpdateEvent) -> None:
        source = update_event.source  # POLLING or STREAMING
        date_modified = update_event.date_modified  # Data file modification date in milliseconds.

        # React to the data file update.


kameleoon_client.set_event_handler(EventType.DATAFILE_UPDATE, DataFileUpdateHandler())

# Clear the handler.
kameleoon_client.set_event_handler(EventType.DATAFILE_UPDATE, None)

DataFileUpdateEvent contiene información sobre una actualización del archivo de datos del SDK.

Nombre	Tipo	Descripción
`source`	`DataFileUpdateEvent.Source`	La fuente de la actualización. `POLLING` indica una actualización programada del archivo de datos, y `STREAMING` indica una actualización en tiempo real recibida mediante el modo streaming.
`date_modified`	`int`	La fecha de modificación del archivo de datos actualizado, en milisegundos.

from kameleoon.events import EventType, HttpRequestFailure, RequestType


class HttpRequestHandler:
    def on_request_succeeded(self, request_type: RequestType, http_status: int, duration_millis: int) -> None:
        # The SDK request completed successfully.
        ...

    def on_request_failed(self, request_type: RequestType, failure: HttpRequestFailure, duration_millis: int) -> None:
        reason = failure.reason  # HTTP_STATUS, EXCEPTION, or CANCELLED
        http_status = failure.http_status
        cause = failure.cause

        # The SDK request failed.


kameleoon_client.set_event_handler(EventType.HTTP_REQUEST, HttpRequestHandler())

# Clear the handler.
kameleoon_client.set_event_handler(EventType.HTTP_REQUEST, None)

HttpRequestHandler le permite reaccionar a las solicitudes HTTP del SDK completadas. El SDK llama a on_request_succeeded() para las respuestas exitosas y a on_request_failed() para las respuestas fallidas, excepciones o solicitudes canceladas.

Método	Descripción
`on_request_succeeded()`	Se llama cuando una solicitud HTTP del SDK se completa correctamente.
`on_request_failed()`	Se llama cuando una solicitud HTTP del SDK falla debido a un estado HTTP, una excepción o una cancelación.

Parámetros del callback y detalles del fallo

Parámetros del callback

Nombre	Tipo	Descripción
`request_type`	`RequestType`	El tipo de solicitud del SDK. Los valores posibles son `DATAFILE`, `TRACKING`, `REMOTE_VISITOR_DATA`, `REMOTE_DATA`, y `ACCESS_TOKEN`.
`http_status`	`int`	El código de estado HTTP devuelto por la solicitud. Solo se pasa a `on_request_succeeded()`.
`failure`	`HttpRequestFailure`	Detalles sobre por qué falló la solicitud. Solo se pasa a `on_request_failed()`.
`duration_millis`	`int`	La duración de la solicitud en milisegundos.

HttpRequestFailure

HttpRequestFailure contiene detalles sobre una solicitud HTTP del SDK fallida.

Nombre	Tipo	Descripción
`reason`	`HttpRequestFailure.Reason`	El motivo del fallo. Los valores posibles son `HTTP_STATUS`, `EXCEPTION`, y `CANCELLED`.
`http_status`	`Optional[int]`	El código de estado HTTP para los fallos causados por una respuesta HTTP no exitosa. Este valor es `None` para los fallos por excepción y cancelación.
`cause`	`Optional[Exception]`	La excepción (error) que provocó que la solicitud fallara. Este valor es `None` cuando la solicitud falló debido a un estado HTTP o a una cancelación.

Parámetros

Nombre	Tipo	Descripción
`event_type` obligatorio	`EventType[T]`	El tipo de evento del SDK que se gestionará. Utilice `EventType.DATAFILE_UPDATE` para reaccionar a las actualizaciones del archivo de datos del SDK, o `EventType.HTTP_REQUEST` para reaccionar a las solicitudes HTTP del SDK completadas.
`handler` obligatorio	`Optional[T]`	El handler que se registrará para el tipo de evento seleccionado. Utilice un `DataFileUpdateHandler` para `EventType.DATAFILE_UPDATE`, o un `HttpRequestHandler` para `EventType.HTTP_REQUEST`. Pase `None` para eliminar el handler actual.

Tipos de datos

Browser

El conjunto de datos Browser almacenado aquí puede utilizarse para filtrar los informes de experimentación y personalización por cualquier valor asociado a él.

Nombre	Tipo	Descripción
browser_type (obligatorio)	`BrowserType`	Lista de navegadores: `CHROME`, `INTERNET_EXPLORER`, `FIREFOX`, `SAFARI`, `OPERA`, `OTHER`.
version (opcional)	`Optional[float]`	Versión del navegador, número de punto flotante que representa la versión principal y secundaria del navegador

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

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

PageView

Nombre	Tipo	Descripción
url	str	URL de la página visitada. Este campo es obligatorio.
title	Optional[str]	Título de la página visitada. Este campo es opcional.
referrers	Optional[List[int]]	Referrers de las páginas vistas. Este campo es opcional.

El índice (ID) del referidor está disponible en la página de configuración del canal de Adquisición de nuestro Back-Office. Tenga cuidado: este índice comienza en 0, por lo que el primer canal de adquisición que cree para un sitio determinado tendrá el ID 0, no 1.

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

Conversion

El conjunto de datos Conversion almacenado aquí puede utilizarse para filtrar los informes de experimentación y personalización por cualquier objetivo asociado a él.

Cada visitante puede tener múltiples objetos Conversion.
Puede encontrar el goal_id en la aplicación de Kameleoon.

Nombre	Tipo	Descripción	Por defecto
goal_id (obligatorio)	`int`	ID del objetivo.
revenue (opcional)	`float`	Ingresos de la conversión. Este campo es opcional.	`0`
negative (opcional)	`bool`	Define si el ingreso es positivo o negativo.	`False`
metadata (opcional)	`Optional[Iterable[CustomData]]`	Metadatos de la conversión.	`None`

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

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

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

CustomData

CustomData permite asociar fácilmente cualquier tipo de datos con cada visitante. Luego se puede usar como condición de orientación en segmentos o como filtro/desglose en informes de experimentos. Para obtener más información sobre datos personalizados, consulte este artículo.

Nombre	Tipo	Descripción	Por defecto
index_or_name obligatorio	`Union[int, str]`	Índice o nombre del dato personalizado. Se debe proporcionar `index` o `name` para identificar los datos.
args obligatorio	`*str`	Valores de los datos personalizados a almacenar.
overwrite opcional	`bool`	Flag para controlar explícitamente cómo se almacenan los valores y cómo aparecen en los informes. Ver más	`True`

Cada visitante puede tener solo un CustomData para cada index único. Añadir otro CustomData con el mismo index reemplazará el CustomData existente.
El index de datos personalizados se puede encontrar en el panel de Control de Datos Personalizados bajo la columna “INDEX”.
Para impedir que el SDK envíe datos con el índice seleccionado a los servidores de Kameleoon por razones de privacidad, habilite la opción Use this data only locally for targeting purposes al crear datos personalizados.
Añadir una instancia CustomData creada con un nombre cuando la configuración de instancia del SDK no está actualizada o el nombre no está registrado resultará en que los datos se ignoren.

from kameleoon.data import CustomData

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

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

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

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

Device

Nombre	Tipo	Descripción
device	DeviceType	Lista de dispositivos: `PHONE`, `TABLET`, `DESKTOP`. Este campo es obligatorio.

from kameleoon import Device, DeviceType

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

UserAgent

Almacene información del agente de usuario del visitante. Los experimentos del lado del servidor son más vulnerables al tráfico de bots que los experimentos del lado del cliente. Para abordarlo, Kameleoon utiliza la lista de Spiders y Bots Internacionales de IAB/ABC para identificar bots y arañas conocidos. Kameleoon también utiliza el campo UserAgent para filtrar bots y otro tráfico no deseado que de otro modo podría sesgar sus métricas de conversión. Para obtener más detalles, consulte el artículo de ayuda sobre filtrado de bots. Si utiliza bots internos, le sugerimos pasar el valor curl/8.0 del userAgent para excluirlos de nuestra analítica.

Nombre	Tipo	Descripción
value	str	El valor del User-Agent que se enviará con las solicitudes de seguimiento. Este campo es obligatorio.

from kameleoon.data import UserAgent

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

UniqueIdentifier

Si no añade UniqueIdentifier para un visitante, se utiliza visitor_code como identificador único del visitante, lo cual es útil para la experimentación entre dispositivos. Cuando añade UniqueIdentifier para un visitante, el SDK vincula los datos vaciados con el visitante asociado al identificador especificado. UniqueIdentifier 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.

Nombre	Tipo	Descripción
value	bool	Parámetro para especificar si el visitor_code es un identificador único. Este campo es obligatorio.

from kameleoon.data import UniqueIdentifier

kameleoon_client.add_data(visitor_code, UniqueIdentifier(True))

OperatingSystem

OperatingSystem contiene información sobre el sistema operativo en el dispositivo del visitante.

Nombre	Tipo	Descripción
os_type	OperatingSystemType	List of types: WINDOWS, MAC, IOS, LINUX, ANDROID, WINDOWS_PHONE. Este campo es obligatorio.

Cada visitante puede tener solo un OperatingSystem. Añadir un segundo OperatingSystem sobrescribe el primero.

from kameleoon.data import OperatingSystem, OperatingSystemType

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

Cookie contiene información sobre las cookies almacenadas en el dispositivo del visitante.

Nombre	Tipo	Descripción
cookies	Dict[str, str]	Dict (`{cookie_name: cookie_value}`) que consiste en claves y valores de cookies. Este campo es obligatorio.

Cada visitante solo puede tener una Cookie. Agregar una segunda Cookie sobrescribe la primera.

from kameleoon.data import Cookie

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

Geolocation

Geolocation contiene los detalles de geolocalización del visitante.

Nombre	Tipo	Descripción
country (obligatorio)	`str`	El país del visitante.
region (opcional)	`Optional[str]`	La región del visitante.
city (opcional)	`Optional[str]`	La ciudad del visitante.
postal_code (opcional)	`Optional[str]`	El código postal del visitante.
latitude (opcional)	`Optional[float]`	La coordenada de latitud que representa la ubicación del visitante. El número de coordenada representa grados decimales.
longitude (opcional)	`Optional[float]`	La coordenada de longitud que representa la ubicación del visitante. El número de coordenada representa grados decimales.

Cada visitante solo puede tener una Geolocation. Agregar una segunda Geolocation sobrescribe la primera.

from kameleoon.data import Geolocation

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

ApplicationVersion

ApplicationVersion representa el número de versión semántica de su aplicación.

Un visitante solo puede tener una ApplicationVersion. Agregar una segunda instancia sobrescribirá la primera.

Nombre	Tipo	Descripción
version opcional	`str`	La versión de la aplicación móvil. Este campo debe seguir el versionado semántico. Los formatos aceptados son `major`, `major.minor` o `major.minor.patch`.

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

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

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

Tipos devueltos

DataFile

El DataFile contiene los detalles de configuración del SDK. Se puede extender con información adicional si los clientes lo requieren. Si necesita más detalles, comuníquese con su Gerente de Éxito del Cliente.

Nombre	Tipo	Descripción
feature_flags	`Dict[str, FeatureFlag]`	Un mapa de objetos `FeatureFlag`, indexados por claves de feature flag.
date_modified	`int`	La marca de tiempo (en milisegundos) que indica cuándo se modificó por última vez `DataFile`.

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

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

FeatureFlag

FeatureFlag representa un conjunto de propiedades que definen un feature flag en sí — por ejemplo, sus Variations](#variation), [Rules, estado del entorno y otros detalles relacionados. Se puede extender con información adicional si los clientes lo requieren. Si necesita más detalles, comuníquese con su Gerente de Éxito del Cliente.

Nombre	Tipo	Descripción
environment_enabled	`bool`	Indica si el feature flag está habilitado en el entorno actual.
default_variation_key	`str`	La clave de la variación predeterminada asociada con el feature flag.
variations	`Dict[str, Variation]`	Un mapa de objetos `Variation`, indexados por claves de variación.
rules	`Iterable[Rule]`	Una lista de objetos `Rule`

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

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

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

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

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

Variation

Variation contiene información sobre la variación asignada al visitante (o la variación predeterminada, si no existe una asignación específica).

Nombre	Tipo	Descripción
key	`str`	La clave única que identifica la variación.
id_	`Optional[int]`	El ID de la variación asignada (o `None` si es la variación predeterminada).
experiment_id	`Optional[int]`	El ID del experimento asociado con la variación (o `None` si es predeterminado).
variables	`Dict[str, Variable]`	Un diccionario que contiene las variables de la variación asignada, indexado por nombres de variables. Este valor podría estar vacío si no hay variables asociadas.

El objeto Variation proporciona detalles sobre la variación asignada y su experimento asociado, mientras que el objeto Variable contiene detalles específicos sobre cada variable dentro de una variación.
Asegúrese de que su código maneje el caso en que id_ o experiment_id pueden ser None, indicando una variación predeterminada.
El hash variables podría estar vacío si no hay variables asociadas con la variación.

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

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

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

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

Variable

Variable contiene información sobre una variable asociada con la variación asignada.

Nombre	Tipo	Descripción
key	`str`	La clave única que identifica la variable.
type	`str`	El tipo de la variable. Valores posibles: BOOLEAN, NUMBER, STRING, JSON, JS, CSS
value	`Optional[Any]`	El valor de la variable, que puede ser de los siguientes tipos: bool, int, float, str, dict, list.

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

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

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

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

Métodos obsoletos

Estos métodos están obsoletos y se eliminarán en la versión del SDK 4.0.0.

get_feature_variation_key()

📨 Envía datos de seguimiento a Kameleoon

Utilice get_variation() en su lugar.

Para obtener una clave de variación de feature, llame al método get_feature_variation_key. Este método toma visitor_code y feature_key como argumentos obligatorios para obtener una clave de variación para un usuario dado. Si tal usuario nunca ha sido asociado con este feature flag, el SDK devuelve una clave de variación aleatoriamente (de acuerdo con las reglas del feature flag). Si un usuario con un visitor_code dado ya está registrado con este feature flag, detectará el valor de variation key anterior. Si el usuario no coincide con ninguna de las reglas, se devolverá el valor predeterminado, que puede definir en su cuenta. 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 get_feature_variation_key usa el visitor_code como identificador único del visitante, lo cual es útil para experimentación entre dispositivos. Cuando especifica un visitor_code y establece el parámetro is_unique_identifier en true, el SDK vincula los datos vaciados al visitante asociado con el identificador especificado.

visitor_code = kameleoon_client.get_visitor_code(request.COOKIES)

feature_key = "feature_key"
variation_key = ""

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

Parámetros

Nombre	Tipo	Descripción
visitor_code	string	Identificador único del usuario. Este campo es obligatorio.
feature_key	string	Clave de la funcionalidad que desea exponer a un usuario. Este campo es obligatorio.
is_unique_identifier (Obsoleto)	Optional[bool]	Cuando es `True`, el SDK vincula los datos vaciados al visitante asociado con el identificador especificado.

Valor de retorno

Tipo	Descripción
string	Clave de variación del feature flag que está registrada para un visitor_code dado.

Excepciones lanzadas

Tipo	Descripción
FeatureNotFound	Excepción que indica que el ID de funcionalidad solicitado no se ha encontrado en la configuración interna del SDK. Esta excepción suele ser normal e indica que el feature flag aún no se ha activado en el lado de Kameleoon (pero el código que implementa la funcionalidad ya se ha desplegado en el lado de la aplicación web).
VisitorCodeInvalid	Excepción que indica que el código de visitante proporcionado no es válido (vacío o más largo que 255 caracteres).
FeatureEnvironmentDisabled	Excepción que indica que el feature flag está desactivado para ciertos entornos.

get_active_features()

Utilice get_variations() en su lugar.

Este método solo acepta el parámetro de entrada visitorCode. El resultado solo contiene las funcionalidades activas para un visitante determinado.

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

Argumentos

Nombre	Tipo	Descripción
visitor_code	str	Identificador único del usuario. Este campo es opcional.

Valor de retorno

Tipo	Descripción
Dict[str, Variation]	Lista de funcionalidades con variaciones asignadas que están activas para un visitor_code dado

Excepciones lanzadas

Tipo	Descripción
VisitorCodeInvalid	Excepción que indica que el código de visitante proporcionado es inválido. Está vacío o es más largo que 255 caracteres.

get_active_feature_list_for_visitor()

Utilice get_variation() en su lugar.

Este método solo acepta el parámetro de entrada visitorCode. El resultado solo contiene los feature flags activos para un visitante determinado.

active_feature_flag_for_visitor = kameleoonClient.get_active_feature_list_for_visitor(visitor_code)

Argumentos

Nombre	Tipo	Descripción
visitor_code	str	Identificador único del usuario. Este campo es opcional.

Valor de retorno

Tipo	Descripción
List[str]	Lista de claves de feature flag que están activas para un visitor_code dado

get_feature_variable()

📨 Envía datos de seguimiento a Kameleoon

Utilice get_variation() en su lugar.

Anteriormente llamado obtain_feature_variable, que se eliminó en la versión del SDK 3.0.0.

Para obtener una variable de la clave de variación asociada con un usuario, llame al método get_feature_variable. Este método toma un visitor_code, feature_key y variable_key como argumentos obligatorios. Si un usuario nunca ha sido asociado con este feature flag, el SDK devuelve un valor de variable aleatoriamente (de acuerdo con las reglas del feature flag). Si un usuario con un visitor_code dado ya está registrado con este feature flag, detectará el valor de variable para la variation asociada. Si el usuario no coincide con ninguna de las reglas, se devolverá la variable predeterminada. 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 get_feature_variable usa el visitor_code como identificador único del visitante, lo cual es útil para experimentación entre dispositivos. Cuando especifica un visitor_code y establece el parámetro is_unique_identifier en true, el SDK vincula los datos vaciados al visitante asociado con el identificador especificado.

visitor_code = kameleoon_client.get_visitor_code(request.COOKIES)

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

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

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

Parámetros

Nombre	Tipo	Descripción
visitor_code	str	Identificador único del usuario. Este campo es obligatorio.
feature_key	str	Clave de la funcionalidad que desea exponer a un usuario. Este campo es obligatorio.
variable_key	str	Nombre de la variable cuyo valor desea obtener. Este campo es obligatorio.
is_unique_identifier (Obsoleto)	Optional[bool]	Cuando es `True`, el SDK vincula los datos vaciados al visitante asociado con el identificador especificado.

Valor de retorno

Tipo	Descripción
Union[bool, str, float, Dict[str, Any], List[Any], None]	Valor de la variable de una variación que está registrada para un visitor_code dado para este feature flag. Tipos posibles: bool, float, str, List, Dict, None

Excepciones lanzadas

Tipo	Descripción
FeatureNotFound	Excepción que indica que el ID de funcionalidad solicitado no se ha encontrado en la configuración interna del SDK. Esta excepción suele ser normal e indica que el feature flag aún no se ha activado en el lado de Kameleoon (pero el código que implementa la funcionalidad ya se ha desplegado en el lado de la aplicación web).
VisitorCodeInvalid	Excepción que indica que el código de visitante proporcionado no es válido (vacío o más largo que 255 caracteres).
FeatureVariableNotFound	Excepción que indica que la variable solicitada no se ha encontrado. Verifique que la clave de la variable coincida con la de su código.
FeatureEnvironmentDisabled	Excepción que indica que el feature flag está desactivado en ciertos entornos.

get_feature_variation_variables()

Utilice get_variation() en su lugar.

Anteriormente llamado get_feature_all_variables, que se eliminó en la versión del SDK 3.0.0.

Para recuperar todas las variables de feature, llame al método get_feature_variation_variables. Una variable de feature puede ser cambiada fácilmente a través de la aplicación web de Kameleoon. Este método toma el parámetro de entrada feature_key. Devolverá datos del tipo Dict[str,Any], como se define en la interfaz web. Lanzará una excepción (FeatureNotFound) si la funcionalidad solicitada no se ha encontrado en la configuración interna del SDK.

feature_key = "myFeature"

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

Parámetros

Nombre	Tipo	Descripción
feature_key	String	Clave de la funcionalidad que desea obtener. Este campo es obligatorio.

Valor de retorno

Tipo	Descripción
Dict[str, Any]	Datos asociados con este feature flag. El valor puede ser int, str, bool, Dict o List (dependiendo del tipo definido en la interfaz web).

Excepciones lanzadas

Tipo	Descripción
FeatureNotFound	Excepción que indica que el ID de funcionalidad solicitado no se ha encontrado en la configuración interna del SDK. Esta excepción suele ser normal e indica que el feature flag aún no se ha activado en el lado de Kameleoon.
FeatureEnvironmentDisabled	Excepción que indica que el feature flag está desactivado en ciertos entornos.

get_feature_list()

Anteriormente llamado obtain_feature_list, que se eliminó en la versión del SDK 3.0.0.

Devuelve una lista de claves de feature flags disponibles actualmente en el SDK.

all_feature_list = kameleoon_client.get_feature_list()

Valor de retorno

Tipo	Descripción
`List[str]`	Lista de claves de feature flag

on_update_configuration()

El método on_update_configuration() le permite manejar el evento cuando la configuración ha actualizado datos. Toma un parámetro de entrada, handler. El handler que se llamará cuando la configuración se actualice mediante un evento de configuración en tiempo real.

kameleoon_client.on_update_configuration(
    # configuration was updated
)

Parámetros

Nombre	Tipo	Descripción
`handler`	`Callable[[], None]`	El handler que se llamará cuando la configuración se actualice mediante un evento de configuración en tiempo real.

SDKs

​Guía del desarrollador

​Primeros pasos

​Instalación del cliente Python

​Configuración adicional

​Inicialización del cliente Kameleoon

​Activación de un feature flag

Asignación de un ID único a un usuario

Recuperación de la configuración de un flag

Adición de puntos de datos para segmentar a un usuario o filtrar / desglosar visitas en informes

Seguimiento de conversiones de objetivos

Envío de eventos a soluciones de analítica

​Uso del SDK de Python de Kameleoon en un entorno Django

​Experimentación entre dispositivos

​Sincronización de datos personalizados entre dispositivos

​Uso de datos personalizados para la fusión de sesiones

​Uso de una clave de bucketing personalizada

​Casos de uso

​Detalles técnicos

​Requisitos técnicos

​Condiciones de segmentación

​Registro de eventos

​Niveles de registro

​Gestión personalizada de los registros

​Referencia

​create()

Argumentos

Excepciones lanzadas

​wait_init_async()

Parámetros

Valor de retorno

​wait_init()

Parámetros

Valor de retorno

​is_ready()

Valor de retorno

​Feature flags y variaciones

​is_feature_active()

Parámetros

Valor de retorno

Excepciones lanzadas

​get_variation()

Parámetros

Valor de retorno

Excepciones lanzadas

​get_variations()

Parámetros

Valor de retorno

Excepciones lanzadas

​get_data_file()

Valor de retorno

​set_forced_variation()

Parámetros

Excepciones lanzadas

​evaluate_audiences()

Parámetros

Excepciones lanzadas

​Datos del visitante

​get_visitor_code()

Parámetros

Valor de retorno

Excepciones lanzadas

​add_data()

Parámetros

Excepciones

​flush()

Argumentos

​get_remote_data()

Parámetros

Valor de retorno

​get_remote_data_async()

Parámetros

Valor de retorno

​get_remote_visitor_data()

Parámetros

Uso de parámetros en get_remote_visitor_data()

Valor de retorno

​get_remote_visitor_data_async()

Parámetros

Valor de retorno

Guía del desarrollador

Primeros pasos

Instalación del cliente Python

Configuración adicional

Inicialización del cliente Kameleoon

Activación de un feature flag

Uso del SDK de Python de Kameleoon en un entorno Django

Experimentación entre dispositivos

Sincronización de datos personalizados entre dispositivos

Uso de datos personalizados para la fusión de sesiones

Uso de una clave de bucketing personalizada

Casos de uso

Detalles técnicos

Requisitos técnicos

Condiciones de segmentación

Registro de eventos

Niveles de registro

Gestión personalizada de los registros

Referencia

create()

wait_init_async()

wait_init()

is_ready()

Feature flags y variaciones

is_feature_active()

get_variation()

get_variations()

get_data_file()

set_forced_variation()

evaluate_audiences()

Datos del visitante

get_visitor_code()

add_data()

flush()

get_remote_data()

get_remote_data_async()

get_remote_visitor_data()

get_remote_visitor_data_async()

get_visitor_warehouse_audience()

get_visitor_warehouse_audience_async()

set_legal_consent()

forget()

Objetivos y analítica de terceros

get_engine_tracking_code()

track_conversion()

Eventos

set_event_handler()

Tipos de datos

Browser

PageView

Conversion

CustomData

Device

UserAgent

UniqueIdentifier

OperatingSystem

Cookie

Geolocation

ApplicationVersion

Tipos devueltos

DataFile

FeatureFlag

Variation

Variable

Métodos obsoletos

get_feature_variation_key()

get_active_features()

get_active_feature_list_for_visitor()

get_feature_variable()

get_feature_variation_variables()

get_feature_list()