> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK de Java

> Integre el SDK de Java de Kameleoon para ejecutar experimentos y activar feature flags en servidores de aplicaciones Java EE o Jakarta EE.

Con el SDK de Java de Kameleoon, puede ejecutar experimentos y activar feature flags en su servidor de aplicaciones Java EE / Jakarta EE.

**Primeros pasos**: Para obtener ayuda para comenzar, consulte la [guía del desarrollador](#developer-guide)

**Changelog**: Última versión del SDK de Java: 4.22.0 [Changelog](https://github.com/Kameleoon/client-java/blob/master/CHANGELOG.md).

**Métodos del SDK**: Para la documentación de referencia completa del SDK de Java, consulte la sección [referencia](#reference).

## Guía del desarrollador

Esta guía está diseñada para ayudarle a integrar nuestro SDK en unos minutos y comenzar a ejecutar experimentos en sus aplicaciones Java.

### Primeros pasos

#### Kit de inicio

Para facilitarle el comienzo, Kameleoon proporciona un kit de inicio y una aplicación de demostración para probar el SDK. El kit de inicio incluye una aplicación totalmente configurada con ejemplos que muestran cómo se pueden utilizar los métodos del SDK en una aplicación. El kit de inicio, la aplicación de demostración y las instrucciones detalladas están disponibles en [Starter kit for Java](https://github.com/Kameleoon/java-examples)

#### Instalación del cliente Java

El paquete de instalación está disponible en el repositorio Maven Central. Puede instalar el SDK de Java añadiendo una dependencia al archivo `pom.xml` de su proyecto, como se muestra en el ejemplo de la derecha. Si utiliza otro sistema de gestión de proyectos, consulte la página de [integraciones](https://search.maven.org/artifact/com.kameleoon/kameleoon-client-java) para ver ejemplos adicionales.

<Tabs>
  <Tab title="Java EE">
    ```java title="pom.xml" theme={null}
    <dependency>
      <groupId>com.kameleoon</groupId>
      <artifactId>kameleoon-client-java</artifactId>
      <version>4.16.0</version>
    </dependency>
    ```
  </Tab>

  <Tab title="Jakarta EE">
    ```java title="pom.xml" theme={null}
    <dependency>
      <groupId>com.kameleoon</groupId>
      <artifactId>kameleoon-client-java-jakarta</artifactId>
      <version>4.16.0</version>
    </dependency>
    ```
  </Tab>
</Tabs>

#### Configuración adicional

Cree un archivo de configuración `.properties` para proporcionar las credenciales y personalizar el comportamiento del SDK. También puede [descargar nuestro archivo de configuración de ejemplo](/assets/developer-docs/sdks/web-sdks/client-configs/client-java.properties).

Recomendamos guardar este archivo en la ruta predeterminada, `/etc/kameleoon/client-java.conf`, pero puede guardarlo en cualquier ubicación dentro del classpath con el nombre `kameleoon-client-java.properties`.

La siguiente tabla muestra las propiedades disponibles que puede configurar:

| Clave                                                                 | Descripción                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Valor predeterminado |
| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `clientId` / `client_id` (*obligatorio*)                              | Necesario para la autenticación con el servicio de Kameleoon. Para encontrar su `client_id`, consulte la documentación de [credenciales de API](/user-manual/account-and-team-management/users-and-teams/api-credentials).                                                                                                                                                                                                                                                                                                                                                                                                                                      |                      |
| `clientSecret` / `client_secret` (*obligatorio*)                      | Necesario para la autenticación con el servicio de Kameleoon. Para encontrar su `client_secret`, consulte la documentación de [credenciales de API](/user-manual/account-and-team-management/users-and-teams/api-credentials).                                                                                                                                                                                                                                                                                                                                                                                                                                  |                      |
| `sessionDuration` / `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         |
| `refreshInterval` / `refresh_interval_minute` (*opcional*)            | Especifica el intervalo de actualización, en minutos, con el que el SDK obtiene la configuración de los experimentos activos y los feature flags. El valor determina el tiempo máximo necesario para propagar los cambios, como activar o desactivar feature flags o lanzar experimentos, a sus servidores de producción. Adicionalmente, ofrecemos un [modo streaming](/developer-docs/feature-experimentation/technical-reference/technical-considerations/#streaming-premium-option) que utiliza server-sent events (SSE) para enviar nuevas configuraciones al SDK automáticamente y aplicar las nuevas configuraciones en tiempo real, sin ningún retraso. | `60` minutos         |
| `defaultTimeout` / `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 |
| `trackingInterval` / `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` / `environment` (*opcional*)                            | Entorno desde el cual se debe utilizar la configuración del feature flag. El valor puede ser `production`, `staging` o `development`. Consulte el artículo de [gestión de entornos](/user-manual/experimentation/feature-experimentation/configure-your-feature-flags/manage-environments) para más detalles.                                                                                                                                                                                                                                                                                                                                                   | `production`         |
| `topLevelDomain` / `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.                                                                                                                                                                                                                                                                                                                                                                                                            | `null`               |
| `proxyHost` / `proxy_host` (*opcional*)                               | Establece el host proxy para todas las llamadas de salida al servidor realizadas por el SDK.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `null`               |
| `networkDomain` / `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.                                                                                                                                                                                                                                                                                                                                                                                                                     | `null`               |

#### Inicialización del cliente Kameleoon

Después de instalar el SDK en su aplicación y configurar sus credenciales y el comportamiento del SDK (en `/etc/kameleoon/client-java.conf`), el siguiente paso es crear el cliente Kameleoon en el código de su aplicación. Por ejemplo:

```java theme={null}
import com.kameleoon.KameleoonClientFactory;

String siteCode = "a8st4f59bj";

try {
    KameleoonClient kameleoonClient = KameleoonClientFactory.create(siteCode, "custom/file/path/client-java.properties");
} catch (KameleoonException.SiteCodeIsEmpty e) {
    // indicates that provided site code is empty
} catch (KameleoonException.ConfigCredentialsInvalid exception) {
    // indicates that provided clientId / clientSecret are not valid
}

try {
    KameleoonClientConfig config = new KameleoonClientConfig.Builder()
    .clientId("<clientId>") // mandatory
    .clientSecret("<clientSecret>") // mandatory
    .refreshInterval(60) // in minutes, optional (60 minutes by default)
    .sessionDuration(30) // in minutes, optional (30 minutes by default)
    .defaultTimeout(10_000) // in milliseconds, optional (10000 ms by default)
    .trackingInterval(1000) // in milliseconds, optional (1000 ms by default)
    .topLevelDomain("example.com") // mandatory if you use hybrid mode (engine or web experiments)
    .environment("development") // optional
    .proxyHost(new HttpHost("192.168.0.25", 8080, "http")) // optional
    .networkDomain("example.com") // optional
    .build();
    KameleoonClientFactory.create(siteCode, config);
} catch (KameleoonException.SiteCodeIsEmpty e) {
    // indicates that provided site code is empty
} catch (KameleoonException.ConfigCredentialsInvalid exception) {
    // indicates that provided clientId / clientSecret are not valid
}
```

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 necesita para ejecutar un experimento. Tenga en cuenta que también admitimos el uso de un proxy HTTP en el SDK de Java (consulte la [referencia del método `create()`](#create) para más detalles).

<Note>
  Es su responsabilidad asegurarse de que la lógica del código de su aplicación sea correcta en el contexto del A/B testing a través de Kameleoon. Una buena práctica es asumir siempre que puede excluir al visitante actual del experimento si aún no ha lanzado el experimento. Esta exclusión es sencilla porque corresponde a la implementación de la lógica de variación predeterminada y de referencia.
</Note>

Ya está listo para comenzar a crear e implementar experimentos y feature flags.

#### 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 [`getVisitorCode()`](#getvisitorcode). Si no existe un **visitor code** (en la cookie de los encabezados de la solicitud), el método genera un ID único aleatorio o utiliza un `defaultVisitorCode` que usted haya generado. A continuación, el ID se establece en una cookie en los encabezados de respuesta.

Si está usando Kameleoon en [modo híbrido](/developer-docs/feature-experimentation/get-started/hybrid-experimentation), llamar al método `getVisitorCode()` 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 [`getVariation()`](#getvariation) o [`isFeatureActive()`](#isfeatureactive) para recuperar la configuración basada en el `featureKey`.

El método `getVariation()` 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 `featureKey` y el `visitorCode`.

El método `isFeatureActive()` 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), `getVariation()` también le permite acceder al objeto [`Variation`](#variation), que proporciona detalles sobre la variación asignada y su experimento asociado. Este método comprueba si el usuario está segmentado, encuentra la variación asignada al visitante y la guarda en almacenamiento. Cuando `track=true`, el SDK enviará el evento de exposición al experimento especificado en la siguiente solicitud de seguimiento, que se desencadena automáticamente según el [`tracking_interval_millisecond`](#additional-configuration) del SDK. De forma predeterminada, este intervalo está configurado en 1000 milisegundos (1 segundo).

El método `getVariation()` 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 realizar el seguimiento de los datos a través del SDK y, en su lugar, basarse en el seguimiento del lado del cliente gestionado por el motor de Kameleoon, por ejemplo. Además, establecer `track=false` resulta útil cuando se utiliza el método `getVariations()`, donde puede que solo necesite las variaciones de todos los flags sin desencadenar eventos de seguimiento. Si desea saber más sobre cómo funciona el seguimiento, consulte [este artículo](/developer-docs/feature-experimentation/technical-reference/faq-global#when-does-the-sdk-send-a-tracking-request-for-analytics)

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

Para segmentar a un usuario, asegúrese de haber añadido los puntos de datos relevantes a su perfil antes de recuperar la variación de la funcionalidad o comprobar si el flag está activo. Utilice el método [`addData()`](#adddata) para añadir estos puntos de datos al perfil del usuario.

Para recuperar puntos de datos recopilados en otros dispositivos o acceder a datos pasados del usuario (recopilados en el lado del cliente cuando se utiliza Kameleoon en modo híbrido), utilice el método [`getRemoteVisitorData()`](#getremotevisitordata). Este método obtiene datos de los servidores de forma asíncrona. Es importante llamar a `getRemoteVisitorData()` *antes* de recuperar la variación o comprobar si el feature flag está activo, ya que estos datos pueden ser necesarios para asignar a 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](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation).

Además, los puntos de datos que añade al perfil del visitante estarán disponibles al analizar sus experimentos, lo que le permite filtrar y desglosar sus resultados por factores como el dispositivo y el navegador. El modo híbrido de Kameleoon recopila automáticamente una variedad de puntos de datos en el lado del cliente, lo que facilita desglosar sus resultados en función de estos puntos de datos previamente recopilados. Consulte la lista completa [aquí](/es/user-manual/experiment-analytics/analyze-results/results-page/results-page-settings#desglose-de-audiencia).

Si necesita realizar el seguimiento de puntos de datos adicionales más allá de los que se recopilan automáticamente, puede utilizar la [funcionalidad de Custom Data](#customdata) de Kameleoon. Custom Data le permite capturar y analizar información específica relevante para sus experimentos. No olvide llamar al método [`flush()`](#flush) para enviar los datos recopilados a los servidores de Kameleoon para su análisis.

<Note>
  Para asegurarse de que sus resultados sean precisos, se recomienda filtrar los bots utilizando el tipo de dato [`UserAgent`](#useragent).
</Note>

##### 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 [`trackConversion()`](#trackconversion) y proporcione los parámetros requeridos `visitorCode` y `goalId`.

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`](#additional-configuration)). Si prefiere enviar la solicitud de inmediato, utilice el método [`flush()`](#flush) con el parámetro `instant=true`.

##### Envío de eventos a soluciones de analítica

Para realizar el seguimiento de las conversiones y enviar eventos de exposición a su solución de analítica de cliente, primero debe implementar Kameleoon en [modo híbrido](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/). A continuación, utilice el método [`getEngineTrackingCode()`](#getenginetrackingcode).

El método `getEngineTrackingCode()` 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 de una clave de bucketing personalizada

De forma predeterminada, Kameleoon utiliza un ID de visitante anónimo y único (`visitorCode`) para asignar usuarios a las variaciones de los feature flags. Este ID se genera y almacena habitualmente en el dispositivo del usuario (en una cookie del navegador para los SDKs del lado del cliente y del lado del servidor, y en almacenamiento persistente para los SDKs móviles). Sin embargo, en determinados escenarios puede necesitar asegurarse de 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 `visitorCode` 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 a nivel de cuenta u organización:** Para productos B2B o escenarios en los que desea asignar a todos los usuarios de la misma organización a la misma variación, puede utilizar un identificador como `accountId`. Las claves de bucketing personalizadas son cruciales para probar mediante A/B funcionalidades que afecten a todo un equipo o empresa.

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:

```java theme={null}
kameleoonClient.addData(visitorCode, new CustomData(index, "newVisitorCode"));
```

* **Proporcionar la clave personalizada:** Usted proporciona su identificador personalizado al SDK de Kameleoon mediante el método [`addData()`](#adddata). En este método, pasará la clave de bucketing personalizada que haya elegido como un objeto [`CustomData`](#customdata). Aquí, `newVisitorCode` hace referencia al identificador que desea usar para el bucketing (por ejemplo, el nuevo `userId` o `accountId`).

<Warning>
  Para que la clave de bucketing personalizada funcione correctamente, también debe definirse y configurarse para el feature flag durante el proceso de creación o edición del flag. Sin esta configuración correspondiente, el bucketing del SDK no aplicará su clave personalizada. Para obtener instrucciones detalladas sobre cómo configurar esto en Kameleoon, consulte este [artículo](/user-manual/experimentation/feature-experimentation/create-and-manage-flags/create-a-feature-flag#Advanced_Flag_Settings).
</Warning>

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

#### Requisitos técnicos

Para utilizar eficazmente una clave de bucketing personalizada:

* La clave debe ser un `String`.
* Debe ser única para la entidad que pretende agrupar (por ejemplo, si utiliza un `userId`, 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](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation).

También puede utilizar sus propios [datos externos para segmentar a los usuarios](/developer-docs/apis/data-api-rest/tutorials/storing-and-retrieving-external-data-to-target-users).

### Experimentación entre dispositivos

Para dar soporte a los visitantes que acceden a una aplicación desde varios dispositivos, Kameleoon permite sincronizar los datos del visitante previamente recopilados entre cada uno de sus dispositivos y reconciliar su historial de visitas entre dispositivos mediante la experimentación entre dispositivos. Los casos de estudio y la información detallada sobre cómo Kameleoon gestiona los datos entre dispositivos están disponibles en el [artículo sobre experimentación entre dispositivos](/developer-docs/cross-device-experimentation).

#### Sincronización de datos personalizados entre dispositivos

Aunque la sincronización de mapeo personalizado se utiliza para alinear los datos del visitante entre dispositivos, no siempre es necesaria. A continuación se presentan dos escenarios en los que no se requiere la sincronización de mapeo personalizado:

**Mismo ID de usuario en todos los dispositivos**
Si el mismo ID de usuario se utiliza de forma consistente en todos los dispositivos, la sincronización se gestiona automáticamente sin necesidad de una sincronización de mapeo personalizado. Basta con llamar al método `getRemoteVisitorData()` cuando desee sincronizar los datos recopilados entre varios dispositivos.

**Instancias multi-servidor con IDs consistentes**
En configuraciones complejas que involucran varios 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 `getRemoteVisitorData()`) es suficiente sin necesidad de una sincronización adicional de mapeo personalizado.

Los clientes que necesiten datos adicionales pueden consultar la descripción del método [`getRemoteVisitorData()`](#getremotevisitordata) para obtener más orientación. En el código siguiente se asume que el mismo identificador único (en este caso, el `visitorCode`, que también puede denominarse `userId`) se utiliza de manera consistente entre los dos dispositivos para una recuperación precisa de los datos.

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

```java title="Device A" theme={null}
// In this example, a Custom data with index `90` was set to "Visitor" scope in Kameleoon.
final int VISITOR_SCOPE_CUSTOM_DATA_INDEX = 90;

kameleoonClient.addData(visitorCode, new CustomData(VISITOR_SCOPE_CUSTOM_DATA_INDEX, "your data"));
kameleoonClient.flush(visitorCode);
```

```java title="Device B" theme={null}
// Before working with the data, call the `getRemoteVisitorData` method.
kameleoonClient.getRemoteVisitorData(visitorCode).get();

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

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

La [experimentación entre dispositivos](/developer-docs/cross-device-experimentation) permite combinar el historial de un visitante en cada uno de sus dispositivos (reconciliación de historial). La reconciliación de historial permite fusionar diferentes sesiones de un visitante en una sola. Para reconciliar el historial de visitas, utilice [`CustomData`](#customdata) para proporcionar un identificador único del visitante. Para más información, consulte la [documentación dedicada](/developer-docs/cross-device-experimentation/#activating-cross-device-history-reconciliation).

Una vez habilitada la reconciliación entre dispositivos, al llamar a [`getRemoteVisitorData()`](#getremotevisitordata) con el parámetro `userId` se recuperan todos los datos conocidos para 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í](/developer-docs/cross-device-experimentation#critical-points-and-practical-insights).

Siga la guía de [activación de la reconciliación de historial entre dispositivos](#cross-device-experimentation) 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:

* `getRemoteVisitorData()` con `UniqueIdentifier(true)` añadido: para recuperar datos de todos los visitantes vinculados.
* [`trackConversion()`](#trackconversion) o [`flush()`](#flush) con datos `UniqueIdentifier(true)` añadidos: para hacer seguimiento de datos de un visitante específico asociado con otro visitante.

<Tip>
  Como el dato personalizado que utiliza como identificador debe configurarse con ámbito **Visitor**, necesita usar la [sincronización de datos personalizados entre dispositivos](/developer-docs/cross-device-experimentation) para recuperar el identificador con el método [`getRemoteVisitorData()`](#getremotevisitordata) en cada dispositivo.
</Tip>

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

```java theme={null}
// In this example, 91 represents the Custom Data's index configured as a unique identifier in Kameleoon.
final int MAPPING_INDEX = 91;
final String FEATURE_KEY = "ff123";

// 1. Before the visitor is authenticated

// Retrieve the variation for an unauthenticated visitor.
// Assume anonymousVisitorCode is the randomly generated ID for that visitor.
Variation anonymousVariation = kameleoonClient.getVariation(anonymousVisitorCode, FEATURE_KEY);

// 2. After the visitor is authenticated

// Assume `userId` is the visitor code of the authenticated visitor.
kameleoonClient.addData(anonymousVisitorCode, new CustomData(MAPPING_INDEX, userId));
kameleoonClient.flush(true, anonymousVisitorCode);

// Indicate that `userId` is a unique identifier.
kameleoonClient.addData(userId, new UniqueIdentifier(true));

// 3. After the visitor was authorized

// Retrieve the variation for the `userId`, which will match the anonymous visitor code's variation.
Variation userVariation = kameleoonClient.getVariation(userId, FEATURE_KEY);
boolean isSameVariation = userVariation.getKey().equals(anonymousVariation.getKey()); // true

// `userId` and `anonymousVisitorCode` are now linked and can be tracked as a single visitor.
kameleoonClient.trackConversion(userId, 123, 10.0);

// Additionally, the linked visitors share all fetched previously tracked remote data.
kameleoonClient.getRemoteVisitorData(userId).get();
```

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 [`getVisitorCode()`](#getvisitorcode). 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.

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

```java theme={null}
// The `NONE` log level does not allow logging.
com.kameleoon.logging.KameleoonLogger.setLogLevel(com.kameleoon.logging.LogLevel.NONE);

// The `ERROR` log level only allows logging issues that may affect the SDK's primary behaviour.
com.kameleoon.logging.KameleoonLogger.setLogLevel(com.kameleoon.logging.LogLevel.ERROR);

// The `WARNING` log level allows logging issues which may require an attention.
// It extends the `ERROR` log level.
// The `WARNING` log level is a default log level.
com.kameleoon.logging.KameleoonLogger.setLogLevel(com.kameleoon.logging.LogLevel.WARNING);

// The `INFO` log level allows logging general information on the SDK's internal processes.
// It extends the `WARNING` log level.
com.kameleoon.logging.KameleoonLogger.setLogLevel(com.kameleoon.logging.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.
com.kameleoon.logging.KameleoonLogger.setLogLevel(com.kameleoon.logging.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.

<Note>
  El filtrado por nivel de log se realiza de forma independiente de la lógica de gestión de los registros.
</Note>

```java theme={null}
public class CustomLogger implements com.kameleoon.logging.Logger {
    private final java.util.logging.Logger inner;

    public CustomLogger(java.util.logging.Logger inner) {
        this.inner = inner;
    }

    // `log` method accepts logs from the SDK
    @Override
    public void log(com.kameleoon.logging.LogLevel level, String message) {
        // Custom log handling logic here. For example:
        switch (level) {
            case ERROR:
                inner.log(java.util.logging.Level.SEVERE, message);
                break;
            case WARNING:
                inner.log(java.util.logging.Level.WARNING, message);
                break;
            case INFO:
                inner.log(java.util.logging.Level.INFO, message);
                break;
            case DEBUG:
                inner.log(java.util.logging.Level.FINE, message);
                break;
        }
    }
}

// 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.
com.kameleoon.logging.KameleoonLogger.setLogLevel(com.kameleoon.logging.LogLevel.DEBUG); // Optional; defaults to `LogLevel.WARNING`.
com.kameleoon.logging.KameleoonLogger.setLogger(new CustomLogger());
```

## Referencia

Esta es la documentación de referencia completa del SDK de Java.

### Inicialización

#### create()

Para utilizar el SDK, debe finalizar la inicialización. Su aplicación realiza todas las interacciones con el SDK a través de un objeto de la clase `KameleoonClient`. Cree este objeto utilizando el método estático `create()` en `KameleoonClientFactory`.

```java theme={null}
import com.kameleoon.KameleoonClientFactory;

String siteCode = "a8st4f59bj";

try {
    KameleoonClient kameleoonClient = KameleoonClientFactory.create(siteCode, "custom/file/path/client-java.properties");
} catch (KameleoonException.SiteCodeIsEmpty e) {
    // indicates that provided site code is empty
} catch (KameleoonException.ConfigCredentialsInvalid exception) {
    // indicates that provided clientId / clientSecret are not valid
}

try {
    KameleoonClientConfig config = new KameleoonClientConfig.Builder()
        .clientId("<clientId>") // mandatory
        .clientSecret("<clientSecret>") // mandatory
        .refreshInterval(60) // in minutes, optional (60 minutes by default)
        .sessionDuration(30) // in minutes, optional (30 minutes by default)
        .defaultTimeout(10_000) // in milliseconds, optional (10000 ms by default)
        .trackingInterval(1000) // in milliseconds, optional (1000 ms by default)
        .topLevelDomain("example.com") // mandatory if you use hybrid mode (engine or web experiments)
        .environment("development") // optional
        .proxyHost(new HttpHost("192.168.0.25", 8080, "http")) // optional
        .networkDomain("example.com") // optional
        .build();
    KameleoonClientFactory.create(siteCode, config);
} catch (KameleoonException.SiteCodeIsEmpty e) {
    // indicates that provided site code is empty
} catch (KameleoonException.ConfigCredentialsInvalid exception) {
    // indicates that provided clientId / clientSecret are not valid
}
```

##### Argumentos

| Nombre                         | Tipo                    | Descripción                                                                                                               | Valor predeterminado              |
| ------------------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| siteCode (*obligatorio*)       | `String`                | Es la [clave única](/user-manual/faq#how-do-i-find-my-sitecode) del proyecto de Kameleoon que está utilizando con el SDK. |                                   |
| configurationPath (*opcional*) | `String`                | Ruta al archivo de configuración del SDK.                                                                                 | `/etc/kameleoon/client-java.conf` |
| kameleoonConfig (*opcional*)   | `KameleoonClientConfig` | Objeto de configuración del SDK que puede pasar en lugar de utilizar un archivo de configuración.                         | `null`                            |

##### Valor de retorno

| Tipo              | Descripción                                                                                                                   |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `KameleoonClient` | Una instancia de la clase `KameleoonClient` que su aplicación puede utilizar para gestionar sus experimentos y feature flags. |

##### Excepciones lanzadas

| Tipo                                        | Descripción                                                                                                                                   |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| KameleoonException.ConfigCredentialsInvalid | Excepción que indica que las credenciales solicitadas no se proporcionaron (ni en el archivo de configuración ni como argumentos del método). |
| KameleoonException.SiteCodeIsEmpty          | Excepción que indica que el site code especificado es una cadena vacía, lo que no es un valor válido.                                         |

#### waitInit()

`waitInit()` espera a la inicialización del `KameleoonClient`. Este método le permite comprobar si el SDK ha inicializado correctamente el cliente antes de proceder con otras operaciones.

<Note>
  Si el método `waitInit()` falla, el proceso de inicialización continuará sin interrupción. Las llamadas posteriores al método `waitInit()` devolverán resultados que reflejan el estado actual del `KameleoonClient`. Por lo tanto, puede invocar el método `waitInit()` varias veces para comprobar el estado del SDK.
</Note>

```java theme={null}
// Synchronized approach
try {
    kameleoonClient.waitInit().get();
} catch (InterruptedException | ExecutionException exception) {
    // Indicates that the client could not be initialized due to the thrown exception.
}

// Asynchronous approach
kameleeoonClient.waitInit().handle((res, ex) -> {
    if (ex != null) {
        // Indicates that the client could not be initialized due to the thrown exception.
    }
    return res;
});
```

##### Valor de retorno

| Tipo                      | Descripción                                                                  |
| ------------------------- | ---------------------------------------------------------------------------- |
| `CompletableFuture<Void>` | La tarea se completará cuando el cliente se haya inicializado correctamente. |

##### Excepciones lanzadas

| Tipo        | Descripción                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------ |
| SDKNotReady | Excepción que indica que el cliente no se ha inicializado correctamente y todavía no puede utilizarse. |

### Feature flags y variaciones

#### isFeatureActive()

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

<Note>
  Este método se llamaba anteriormente `activeFeature`, que fue eliminado en la versión `4.0.0` del SDK.
</Note>

Llame a este método para comprobar si un feature flag debe estar activo para un usuario especificado. Este método toma un `visitorCode` y un `featureKey` como argumentos obligatorios para comprobar si la funcionalidad está activa para el usuario.

Si el usuario nunca ha sido asociado con este feature flag, el SDK devuelve un valor booleano aleatorio (ya sea `true` para añadir al usuario a esta funcionalidad o `false` para excluirlo de la funcionalidad). Si un usuario con el `visitorCode` especificado ya está registrado en este feature flag, el SDK detecta el valor anterior del `featureFlag`.

Asegúrese de capturar y gestionar las posibles excepciones.

Si especifica un `visitorCode`, el método `isFeatureActive()` lo usa como identificador único del visitante, lo cual es útil para la [experimentación entre dispositivos](/developer-docs/cross-device-experimentation). Cuando especifica un `visitorCode` y establece el parámetro `isUniqueIdentifier` en `true`, el SDK vincula los datos vaciados con el visitante asociado al identificador especificado.

<Note>
  El parámetro `isUniqueIdentifier` está obsoleto. Utilice en su lugar [`UniqueIdentifier`](#uniqueidentifier).

  `isUniqueIdentifier` puede ser útil en situaciones particulares; por ejemplo, si no puede acceder al `visitorCode` anónimo asignado a un visitante, pero puede usar un ID interno vinculado a ese visitante a través de la fusión de sesiones.
</Note>

```java theme={null}
String visitorCode = kameleoonClient.getVisitorCode(httpServletRequest, httpServletResponse);
String featureKey = "new_checkout";
Boolean hasNewCheckout = false;

try {
  hasNewCheckout = kameleoonClient.isFeatureActive(visitorCode, featureKey);
  // disabling tracking
  hasNewCheckout = kameleoonClient.isFeatureActive(false, visitorCode, featureKey);
} catch (KameleoonException.FeatureNotFound e) {
  // Feature toggle not yet activated on Kameleoon's side - we consider the feature inactive.
  hasNewCheckout = false;
} catch (Exception e) {
  // This is a generic exception handler that handles all exceptions.
  System.out.println("Exception occurred");
}
if (hasNewCheckout)
{
  // Implement new checkout code here
}
```

##### Argumentos

| Nombre                        | Tipo      | Descripción                                                                                                                                              |
| ----------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| track                         | `boolean` | An optional parameter to enable or disable tracking of the feature evaluation (`true` by default).                                                       |
| visitorCode                   | `String`  | Identificador único del usuario. Este campo es obligatorio.                                                                                              |
| featureKey                    | `String`  | Clave de la funcionalidad cuyo estado desea comprobar para el usuario. Este campo es obligatorio.                                                        |
| isUniqueIdentifier (Obsoleto) | `boolean` | Parámetro opcional para indicar si el visitorCode es un identificador único. If not provided, el valor predeterminado es `false`. The field is optional. |

##### Valor de retorno

| Tipo      | Descripción                                                                       |
| --------- | --------------------------------------------------------------------------------- |
| `boolean` | Valor de la funcionalidad que está registrada para el `visitorCode` especificado. |

##### Excepciones lanzadas

| Tipo                                  | Descripción                                                                                                                                                                                                                                                                                          |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| KameleoonException.FeatureNotFound    | Excepción que indica que el ID de funcionalidad solicitado no se encontró en la configuración interna del SDK. Esta excepción suele significar que el feature flag aún no se ha activado del lado de Kameleoon (pero el código que implementa la funcionalidad ya está desplegado en la aplicación). |
| KameleoonException.VisitorCodeInvalid | Excepción que indica que el visitor code proporcionado no es válido. It is either empty or longer than 255 characters.                                                                                                                                                                               |

#### getVariation()

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

Recupera la [`Variation`](#variation) asignada a un visitante dado para un feature flag específico.

Este método toma un `visitorCode` and `featureKey` as mandatory arguments. The `track` argument is optional and defaults to `true`.

Devuelve la `Variation` asignada al visitante. Si el visitante no está asociado con ninguna regla de feature flag, el método devuelve la `Variation` predeterminada para el feature flag dado.

Asegúrese de implementar un manejo de errores adecuado en su código para gestionar las posibles excepciones.

<Note>
  La variación predeterminada se refiere a la variación asignada a un visitante cuando no coincide con ninguna regla de entrega predefinida para un feature flag. In other words, it is the fallback variation applied to all users who are not targeted by specific rules. Se representa como la variación en la sección "Then, for everyone else..." de la interfaz de administración.
</Note>

```java theme={null}
String visitorCode = kameleoonClient.getVisitorCode(httpServletRequest, httpServletResponse);
String featureKey = "new_checkout";
Variation variation;

try {
  variation = kameleoonClient.getVariation(visitorCode, featureKey);
  // disabling tracking
  variation = kameleoonClient.getVariation(visitorCode, featureKey, false);
} catch (KameleoonException.FeatureNotFound e) {
  // The error has occurred; the feature flag isn't found in the current configuration.
} catch (KameleoonException.FeatureEnvironmentDisabled e) {
  // The feature flag is disabled for the environment.
} catch (KameleoonException.VisitorCodeInvalid e) {
  // The visitor code you passed to the method is invalid and can't be accepted by SDK.
} catch (KameleoonException ex) {
  // Handle the common Kameleoon Exception
}

// Fetch a variable value for the assigned variation
String title = (String) variation.getVariables().get("title").getValue();

switch (variation.getKey()) {
  case 'on':
    // Main variation key is selected for visitorCode
    break;
  case 'alternative_variation':
    // Alternative variation key
    break;
  default:
    // Default variation key
    break;
}
```

##### Argumentos

| Name                        | Type      | Description                                                                                           | Default |
| --------------------------- | --------- | ----------------------------------------------------------------------------------------------------- | ------- |
| visitorCode (*obligatorio*) | `String`  | Identificador único del visitante.                                                                    |         |
| featureKey (*obligatorio*)  | `String`  | Clave de la funcionalidad que desea exponer a un visitante.                                           |         |
| track (*opcional*)          | `boolean` | Parámetro opcional para habilitar o deshabilitar el seguimiento de la evaluación de la funcionalidad. | `true`  |

##### Valor de retorno

| Tipo        | Descripción                                                                           |
| ----------- | ------------------------------------------------------------------------------------- |
| `Variation` | An assigned [`Variation`](#variation) to a given visitor for a specific feature flag. |

##### Excepciones lanzadas

| Tipo                         | Descripción                                                                                                                                                                                                                                                                                      |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `VisitorCodeInvalid`         | Excepción que indica que el visitor code proporcionado no es válido. It is either empty or longer than 255 characters.                                                                                                                                                                           |
| `FeatureNotFound`            | Excepción que indica que la clave de funcionalidad solicitada no se encontró en la configuración interna del SDK. Esto suele significar que el feature flag no está activado en la aplicación de Kameleoon (pero el código que implementa la funcionalidad ya está desplegado en la aplicación). |
| `FeatureEnvironmentDisabled` | Excepción que indica que el feature flag está deshabilitado para el entorno actual del visitante (por ejemplo, production, staging o development).                                                                                                                                               |

#### getVariations()

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

Recupera un map de objetos [`Variation`](#variation) asignados a un visitante dado para todos los feature flags.

Este método itera sobre todos los feature flags disponibles y devuelve la `Variation` asignada para cada flag asociado con el visitante especificado. It takes `visitorCode` as a mandatory argument, while `onlyActive` and `track` are optional.

* Si `onlyActive` se establece en `true`, el método `getVariations()` devolverá las variaciones de los feature flags siempre que el usuario no esté asignado a la variación `off`.
* El parámetro `track` controla si el método realizará el seguimiento de las asignaciones de variación. De forma predeterminada, it is set to `true`. Si se establece en `false`, el seguimiento estará deshabilitado.

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.

<Note>
  La variación predeterminada se refiere a la variación asignada a un visitante cuando no coincide con ninguna regla de entrega predefinida para un feature flag. In other words, it is the fallback variation applied to all users who are not targeted by specific rules. Se representa como la variación en la sección "Then, for everyone else..." de la interfaz de administración.
</Note>

```java theme={null}
try {
    Map<String, Variation> variations = kameleoonClient.getVariations(visitorCode);
    // only active variations
    Map<String, Variation> variations = kameleoonClient.getVariations(visitorCode, true);
    // disable tracking
    Map<String, Variation> variations = kameleoonClient.getVariations(visitorCode, true, false);
} catch (VisitorCodeInvalid e) {
    //  Handle exception
}
```

##### Argumentos

| Name                        | Type      | Description                                                                                                                   | Default |
| --------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- | ------- |
| visitorCode (*obligatorio*) | `String`  | Identificador único del visitante.                                                                                            |         |
| onlyActive (*opcional*)     | `boolean` | Parámetro opcional que indica si se deben devolver las variaciones para los feature flags activos (`true`) o todos (`false`). | `false` |
| track (*opcional*)          | `boolean` | Parámetro opcional para habilitar o deshabilitar el seguimiento de la evaluación de la funcionalidad.                         | `true`  |

##### Valor de retorno

| Tipo                     | Descripción                                                                                                                                          |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Map<String, Variation>` | Map que contiene los objetos [`Variation`](#variation) asignados de los feature flags utilizando las claves de las funcionalidades correspondientes. |

##### Excepciones lanzadas

| Tipo                 | Descripción                                                                                                            |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | Excepción que indica que el visitor code proporcionado no es válido. It is either empty or longer than 255 characters. |

#### setForcedVariation()

El método permite you to programmatically assign a specific [`Variation`](#variation) to a user, bypassing the standard evaluation process. Esto es especialmente valioso para experimentos controlados donde la lógica de evaluación habitual no es necesaria o debe omitirse. It can also be helpful in scenarios like debugging or custom testing.

Cuando se establece una variación **forzada**, esta anula la lógica de evaluación en tiempo real de Kameleoon. Processes like segmentation, targeting conditions, and algorithmic calculations are skipped. To preserve segmentation and targeting conditions during an experiment, set `forceTargeting=false` instead.

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

A forced variation is treated the same as an evaluated variation. It is tracked in analytics and stored in the user context like any standard evaluated variation, ensuring consistency in reporting.

El método puede lanzar excepciones bajo ciertas condiciones (por ejemplo, parámetros no válidos, contexto del usuario o problemas internos). Proper exception handling is essential to ensure that your application remains stable and resilient.

<Warning>
  It’s important to distinguish **forced** variations from **[simulated](#getvisitorcode)** variations:

  * **Forced variations**: Are specific to an individual experiment.
  * **Simulated variations**: Affect the overall **feature flag** result.
</Warning>

```java theme={null}
try {
    // Forcing the variation "on" for the feature flag "featureKey1" for the visitor
    final int experimentId = 9516;
    kameleoonClient.setForcedVariation(visitorCode, experimentId, "on");

    // Resetting the forced variation for the feature flag "featureKey1" for the visitor
    kameleoonClient.setForcedVariation(visitorCode, experimentId, null);
} catch (KameleoonException ex) {
    // Handle the common Kameleoon Exception
}
```

##### Argumentos

| Name                         | Type      | Description                                                                                                                                                                 | Default |
| ---------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| visitorCode (*obligatorio*)  | `String`  | Identificador único del visitante.                                                                                                                                          |         |
| experimentId (*obligatorio*) | `int`     | **Experiment Id** que será segmentado y seleccionado durante el proceso de evaluación.                                                                                      |         |
| variationKey (*obligatorio*) | `String`  | **Variation Key** correspondiente a una `Variation` que debe forzarse como valor devuelto para el experimento. Si el valor es `null`, la variación forzada se restablecerá. |         |
| forceTargeting (*opcional*)  | `boolean` | Indica si la segmentación para el 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. It is either empty or longer than 255 characters.                                                                                                                                  |
| `FeatureExperimentNotFound` | Excepción que indica que el experiment id solicitado no se encontró en la configuración interna del SDK. Esto suele ser normal y significa que el experimento correspondiente a la regla todavía no se ha activado del lado de Kameleoon.               |
| `FeatureVariationNotFound`  | Excepción que indica que la variation key (id) solicitada no se ha encontrado en la configuración interna del SDK. Esto suele ser normal y significa que el experimento correspondiente a la variación todavía no se ha activado del lado de Kameleoon. |

<Info>
  En la mayoría de los casos, solo es necesario gestionar el error básico `KameleoonException`, como se muestra en el ejemplo. However, if different types of errors require a response, handle each one separately based on specific requirements. Additionally, for enhanced reliability, general language errors can be handled by including `Exception`.
</Info>

#### evaluateAudiences()

* 📨 *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.

`evaluateAudiences()` should be called **after all relevant visitor data has been set or updated**, and **just before** getting a feature variation or checking a feature flag. Este enfoque garantiza que el visitante se evalúe con los datos más recientes disponibles, lo que permite una asignación precisa de audiencia basada en todos los criterios.

After calling this method, you can perform a detailed analysis of segment performance in Audiences Explorer.

```java theme={null}
try {
    kameleoonClient.evaluateAudiences(visitorCode);
} catch (KameleoonException ex) {
    // Handle the common Kameleoon Exception
}
```

##### Argumentos

| Nombre                      | Tipo     | Descripción                        |
| --------------------------- | -------- | ---------------------------------- |
| visitorCode (*obligatorio*) | `String` | Identificador único del visitante. |

##### Excepciones lanzadas

| Tipo                 | Descripción                                                                                                            |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | Excepción que indica que el visitor code proporcionado no es válido. It is either empty or longer than 255 characters. |

<Info>
  En la mayoría de los casos, solo es necesario gestionar el error básico `KameleoonException`, como se muestra en el ejemplo. However, if different types of errors require a response, handle each one separately based on specific requirements. Additionally, for enhanced reliability, general language errors can be handled by including `Exception`.
</Info>

#### getFeatureList()

<Note>
  Este método se llamaba anteriormente `obtainFeatureList`, que fue eliminado en la versión `4.0.0` del SDK.
</Note>

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

```java theme={null}
List<String> allFeatureFlagKey = kameleoonClient.getFeatureList();
```

##### Valor de retorno

| Tipo           | Descripción               |
| -------------- | ------------------------- |
| `List<String>` | List of feature flag keys |

#### getDataFile()

<Tip>
  To evaluate all feature flags, use [`getVariations()`](#getvariations). Este método es más eficiente que llamar a `DataFile` e iterar por los flags con [`getVariation()`](#getvariation).
</Tip>

Devuelve la configuración actual del SDK como un objeto [`DataFile`](#datafile).

```java theme={null}
try {
    DataFile dataFile = kameleoonClient.getDataFile();
} catch (Exception e) {
    // Recommended (but optional) safeguard for unexpected exceptions from third-party libraries
}
```

##### Valor de retorno

| Tipo       | Descripción                                                      |
| ---------- | ---------------------------------------------------------------- |
| `DataFile` | El [`DataFile`](#datafile) que contiene la configuración del SDK |

### Datos del visitante

#### getVisitorCode()

<Note>
  Este método se llamaba anteriormente `obtainVisitorCode`, que fue eliminado en la versión `4.0.0` del SDK.
</Note>

Se debe llamar al método `getVisitorCode()` para obtener el `visitorCode` de Kameleoon del visitante actual. This method is especially important when using Kameleoon in a mixed front-end and back-end environment, where user identification consistency must be guaranteed. La lógica de implementación se describe a continuación:

1. Comprobamos si se puede encontrar una cookie `kameleoonVisitorCode` o un parámetro de consulta asociados con la solicitud HTTP actual. If it can, we use this `kameleoonVisitorCode` as the visitor identifier.

2. If no cookie / parameter is found in the current request, we either randomly generate a new identifier or use the `defaultVisitorCode` argument as identifier if it is passed. Este proceso permite a nuestros clientes utilizar sus propios identificadores como visitor codes, si así lo desean. Esta flexibilidad tiene el beneficio adicional de hacer coincidir a los visitantes de Kameleoon con sus propios usuarios sin necesidad de búsquedas adicionales en una tabla de coincidencias.

3. En cualquier caso, la cookie `kameleoonVisitorCode` del lado del servidor (a través del encabezado HTTP) se establece con el valor relevante. A continuación, el método devuelve este valor de identificador.

Para más información, consulte [este artículo](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/).

<Warning>
  If you provide a `visitorCode`, its uniqueness must be guaranteed on your end - the SDK cannot check it. Además, tenga en cuenta que la longitud de `visitorCode` está limitada a `255` caracteres. Any excess characters will throw an exception.
</Warning>

<Info>
  El método `getVisitorCode()` 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`](#variation) basada en los datos proporcionados.

  Puede aplicar simulaciones de dos formas:

  * **Automatically (recommended):** If using Kameleoon Web Experimentation or the SDK in [Hybrid mode](/developer-docs/feature-experimentation/get-started/hybrid-experimentation#linking-feature-experiments-with-front-end-tracking-code), the cookie is created automatically when simulating a variant's display using the [Simulation Panel](/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/validation-and-rollback/using-simulation-mode).
  * **Manualmente:** Establezca la cookie `kameleoonSimulationFFData` manualmente.

  It’s important to distinguish **simulated** variations from **[forced](#setforcedvariation)** variations:

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

  ⚙️ **Manual setup**

  Asegúrese de que la cookie `kameleoonSimulationFFData` siga este formato:

  * `kameleoonSimulationFFData={"featureKey":{"expId":10,"varId":20}}`: Simula la variación con `varId` del experimento `expId` para el `featureKey` indicado.
  * `kameleoonSimulationFFData={"featureKey":{"expId":0}}`: Simula la variación predeterminada (definida en la sección **Then, for everyone else in Production, serve**) para el `featureKey` indicado.

  ⚠️ To ensure proper functionality, the cookie value must be encoded as a URI component using a method such as [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent).
</Info>

```java theme={null}
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

String visitorCode = kameleoonClient.getVisitorCode(httpServletRequest, httpServletResponse);

String visitorCode = kameleoonClient.getVisitorCode(httpServletRequest, httpServletResponse, defaultVisitorCode);
```

##### Argumentos

| Nombre              | Tipo                  | Descripción                                                                                                                                                                                                                                                              |
| ------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| httpServletRequest  | `HttpServletRequest`  | El objeto HttpServletRequest actual debe pasarse como primer parámetro. Este campo es obligatorio.                                                                                                                                                                       |
| httpServletResponse | `HttpServletResponse` | El objeto HttpServletResponse actual debe pasarse como segundo parámetro. Este campo es obligatorio.                                                                                                                                                                     |
| defaultVisitorCode  | `String`              | Este parámetro se usará como `visitorCode` cuando no se encuentre una cookie `kameleoonVisitorCode` existente en la solicitud. Este campo es opcional. Si no se especifica, el SDK genera un `visitorCode` aleatorio cuando no existe una cookie `kameleoonVisitorCode`. |

##### Valor de retorno

| Tipo     | Descripción                                                                                                               |
| -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `String` | A `visitorCode` that will be associated with this particular user and should be used with most of the methods of the SDK. |

#### addData()

El método `addData()` añade [datos de segmentación](#data-types) al almacenamiento para que otros métodos puedan utilizar los datos para decidir si segmentar o no al visitante actual.

El método `addData()` no devuelve ningún valor y no interactúa por sí mismo con los servidores backend de Kameleoon. En su lugar, todos los datos declarados se guardan para su transmisión futura mediante el método [`flush()`](#flush). Este enfoque reduce el número de llamadas al servidor, ya que los datos se agrupan habitualmente en una única llamada al servidor que desencadena el `flush()`.

El método [`trackConversion()`](#trackconversion) también envía cualquier dato previamente asociado, al igual que `flush()`. The same holds true for [`getVariation()`](#getvariation) and [`getVariations()`](#getvariations) methods if an experimentation rule is triggered.

<Tip>
  Cada visitante solo puede tener una instancia de datos asociados para la mayoría de los tipos de datos. However, [`CustomData`](#customdata) is an exception. Visitors can have one instance of associated `CustomData` per index.
</Tip>

```java theme={null}
// Add a single data item (tracked by default)
kameleoonClient.addData(visitorCode, Browser.chrome());

// Add multiple data items (tracked by default)
kameleoonClient.addData(visitorCode, new PageView("https://url.com", "title"), new UserAgent("UserAgent"));

// Add multiple data items stored locally for targeting only (not sent to the Kameleoon Data API)
kameleoonClient.addData(visitorCode, false, new PageView("https://url.com", "title"), new UserAgent("UserAgent"));
```

##### Argumentos

| Nombre                      | Tipo      | Descripción                                                                                                                                                                                                                       | Valor predeterminado |
| --------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| visitorCode (*obligatorio*) | `String`  | Identificador único del visitante.                                                                                                                                                                                                |                      |
| track (*opcional*)          | `boolean` | 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 segmentación; no se envían a la Data API de Kameleoon. | `true`               |
| data (*obligatorio*)        | `Data...` | Colección de tipos de datos de Kameleoon.                                                                                                                                                                                         |                      |

##### Excepciones

| Tipo                 | Descripción                                                                                                            |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | Excepción que indica que el visitor code proporcionado no es válido. It is either empty or longer than 255 characters. |

#### flush()

* *📨 Envía datos de seguimiento a Kameleoon*

El método `flush()` recopila los datos de Kameleoon vinculados al visitante. Después envía una solicitud de seguimiento, junto con todos los datos añadidos mediante el método `addData` que aún no se hayan enviado mediante uno de [estos métodos](/developer-docs/feature-experimentation/technical-reference/faq-global#when-does-the-sdk-send-a-tracking-request-for-analytics). `flush()` is non-blocking as the server call is made asynchronously.

`flush` le permite controlar cuándo se envían a nuestros servidores los datos asociados a un `visitorCode` determinado. For instance, if you call `addData()` a dozen times, it would be inefficient to send data to the server each time `addData()` is invoked. So, all you have to do is call `flush()` once.

Si especifica un `visitorCode`, el método `flush()` utiliza este código como identificador único del visitante, lo cual es útil para la [experimentación entre dispositivos](/developer-docs/cross-device-experimentation). Cuando especifica un `visitorCode` y establece el parámetro `isUniqueIdentifier` en `true`, el SDK vincula los datos vaciados con el visitante asociado al identificador especificado.

<Note>
  El parámetro `isUniqueIdentifier` está obsoleto. Utilice en su lugar [`UniqueIdentifier`](#uniqueidentifier).

  `isUniqueIdentifier` puede ser útil en situaciones particulares; por ejemplo, si no puede acceder al `visitorCode` anónimo asignado a un visitante, pero puede usar un ID interno vinculado a ese visitante a través de la fusión de sesiones.
</Note>

```java theme={null}

try {
    kameleoonClient.flush(visitorCode); // Interval tracking (most performant tracking method)
    kameleoonClient.flush(true, visitorCode); // Instant tracking
} catch (VisitorCodeInvalid e) {
  // Catch exception
}
```

##### Argumentos

| Nombre                        | Tipo      | Descripción                                                                                                                                                                                                                                                                                      |
| ----------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| instant                       | `boolean` | Boolean flag indicating whether the data should be sent instantly (`true`) or according to the default tracking interval (`false`) set with the SDK parameter [`tracking_interval_millisecond`](#additional-configuration). Este campo es opcional.                                              |
| visitorCode                   | `String`  | Identificador único del usuario. Este campo es obligatorio.                                                                                                                                                                                                                                      |
| isUniqueIdentifier (Obsoleto) | `boolean` | Parámetro opcional para indicar si el visitorCode es un identificador único. Se debe proporcionar el `visitorCode` y no ser `null` para aplicar `isUniqueIdentifier` a un visitante; de lo contrario, será ignorado. If not provided, el valor predeterminado es `false`. The field is optional. |

#### getRemoteData()

<Note>
  Este método se llamaba anteriormente `retrieveDataFromRemoteSource`, que fue eliminado en la versión `4.0.0` del SDK.
</Note>

El método `getRemoteData()` le permite recuperar datos (según una `key` pasada como argumento) para el `siteCode` especificado almacenados en el servidor de Kameleoon. Your site code is specified in `KameleoonClientFactory.create()`. Usually, data is stored on our remote servers using our Data API. Este método, junto con la disponibilidad de nuestros servidores escalables, proporciona una forma conveniente de almacenar datos adicionales que puede recuperar más tarde para su aplicación.

```java theme={null}
CompletableFuture<JsonObject> data = kameleoonClient.getRemoteData("key");

try {
  JsonObject test = kameleoonClient.getRemoteData("key").get(5_000, TimeUnit.MILLISECONDS);
} catch (InterruptedException | ExecutionException | TimeoutException e) {
  // Catch exception
}
```

##### Argumentos

| Nombre | Tipo     | Descripción                                                           |
| ------ | -------- | --------------------------------------------------------------------- |
| key    | `String` | La clave asociada a los datos recuperados. Este campo es obligatorio. |

##### Valor de retorno

| Tipo                            | Descripción                                                               |
| ------------------------------- | ------------------------------------------------------------------------- |
| `CompletableFuture<JsonObject>` | Future `JsonObject` associated with retrieving data for specific **key**. |

#### getRemoteVisitorData()

`getRemoteVisitorData()` es un método asíncrono para recuperar los datos de visitas de Kameleoon para el `visitorCode` desde la Data API de Kameleoon. El método añade los datos al almacenamiento para que otros métodos los utilicen al tomar decisiones de segmentación.

Los datos obtenidos mediante este método desempeñan un papel importante cuando desea:

* utilizar datos recopilados desde otros dispositivos.
* access a user's history, such as previously visited pages during past visits.
* utilizar datos a los que solo se puede acceder en el lado del cliente, como las variables del datalayer y los objetivos que convierten en el front-end.

Read [this article](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation) for a better understanding of possible use cases.

<Warning>
  De forma predeterminada, `getRemoteVisitorData()` automatically retrieves the latest stored custom data with `scope=Visitor` and attaches them to the visitor without the need to call the method `addData()`. It is particularly useful for [synchronizing custom data between multiple devices](/developer-docs/sdks/web-sdks/nodejs-sdk#synchronizing-custom-data-across-devices).
</Warning>

<Note>
  El parámetro `isUniqueIdentifier` está obsoleto. Utilice en su lugar [`UniqueIdentifier`](#uniqueidentifier).

  `isUniqueIdentifier` puede ser útil en situaciones particulares; por ejemplo, si no puede acceder al `visitorCode` anónimo asignado a un visitante, pero puede usar un ID interno vinculado a ese visitante a través de la fusión de sesiones.
</Note>

```java theme={null}
String visitorCode = "visitorCode";
// Visitor data will be fetched and automatically added for `visitorCode`
CompletableFuture<List<Data>> visitorData = kameleoonClient.getRemoteVisitorData(visitorCode);

// If you only want to fetch data and add it yourself manually, set addData == `false`
CompletableFuture<List<Data>> visitorData = kameleoonClient.getRemoteVisitorData(visitorCode, false);

// If you want to fetch custom list of data types
RemoteVisitorDataFilter filter = RemoteVisitorDataFilter.builder()
    .previousVisitAmount(25)
    .customData(false)
    .conversions(true)
    .build();
CompletableFuture<List<Data>> visitorData = kameleoonClient.getRemoteVisitorData(visitorCode, filter, true, false);

try {
  List<Data> visitorData = kameleoonClient.getRemoteVisitorData(visitorCode).get(5_000, TimeUnit.MILLISECONDS);
  // Your custom code
} catch (CancellationException | InterruptedException | ExecutionException | TimeoutException e) {
  // Catch exception
}
```

##### Argumentos

| Nombre                        | Tipo                      | Descripción                                                                                                                                                                                                                                                                                                                   |
| ----------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitorCode                   | string                    | The visitor code for the data you want to retrieve. Este campo es obligatorio.                                                                                                                                                                                                                                                |
| filter                        | `RemoteVisitorDataFilter` | Filtro para especificar qué datos deben recuperarse de las visitas. De forma predeterminada, only `CustomData` is retrieved from the current and latest previous visit (`RemoteVisitorDataFilter.builder().build()` or `new RemoteVisitorDataFilter()`). Other filters parameters are set to `false`. Este campo es opcional. |
| addData                       | `boolean`                 | Booleano que indica si el método debe añadir automáticamente los datos recuperados para un visitante. Este campo es opcional.                                                                                                                                                                                                 |
| isUniqueIdentifier (Obsoleto) | `boolean`                 | Parámetro opcional para indicar si el `visitorCode` es un identificador único. If not provided, el valor predeterminado es `false`. The field is optional.                                                                                                                                                                    |

##### Valor de retorno

| Tipo                            | Descripción                                          |
| ------------------------------- | ---------------------------------------------------- |
| `CompletableFuture<List<Data>>` | Future `List<Data>` associated with a given visitor. |

##### Uso de parámetros en getRemoteVisitorData()

El método `getRemoteVisitorData()` ofrece flexibilidad al permitirle definir varios parámetros al recuperar datos de los visitantes. Whether you're targeting based on goals, experiments, or variations, the same approach applies across all data types.

Por ejemplo, let's say you want to retrieve data on visitors who completed a goal "Order transaction". Puede especificar parámetros dentro del método `getRemoteVisitorData()` para refinar su segmentación. For instance, if you want to target only users who converted on the goal in their last five visits, you can set the `previousVisitAmount` parameter to 5 and `conversions` to true.

La flexibilidad mostrada en este ejemplo no se limita a los datos de objetivos. Puede usar parámetros dentro del método `getRemoteVisitorData()` para recuperar datos sobre una variedad de comportamientos del visitante.

<Note>
  A continuación se muestra la lista de opciones disponibles de `kameleoon.types.RemoteVisitorDataFilter`:

  | Name                             | Type      | Description                                                                                                                                                                                                                                                                                                                                     | Default |
  | -------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
  | previousVisitAmount (*opcional*) | `int`     | Número de visitas previas de las que recuperar datos. Number between `1` and `25`                                                                                                                                                                                                                                                               | `1`     |
  | currentVisit (*opcional*)        | `boolean` | If true, current visit data will be retrieved                                                                                                                                                                                                                                                                                                   | `true`  |
  | customData (*opcional*)          | `boolean` | If true, custom data will be retrieved.                                                                                                                                                                                                                                                                                                         | `true`  |
  | pageViews (*opcional*)           | `boolean` | If true, page data will be retrieved.                                                                                                                                                                                                                                                                                                           | `false` |
  | geolocation (*opcional*)         | `boolean` | If true, geolocation data will be retrieved.                                                                                                                                                                                                                                                                                                    | `false` |
  | device (*opcional*)              | `boolean` | If true, device data will be retrieved.                                                                                                                                                                                                                                                                                                         | `false` |
  | browser (*opcional*)             | `boolean` | If true, browser data will be retrieved.                                                                                                                                                                                                                                                                                                        | `false` |
  | operatingSystem (*opcional*)     | `boolean` | If true, operating system data will be retrieved.                                                                                                                                                                                                                                                                                               | `false` |
  | conversions (*opcional*)         | `boolean` | If true, conversion data will be retrieved.                                                                                                                                                                                                                                                                                                     | `false` |
  | experiments (*opcional*)         | `boolean` | If true, experiment data will be retrieved.                                                                                                                                                                                                                                                                                                     | `false` |
  | kcs (*opcional*)                 | `boolean` | If true, Kameleoon Conversion Score (KCS) will be retrieved. Requires the [AI Predictive Targeting add-on](/user-manual/ai-predictive-targeting/target-users-based-on-likelihood-to-convert)                                                                                                                                                    | `false` |
  | visitorCode (*opcional*)         | `boolean` | If true, Kameleoon will retrieve the `visitorCode` from the most recent visit and use it for the current visit. This is necessary if you want to ensure that the visitor, identified by their `visitorCode`, always receives the same variation across visits for [Cross-device experimentation](/developer-docs/cross-device-experimentation). | `true`  |
  | personalization (*opcional*)     | `boolean` | If true, personalization data will be retrieved. This is required for the personalization condition.                                                                                                                                                                                                                                            | `false` |
  | cbs (*opcional*)                 | `boolean` | If true, Contextual Bandit score data will be retrieved.                                                                                                                                                                                                                                                                                        | `false` |
</Note>

#### getVisitorWarehouseAudience()

Este método recupera all audience data associated with the visitor in your data warehouse using the specified `visitorCode` and `warehouseKey`. The `warehouseKey` is typically your internal user ID. The `customDataIndex` parameter corresponds to the Kameleoon custom data that Kameleoon uses to target your visitors. You can refer to the [warehouse targeting documentation](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting) for additional details. The method passes the result to the returned future as a `CustomData` object, confirming that the data has been added to the visitor and is available for targeting purposes.

```java theme={null}
CompletableFuture<CustomData> warehouseAudienceDataCF =
  kameleoonClient.getVisitorWarehouseAudience(visitorCode, warehouseKeyValue, customDataIndex);

// If you need to specify warehouse key
CompletableFuture<CustomData> warehouseAudienceDataCF =
  kameleoonClient.getVisitorWarehouseAudience(visitorCode, customDataIndex);

try {
  CustomData warehouseAudienceData = warehouseAudienceDataCF.get(5_000, TimeUnit.MILLISECONDS);
  // Your custom code
} catch (CancellationException | InterruptedException | ExecutionException | TimeoutException e) {
  // Catch exception
}
```

##### Argumentos

| Nombre          | Tipo     | Descripción                                                                                                      |
| --------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| visitorCode     | `String` | The unique identifier of the visitor for whom you want to retrieve and add the data.                             |
| warehouseKey    | `String` | The unique key to identify the warehouse data (usually, your internal user ID). Este campo es opcional.          |
| customDataIndex | `int`    | Entero que representa el índice del dato personalizado que desea utilizar para segmentar sus BigQuery Audiences. |

##### Valor de retorno

| Tipo                            | Descripción                                                                          |
| ------------------------------- | ------------------------------------------------------------------------------------ |
| `CompletableFuture<CustomData>` | Future `CustomData` instance confirming that the data has been added to the visitor. |

##### Excepciones lanzadas

| Tipo                 | Descripción                                                                                                     |
| -------------------- | --------------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | Excepción que indica que el visitor code proporcionado no es válido (está vacío o tiene más de 255 caracteres). |

#### setLegalConsent()

You must use this method to specify whether the visitor has given legal consent to use personal data. Setting the `legalConsent` parameter to `false` limits the types of data that you can include in tracking requests. This method helps you adhere to legal and regulatory requirements while responsibly managing visitor data. You can find more information on personal data in the [consent management policy](/user-manual/project-management/consent-management-policy).

```java theme={null}
// if you do not need to set the visitor code in a cookie to respond
kameleoonClient.setLegalConsent(visitorCode, true);

String visitorCode = kameleoonClient.getVisitorCode(httpServletRequest, httpServletResponse);
kameleoonClient.setLegalConsent(visitorCode, true, httpServletResponse);
```

##### Argumentos

| Nombre       | Tipo                | Descripción                                                                                                                                                                                                                           |
| ------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitorCode  | `String`            | Identificador único del usuario. Este campo es obligatorio.                                                                                                                                                                           |
| legalConsent | `boolean`           | Valor booleano que representa el estado del consentimiento legal. `true` indicates the visitor has given legal consent, `false` indicates the visitor has never provided, or has withdrawn, legal consent. Este campo es obligatorio. |
| response     | HttpServletResponse | The HTTP servlet response where values in the cookies will be adjusted based on the legal consent status. The field is optional.                                                                                                      |

##### Excepciones lanzadas

| Tipo                                  | Descripción                                                                                                    |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| KameleoonException.VisitorCodeInvalid | Excepción que indica que el visitor code proporcionado no es válido. Está vacío o tiene más de 255 caracteres. |

##### Comportamiento al revocar el consentimiento

Cuando llama a `setLegalConsent()` con `legalConsent=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.

### Objetivos y analítica de terceros

#### trackConversion()

* 📨 *Envía datos de seguimiento a Kameleoon*

Use este método para track a conversion for a specific [goal](/user-manual//assets/goals/create-a-goal) and user. This method requires `visitorCode` and `goalId`. In addition, this method also accepts an optional `revenue`, `negative` and `metadata` arguments. The `visitorCode` is usually identical to the one that was used when triggering the experiment.

El método `trackConversion()` no devuelve ningún valor. Este método no es bloqueante, ya que la llamada al servidor se realiza de forma asíncrona.

<Note>
  El parámetro `isUniqueIdentifier` está obsoleto. Utilice en su lugar [`UniqueIdentifier`](#uniqueidentifier).

  `isUniqueIdentifier` también puede ser útil en otros escenarios excepcionales, como cuando no puede acceder al `visitorCode` 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.
</Note>

```java theme={null}
String visitorCode = kameleoonClient.getVisitorCode(httpServletRequest, httpServletResponse);
int goalId = 83023;

kameleoonClient.trackConversion(visitorCode, goalId);

// Add metadata
CustomData cd = new CustomData(1, "metadata");
kameleoonClient.trackConversion(visitorCode, goalId, cd);
```

##### Argumentos

| Nombre                            | Tipo            | Descripción                                                                                                                                                                                                                                                                                                                                                               | Default             |
| --------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| visitorCode (*obligatorio*)       | `String`        | Identificador único del visitante.                                                                                                                                                                                                                                                                                                                                        |                     |
| goalId (*obligatorio*)            | `int`           | ID del objetivo.                                                                                                                                                                                                                                                                                                                                                          |                     |
| revenue (*opcional*)              | `float`         | Ingreso de la conversión.                                                                                                                                                                                                                                                                                                                                                 | `0`                 |
| negative (*opcional*)             | `boolean`       | Define si el ingreso es positivo o negativo.                                                                                                                                                                                                                                                                                                                              | `false`             |
| metadata (*opcional*)             | `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. Example: `[CustomData{id: 5, value: "Payment Type"}, CustomData{id: 6, value: "Delivery Method"}]`. In this example, `5` and `9` are the indexes of the custom data (5 = “Payment Type”, 9 = “Delivery Method”). | `new CustomData[0]` |
| isUniqueIdentifier *(deprecated)* | `boolean`       | Parámetro opcional para indicar si el visitorCode es un identificador único.                                                                                                                                                                                                                                                                                              | `false`             |

<Note>
  metadata values are accessible through [raw data exports](/user-manual/experiment-analytics/analyze-results/results-page/results-page-actions#Export) and [the results page](/user-manual/experiment-analytics/analyze-results/data-and-metrics/goal-metadata).

  Si se proporciona el parámetro `metadata`, Kameleoon utilizará estos valores especificados para la conversión actual en lugar de lo recopilado previamente mediante el método [`addData()`](#adddata). Si se omite el parámetro, Kameleoon utilizará los últimos valores rastreados para esos [`CustomData`](#customdata) antes de la conversión y dentro de la misma visita.

  Kameleoon will only consider the metadata values that are explicitly passed as parameters to the `trackConversion()` method.

  En el siguiente ejemplo, Kameleoon will associate the conversion only with the custom data value explicitly provided as a parameter (here: index 5 with the value 'Amex Credit Card').

  ```java theme={null}
  kameleoonClient.addData(visitorCode, new CustomData(5, "Credit Card"), new CustomData(9, "Express Delivery"));
  kameleoonClient.trackConversion(visitorCode, 1000, new CustomData(5, "Amex Credit Card"));
  ```
</Note>

##### Excepciones

| Tipo                 | Descripción                                                                                                            |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | Excepción que indica que el visitor code proporcionado no es válido. It is either empty or longer than 255 characters. |

#### getEngineTrackingCode()

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

Consulte [experimentación híbrida](/developer-docs/feature-experimentation/get-started/hybrid-experimentation) para más información sobre cómo implementar este método.

```java theme={null}
String engineTrackingCode = kameleoonClient.getEngineTrackingCode(visitorCode);
```

<Note>
  * To use this feature, implement both the Java SDK and Kameleoon [Engine.js](/developer-docs/web-experimentation/implementation-and-deployment/standard-implementation). Because Engine.js is used only for tracking in this flow, you can install the asynchronous tag before the closing `</body>` tag.
  * If you only want to track experiments in Kameleoon and do not need to send exposure events to third-party analytics tools, use the [JavaScript / TypeScript SDK](/developer-docs/sdks/web-sdks/js-sdk). This option works well for [serverless edge compute platforms](/developer-docs/feature-experimentation/implementation-and-deployment/serverless-edge-compute-starter-kits). The JavaScript / TypeScript SDK automatically tracks variations when you call [`getVisitorCode`](/developer-docs/sdks/web-sdks/js-sdk#getvisitorcode), as long as you add the corresponding experiment assignments to `window.kameleoonQueue`..
  * You can insert the returned tracking code directly into an HTML `<script>` tag.

  ```html theme={null}
  <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.
</Note>

##### Argumentos

| Nombre                      | Tipo     | Descripción                        |
| --------------------------- | -------- | ---------------------------------- |
| visitorCode (*obligatorio*) | `String` | Identificador único del visitante. |

##### Valor de retorno

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

### Events

#### setEventHandler()

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

<Tabs>
  <Tab title="DATAFILE_UPDATE">
    ```java theme={null}
    import com.kameleoon.events.DataFileUpdateEvent;
    import com.kameleoon.events.EventType;

    kameleoonClient.setEventHandler(EventType.DATAFILE_UPDATE, event -> {
      DataFileUpdateEvent.Source source = event.getSource(); // POLLING or STREAMING
      long dateModified = event.getDateModified(); // Data file modification date in milliseconds.

      // React to the data file update.
    });

    // Clear the handler.
    kameleoonClient.setEventHandler(EventType.DATAFILE_UPDATE, null);
    ```

    <Tip>
      `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`](/es/developer-docs/feature-experimentation/technical-reference/technical-considerations#polling-predeterminado) indica una actualización programada del archivo de datos, y [`STREAMING`](/es/developer-docs/feature-experimentation/technical-reference/technical-considerations#streaming-opción-premium) indica una actualización en tiempo real recibida mediante el modo streaming. |
      | `dateModified` | `long`                       | La fecha de modificación del archivo de datos actualizado, en milisegundos.                                                                                                                                                                                                                                                                                                                                                         |
    </Tip>
  </Tab>

  <Tab title="HTTP_REQUEST">
    ```java theme={null}
    import com.kameleoon.events.EventType;
    import com.kameleoon.events.HttpRequestFailure;
    import com.kameleoon.events.HttpRequestHandler;
    import com.kameleoon.events.HttpRequestHandler.RequestType;

    kameleoonClient.setEventHandler(EventType.HTTP_REQUEST, new HttpRequestHandler() {
      @Override
      public void onRequestSucceeded(RequestType requestType, int httpStatus, long durationMillis) {
        // The SDK request completed successfully.
      }

      @Override
      public void onRequestFailed(RequestType requestType, HttpRequestFailure failure, long durationMillis) {
        HttpRequestFailure.Reason reason = failure.getReason();
        Integer httpStatus = failure.getHttpStatus();
        Throwable cause = failure.getCause();

        // The SDK request failed.
      }
    });

    // Clear the handler.
    kameleoonClient.setEventHandler(EventType.HTTP_REQUEST, null);
    ```

    <Tip>
      `HttpRequestHandler` le permite reaccionar a las solicitudes HTTP del SDK completadas. El SDK llama a `onRequestSucceeded()` para las respuestas exitosas y a `onRequestFailed()` para las respuestas fallidas, excepciones o solicitudes canceladas.

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

      <Accordion title="Parámetros del callback y detalles del fallo">
        ##### Parámetros del callback

        | Nombre           | Tipo                             | Descripción                                                                                                                           |
        | ---------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
        | `requestType`    | `HttpRequestHandler.RequestType` | El tipo de solicitud del SDK. Los valores posibles son `DATAFILE`, `TRACKING`, `REMOTE_VISITOR_DATA`, `REMOTE_DATA` y `ACCESS_TOKEN`. |
        | `httpStatus`     | `int`                            | El código de estado HTTP devuelto por la solicitud. Solo se pasa a `onRequestSucceeded()`.                                            |
        | `failure`        | `HttpRequestFailure`             | Detalles sobre por qué falló la solicitud. Solo se pasa a `onRequestFailed()`.                                                        |
        | `durationMillis` | `long`                           | 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`.                                                            |
        | `httpStatus` | `Integer`                   | El código de estado HTTP para los fallos causados por una respuesta HTTP no exitosa. Este valor es `null` para fallos por excepción y cancelación. |
        | `cause`      | `Throwable`                 | La excepción que provocó que la solicitud fallara. Este valor es `null` cuando la solicitud falló debido a un estado HTTP o a una cancelación.     |
      </Accordion>
    </Tip>
  </Tab>
</Tabs>

##### Argumentos

| Nombre                      | Tipo                     | Descripción                                                                                                                                                                                                                              |
| --------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eventType` (*obligatorio*) | `EventType<T>`           | El tipo de evento del SDK que se gestionará. Use `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` (*opcional*)      | `T extends EventHandler` | El handler que se registrará para el tipo de evento seleccionado. Use un `DataFileUpdateHandler` para `EventType.DATAFILE_UPDATE`, o un `HttpRequestHandler` para `EventType.HTTP_REQUEST`. Pase `null` para eliminar el handler actual. |

### Tipos de datos

This section lists the data types supported by Kameleoon in `com.kameleoon.Data`. We provide several standard data types as well as the `CustomData` type that allows you to define custom data types.

#### 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                                                                                     |
| -------------------- | -------------- | ----------------------------------------------------------------------------------------------- |
| type (*obligatorio*) | `Browser.Type` | List of browsers: `CHROME`, `INTERNET_EXPLORER`, `FIREFOX`, `SAFARI`, `OPERA`, `OTHER`.         |
| version (*opcional*) | `Float`        | Version of the browser, floating point number represents major and minor version of the browser |

```java theme={null}
kameleoonClient.addData(visitorCode, Browser.chrome());
kameleoonClient.addData(visitorCode, Browser.safari());

kameleoonClient.addData(visitorCode, new Browser(Browser.Type.CHROME, 10.0));
```

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

<Tip>
  * Each visitor can have multiple `Conversion` objects.
  * You can find the `goalId` in the Kameleoon app.
</Tip>

| Nombre                 | Tipo            | Descripción                                  | Default             |
| ---------------------- | --------------- | -------------------------------------------- | ------------------- |
| goalId (*obligatorio*) | `int`           | ID del objetivo.                             |                     |
| revenue (*opcional*)   | `float`         | Revenue of the conversion                    | `0`                 |
| negative (*opcional*)  | `boolean`       | Define si el ingreso es positivo o negativo. | `false`             |
| metadata (*opcional*)  | `CustomData...` | Metadatos de la conversión.                  | `new CustomData[0]` |

```java theme={null}
kameleoonClient.addData(visitorCode, new Conversion(32, 10f));

kameleoonClient.addData(visitorCode, new Conversion(33, null, true));

kameleoonClient.addData(
    visitorCode,
    new Conversion(34, 5f, new CustomData(3, "metadata1", "md2"), new CustomData(5, "md3"))
);
```

#### Cookie

`Cookie` contains information about the cookie stored on the visitor's device.

| Nombre  | Tipo                  | Descripción                                                                                 |
| ------- | --------------------- | ------------------------------------------------------------------------------------------- |
| cookies | `Map<String, String>` | Map de objetos string que consta de claves y valores de cookies. Este campo es obligatorio. |

<Tip>
  Each visitor can only have one `Cookie`. Adding a second `Cookie` overwrites the first one.
</Tip>

```java theme={null}
Cookie cookie = new Cookie (new HashMap<String, String>() {{
    put("my_key1", "my_value1");
    put("my_key2", "my_value1");
}});
kameleoonClient.addData(visitorCode, cookie);
```

#### Geolocation

`Geolocation` contains the visitor's geolocation details.

| Nombre                  | Tipo                  | Descripción                                                                                                      |
| ----------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| country (*obligatorio*) | `String`              | The country of the visitor.                                                                                      |
| region (*opcional*)     | <nobr>`String`</nobr> | The region of the visitor.                                                                                       |
| city (*opcional*)       | <nobr>`String`</nobr> | The city of the visitor.                                                                                         |
| postalCode (*opcional*) | <nobr>`String`</nobr> | The postal code of the visitor.                                                                                  |
| latitude (*opcional*)   | `float`               | The latitude coordinate representing the location of the visitor. Coordinate number represents decimal degrees.  |
| longitude (*opcional*)  | `float`               | The longitude coordinate representing the location of the visitor. Coordinate number represents decimal degrees. |

<Tip>
  * Each visitor can have only one `Geolocation`. Adding a second `Geolocation` overwrites the first one.
</Tip>

```java theme={null}
kameleoonClient.addData(visitorCode, new Geolocation("France", "Île-de-France", "Paris"));
```

#### CustomData

`CustomData` enables the association of any type of data with each visitor, making it an effective tool for targeting conditions in [segments](/user-manual/assets/segments/create-a-segment/). Additionally, it can be used as a filter or breakdown in experiment reports. Para más información sobre los datos personalizados, consulte este [artículo](/developer-docs/custom-data).

Define custom data types in the Kameleoon app or the Data API and use them from the SDK.

| Nombre                     | Tipo                       | Descripción                                                                                                                                                                                          | Default |
| -------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| index/name (*obligatorio*) | `int`/`String`             | Índice o nombre del dato personalizado. **Either `index` or `name` must be provided** to identify the data..                                                                                         |         |
| values (*obligatorio*)     | `String...`/`List<String>` | Values of the custom data to be stored.                                                                                                                                                              |         |
| overwrite (*opcional*)     | `boolean`                  | Flag para controlar explícitamente cómo se almacenan los valores y cómo aparecen en los informes. [See more](/developer-docs/custom-data#default-logic-when-overwrite-parameter-is-false-or-omitted) | `true`  |

<Note>
  * Each visitor is allowed only one `CustomData` for each unique `index`(`name`). Adding another `CustomData` with the same `index`(`name`) will replace the existing one.

  * The custom data ‘index’ can be found in the [Custom Data dashboard](/user-manual/assets/custom-data/manage-custom-data) under the “INDEX” column.

  * To prevent the SDK from sending data with the selected index to Kameleoon servers for privacy reasons, enable the option: **Use this data only locally for targeting purposes** when creating custom data.

  * Adding a `CustomData` instance created with a name when the SDK instance is not initialized or the name is not registered, will result in the data being ignored.
</Note>

```java theme={null}
kameleoonClient.addData(visitorCode, new CustomData(1, "value"));

// With several values
kameleoonClient.addData(visitorCode, new CustomData(1, "value1", "value2"));

// To set the 'overwrite' flag to false
kameleoonClient.addData(visitorCode, new CustomData(1, false, "value"));

// To use a name instead of the index
kameleoonClient.addData(visitorCode, new CustomData("my-custom-data", "value"));
```

#### Device

| Nombre | Tipo     | Descripción                                                               |
| ------ | -------- | ------------------------------------------------------------------------- |
| device | `Device` | List of devices: `PHONE`, `TABLET`, `DESKTOP`. Este campo es obligatorio. |

```java theme={null}
kameleoonClient.addData(visitorCode, Device.desktop());
```

#### PageView

Store page view events.

| Nombre    | Tipo            | Descripción                                              |
| --------- | --------------- | -------------------------------------------------------- |
| url       | `String`        | URL of the page viewed. Este campo es obligatorio.       |
| title     | `String`        | Title of the page viewed. Este campo es obligatorio.     |
| referrers | `List<Integer>` | Referrers de las páginas vistas. Este campo es opcional. |

<Note>
  The referrer's index (ID) is available in the Kameleoon app in the [acquisition channel configuration](/user-manual/assets/advanced-targeting-tools/create-an-acquisition-channel) page. Be careful: this index starts at 0, so the first acquisition channel you create for the specified site would have the ID 0, not 1.
</Note>

```java theme={null}
kameleoonClient.addData(
  visitorCode,
  new PageView("https://url.com", "title", Array.asList(3))
);
```

#### UserAgent

Server-side experiments are more likely to be affected by bot traffic than client-side experiments. Kameleoon uses the IAB/ABC International Spiders and Bots List to tackle this issue and recognize known bots and spiders. Kameleoon also uses the `UserAgent` field to filter out bots and other unwanted traffic that might distort your conversion metrics. Para más detalles, consulte our help article on [bot filtering](/user-manual/faq#how-does-kameleoon-filter-bot-traffic-from-my-results).

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  | `String` | The User-Agent value that will be sent with tracking requests. Este campo es obligatorio. |

```java theme={null}
kameleoonClient.addData(visitorCode, new UserAgent("Your User Agent"));
```

#### UniqueIdentifier

Si no añade `UniqueIdentifier` para un visitante, se utiliza `visitorCode` como identificador único del visitante, lo cual es útil para la [experimentación entre dispositivos](/developer-docs/cross-device-experimentation). Cuando añade `UniqueIdentifier` para un visitante, el SDK vincula los datos vaciados con el visitante asociado al identificador especificado.

`isUniqueIdentifier` puede ser útil en situaciones particulares; por ejemplo, si no puede acceder al `visitorCode` anónimo asignado a un visitante, pero puede usar un ID interno vinculado a ese visitante a través de la fusión de sesiones.

| Nombre | Tipo      | Descripción                                                                                  |
| ------ | --------- | -------------------------------------------------------------------------------------------- |
| value  | `boolean` | Parámetro que indica si el visitorCode es un identificador único. Este campo es obligatorio. |

```java theme={null}
kameleoonClient.addData(visitorCode, new UniqueIdentifier(true));
```

#### OperatingSystem

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

| Nombre | Tipo                   | Descripción                                                                                                             |
| ------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| type   | `OperatingSystem.Type` | List of operating systems: `WINDOWS_PHONE`, `WINDOWS`, `ANDROID`, `LINUX`, `MAC`, and `IOS`. Este campo es obligatorio. |

<Tip>
  Each visitor can only have one `OperatingSystem`. Adding a second `OperatingSystem` overwrites the first one.
</Tip>

```java theme={null}
kameleoonClient.addData(visitorCode, new OperatingSystem(OperatingSystem.Type.WINDOWS));

kameleoonClient.addData(visitorCode, OperatingSystem.mac());
```

#### ApplicationVersion

`ApplicationVersion` represents the semantic version number of your application.

<Tip>
  A **visitor** can have only one `ApplicationVersion`. Adding a second instance will overwrite the first one.
</Tip>

| Nombre               | Tipo     | Descripción                                                                                                                                      |
| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| version (*opcional*) | `String` | The mobile application version. This field must follow semantic versioning. Accepted formats are `major`, `major.minor`, or `major.minor.patch`. |

```java theme={null}
kameleoonClient.addData(visitorCode, new ApplicationVersion("10")); // major

kameleoonClient.addData(visitorCode, new ApplicationVersion("10.20")); // major.minor

kameleoonClient.addData(visitorCode, new ApplicationVersion("10.20.30")); // major.minor.patch
```

### Returned Types

#### DataFile

El `DataFile` contiene los detalles de configuración del SDK.

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

| Nombre       | Tipo                       | Descripción                                                                       |
| ------------ | -------------------------- | --------------------------------------------------------------------------------- |
| featureFlags | `Map<String, FeatureFlag>` | A map of [`FeatureFlag`](#featureflag) objects, keyed by feature flag keys.       |
| dateModified | `long`                     | The timestamp (in milliseconds) indicating when the `DataFile` was last modified. |

```java theme={null}
// Retrieves the map of feature flags from the DataFile.
// The map is keyed by feature flag identifiers, with each value being a FeatureFlag object.
Map<String, FeatureFlag> featureFlags = dataFile.getFeatureFlags();

// Retrieves the last modification timestamp of the DataFile.
// The value is a long representing milliseconds since the Unix epoch.
long dateModified = dataFile.getDateModified();
```

#### FeatureFlag

`FeatureFlag` representa un conjunto de propiedades que definen un feature flag en sí — por ejemplo, sus [`Variations`](#variation), [`Rules`](#rule), estado del entorno y otros detalles relacionados.

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

| Nombre              | Tipo                     | Descripción                                                        |
| ------------------- | ------------------------ | ------------------------------------------------------------------ |
| environmentEnabled  | `boolean`                | Indica si el feature flag está habilitado en el entorno actual.    |
| defaultVariationKey | `String`                 | The key of the default variation associated with the feature flag. |
| variations          | `Map<String, Variation>` | A map of `Variation` objects, keyed by variation keys.             |
| rules               | `List<Rule>`             | A list of `Rule` objects                                           |

```java theme={null}
// Check whether the feature flag is enabled in the current environment
boolean isEnvironmentEnabled = featureFlag.isEnvironmentEnabled();

// Retrieve the key of the default variation
String defaultVariationKey = featureFlag.getDefaultVariationKey();

// Retrieve the default variation object
Variation defaultVariation = featureFlag.getDefaultVariation();

// Retrieve all variations of the feature flag as a map (key = variation key, value = Variation object)
Map<String, Variation> variations = featureFlag.getVariations();

// Retrieve all targeting rules associated with the feature flag
List<Rule> rules = featureFlag.getRules();
```

#### Rule

`Rule` representa un conjunto de propiedades que definen una regla en sí — por ejemplo, sus [`Variations`](#variation).

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

| Nombre     | Tipo                     | Descripción                                            |
| ---------- | ------------------------ | ------------------------------------------------------ |
| variations | `Map<String, Variation>` | A map of `Variation` objects, keyed by variation keys. |

```java theme={null}
// Retrieve all variations of the rule as a map (key = variation key, value = Variation object)
Map<String, Variation> variations = rule.getVariations();
```

#### Variation

`Variation` contains information about the visitor's assigned variation (or the default variation, if no specific assignment exists).

| Nombre       | Tipo                    | Descripción                                                                                                                                          |
| ------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| name         | `String`                | The name of the variation.                                                                                                                           |
| key          | `String`                | The unique key identifying the variation.                                                                                                            |
| id           | `Integer`               | The ID of the assigned variation (or `null` if it's the default variation).                                                                          |
| experimentId | `Integer`               | The ID of the experiment associated with the variation (or `null` if default).                                                                       |
| variables    | `Map<String, Variable>` | A map containing the variables of the assigned variation, keyed by variable names. This could be an empty collection if no variables are associated. |

<Note>
  * The `Variation` object provides details about the assigned variation and its associated experiment, while the [`Variable`](#variable) object contains specific details about each variable within a variation.
  * Ensure that your code handles the case where `id` or `experimentId` may be `null`, indicating a default variation.
  * The `variables` map might be empty if no variables are associated with the variation.
</Note>

```java theme={null}
// Retrieving the variation name
String variationName = variation.getName();

// Retrieving the variation key
String variationKey = variation.getKey();

// Retrieving the variation id
Integer variationId = variation.getId();

// Retrieving the experiment id
Integer experimentId = variation.getExperimentId();

// Retrieving the variables map
Map<String, Variable> variables = variation.getVariables();
```

#### Variable

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

| Nombre | Tipo     | Descripción                                                                                                                                                |
| ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key    | `String` | The unique key identifying the variable.                                                                                                                   |
| type   | `String` | The type of the variable. Possible values: **BOOLEAN**, **NUMBER**, **STRING**, **JSON**, **JS**, **CSS**.                                                 |
| value  | `Object` | The value of the variable, which can be of the following types: **Boolean**, **Integer**, **Long**, **Double**, **String**, **JsonObject**, **JsonArray**. |

```java theme={null}
// Retrieving the variables map
Map<String, Variable> variables = variation.getVariables();

// Variable type can be retrieved for further processing
String type = variables.get("isDiscount").getType();

// Retrieving the variable value by key
Boolean isDiscount = (Boolean) variables.get("isDiscount").getValue();

// Variable value can be of different types
String title = (String) variables.get("title").getValue();
```

### Deprecated methods

<Warning>
  Estos métodos están obsoletos y se eliminarán en la versión `5.0.0` del SDK.
</Warning>

#### getFeatureVariationKey()

* *📨 Envía datos de seguimiento a Kameleoon*

<Note>
  Use [`getVariation()`](#getvariation) instead.
</Note>

Llame a este método para obtener la clave de variación de funcionalidad para un usuario y una funcionalidad especificados. Este método toma un `visitorCode` y un `featureKey` como argumentos obligatorios para obtener la clave de variación para el usuario y la funcionalidad.

Si el usuario nunca ha sido asociado con este feature flag, el SDK devuelve una clave de variación asignada aleatoriamente (según las reglas del feature flag). Si un usuario con el `visitorCode` especificado ya está registrado en este feature flag, el SDK detecta el valor anterior de la clave de variación. Si el usuario no coincide con ninguna de las reglas, se devuelve el valor predeterminado, que puede personalizar en la aplicación de Kameleoon.

Asegúrese de capturar y gestionar las posibles excepciones.

Si especifica un `visitorCode`, el método `flush()` lo usa como identificador único del visitante, lo cual es útil para la [experimentación entre dispositivos](/developer-docs/cross-device-experimentation). Cuando especifica un `visitorCode` y establece el parámetro `isUniqueIdentifier` en `true`, el SDK vincula los datos vaciados con el visitante asociado al identificador especificado.

<Note>
  El parámetro `isUniqueIdentifier` está obsoleto. Utilice en su lugar [`UniqueIdentifier`](#uniqueidentifier).

  `isUniqueIdentifier` puede ser útil en situaciones particulares; por ejemplo, si no puede acceder al `visitorCode` anónimo asignado a un visitante, pero puede usar un ID interno vinculado a ese visitante a través de la fusión de sesiones.
</Note>

```java theme={null}
String visitorCode = kameleoonClient.getVisitorCode(httpServletRequest, httpServletResponse);
String featureKey = "new_checkout";
String variationKey = ""

try {
  variationKey = kameleoonClient.GetFeatureVariationKey(visitorCode, featureKey);
} catch (KameleoonException.FeatureNotFound e) {
  // The error has occurred; the feature flag isn't found in the current configuration
} catch (KameleoonException.FeatureEnvironmentDisabled e) {
  // The feature flag is disabled for the environment
} catch (KameleoonException.VisitorCodeInvalid e) {
  // The visitor code you passed to the method is invalid and can't be accepted by SDK.
}

switch (variationKey) {
  case 'on':
    // Main variation key is selected for visitorCode
    break;
  case 'alternative_variation':
    // Alternative variation key
    break;
  default:
    // Default variation key
    break;
}
```

##### Argumentos

| Nombre                        | Tipo      | Descripción                                                                                                                                              |
| ----------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitorCode                   | `String`  | Identificador único del usuario. Este campo es obligatorio.                                                                                              |
| featureKey                    | `String`  | Clave de la funcionalidad que desea exponer a un usuario. Este campo es obligatorio.                                                                     |
| isUniqueIdentifier (Obsoleto) | `boolean` | Parámetro opcional para indicar si el visitorCode es un identificador único. If not provided, el valor predeterminado es `false`. The field is optional. |

##### Valor de retorno

| Tipo     | Descripción                                                                           |
| -------- | ------------------------------------------------------------------------------------- |
| `String` | Variation key of the feature flag that is registered for the specified `visitorCode`. |

##### Excepciones lanzadas

| Tipo                                          | Descripción                                                                                                                                                                                                                                                                                                |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| KameleoonException.FeatureNotFound            | Excepción que indica que la clave de funcionalidad solicitada no se encontró en la configuración interna del SDK. Esta excepción 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 su aplicación). |
| KameleoonException.FeatureEnvironmentDisabled | Excepción que indica que el feature flag está deshabilitado para el entorno actual del visitante (por ejemplo, production, staging o development).                                                                                                                                                         |
| KameleoonException.VisitorCodeInvalid         | Excepción que indica que el visitor code proporcionado no es válido. It is empty or longer than 255 characters.                                                                                                                                                                                            |

#### getActiveFeatures()

<Note>
  Use [`getVariations()`](#getvariations) instead.
</Note>

Este método toma un single **visitorCode** parameter. Result contains only active features for a given visitor.

```java theme={null}
try {
    Map<String, Variation> activeFeatures = kameleoonClient.getActiveFeatures(visitorCode);
} catch (VisitorCodeInvalid e) {
    //  Handle exception
}
```

##### Argumentos

| Nombre      | Tipo   | Descripción                                                 |
| ----------- | ------ | ----------------------------------------------------------- |
| visitorCode | String | Identificador único del usuario. Este campo es obligatorio. |

##### Valor de retorno

| Tipo                     | Descripción                                                                                                                                      |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Map<String, Variation>` | Map que contiene las variaciones asignadas de las funcionalidades activas utilizando las claves de las funcionalidades activas correspondientes. |

##### Excepciones lanzadas

| Tipo               | Descripción                                                                                                            |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| VisitorCodeInvalid | Excepción que indica que el visitor code proporcionado no es válido. It is either empty or longer than 255 characters. |

#### getActiveFeatureListForVisitorCode()

<Note>
  * Use [`getVariations()`](#getvariations) instead.
  * This method was previously called `obtainFeatureListForVisitorCode`, which was removed in SDK version `4.0.0`.
</Note>

Este método toma un single `visitorCode` parameter. Return only the active feature flags for the specified visitor.

```java theme={null}
List<String> listActiveFeatureFlags = kameleoonClient.getActiveFeatureListForVisitorCode(visitorCode);
```

##### Argumentos

| Nombre      | Tipo     | Descripción                                                 |
| ----------- | -------- | ----------------------------------------------------------- |
| visitorCode | `String` | Identificador único del usuario. Este campo es obligatorio. |

##### Valor de retorno

| Tipo           | Descripción                                                           |
| -------------- | --------------------------------------------------------------------- |
| `List<String>` | List of active feature flag keys available for specific `visitorCode` |

#### getFeatureVariable()

* *📨 Envía datos de seguimiento a Kameleoon*

<Note>
  Use [`getVariation()`](#getvariation) instead.
</Note>

Llame a este método para obtener el valor de la variación de funcionalidad asociado a un usuario. Este método toma un `visitorCode`, `featureKey` y `variableKey` como argumentos obligatorios para obtener la variable de la clave de variación para el usuario especificado.

Si un usuario nunca ha sido asociado con este feature flag, el SDK devuelve un valor de variable asignado aleatoriamente para la clave de variación según las reglas del feature flag. Si un usuario con el `visitorCode` especificado ya está registrado en este feature flag, el SDK devuelve el valor de la variable para la variación previamente asociada. Si el usuario no coincide con ninguna de las reglas, se devuelve la variable predeterminada.

Asegúrese de capturar y gestionar las posibles excepciones.

Si especifica un `visitorCode`, el método `getFeatureVariable()` usa el código como identificador único del visitante, lo cual es útil para la [experimentación entre dispositivos](/developer-docs/cross-device-experimentation). Cuando especifica un `visitorCode` y establece el parámetro `isUniqueIdentifier` en `true`, el SDK vincula los datos vaciados con el visitante asociado al identificador especificado.

<Note>
  El parámetro `isUniqueIdentifier` está obsoleto. Utilice en su lugar [`UniqueIdentifier`](#uniqueidentifier).

  `isUniqueIdentifier` puede ser útil en situaciones particulares; por ejemplo, si no puede acceder al `visitorCode` anónimo asignado a un visitante, pero puede usar un ID interno vinculado a ese visitante a través de la fusión de sesiones.
</Note>

```java theme={null}
String visitorCode = kameleoonClient.getVisitorCode(httpServletRequest, httpServletResponse);
String featureKey = "feature_key";
String variableKey = "var"

try {
  var variableValue = kameleoonClient.getFeatureVariable(visitorCode, featureKey, variableKey);
  // Your custom code, depending on variableValue.
} catch (KameleoonException.FeatureNotFound e) {
  // The error has occurred; the feature flag isn't found in current configuration
} catch (KameleoonException.FeatureEnvironmentDisabled e) {
  // The feature flag is disabled for the environment.
} catch (KameleoonException.FeatureVariableNotFound e) {
  // Requested variable not defined on Kameleoon's side
} catch (KameleoonException.VisitorCodeInvalid e) {
  // The visitor code passed to the method is invalid and can't be accepted by SDK.
}
```

##### Argumentos

| Nombre                        | Tipo      | Descripción                                                                                                                                              |
| ----------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitorCode                   | `String`  | Identificador único del usuario. Este campo es obligatorio.                                                                                              |
| featureKey                    | `String`  | Clave de la funcionalidad que desea exponer a un usuario. Este campo es obligatorio.                                                                     |
| variableKey                   | `String`  | Nombre de la variable cuyo valor desea obtener. Este campo es obligatorio.                                                                               |
| isUniqueIdentifier (Obsoleto) | `boolean` | Parámetro opcional para indicar si el visitorCode es un identificador único. If not provided, el valor predeterminado es `false`. The field is optional. |

##### Valor de retorno

| Tipo   | Descripción                                                                                                                                                                     |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| object | Value of variable of variation that is registered for the specified `visitorCode` for this feature flag. Possible types: `bool`, `int`, `double`, `string`, `JObject`, `JArray` |

##### Excepciones lanzadas

| Tipo                                          | Descripción                                                                                                                                                                                                                                                                                           |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| KameleoonException.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 aún no se ha activado en la aplicación de Kameleoon (pero el código que implementa la funcionalidad ya está desplegado en su aplicación). |
| KameleoonException.FeatureEnvironmentDisabled | Excepción que indica que el feature flag está deshabilitado para el entorno actual del visitante (por ejemplo, production, staging o development).                                                                                                                                                    |
| KameleoonException.FeatureVariableNotFound    | Excepción que indica que la variable solicitada no se encontró. Compruebe que la clave de la variable en la aplicación de Kameleoon coincida con la de su código.                                                                                                                                     |
| KameleoonException.VisitorCodeInvalid         | Excepción que indica que el visitor code especificado no es válido. (Está vacío o tiene más de 255 caracteres).                                                                                                                                                                                       |

#### getFeatureVariables()

* *📨 Envía datos de seguimiento a Kameleoon*

<Note>
  Use [`getVariation()`](#getvariation) instead.
</Note>

Este método recupera a map containing variable keys and their values assigned according the variation that the visitor is assigned in the specified feature flag. Feature variables can be modified in the Kameleoon app.

If a user has never been associated with this feature flag, the SDK returns a randomly assigned set of variable values in the variation according to the feature flag rules. If a user with the specified `visitorCode` is already registered with this feature flag, the SDK returns the variable values for the variation used previously. If the user does not match any of the rules, the default variables are returned.

Asegúrese de capturar y gestionar las posibles excepciones.

```java theme={null}
String visitorCode = kameleoonClient.getVisitorCode(httpServletRequest, httpServletResponse);
String featureKey = "feature_key";
String variableKey = "var"

try {
  var variableValue = kameleoonClient.getFeatureVariables(visitorCode, featureKey);
  // Your custom code, depending on variable values.
} catch (KameleoonException.FeatureNotFound e) {
  // The error has occurred; the feature flag isn't found in current configuration.
} catch (KameleoonException.FeatureEnvironmentDisabled e) {
  // The feature flag is disabled for the environment.
} catch (KameleoonException.FeatureVariableNotFound e) {
  // Requested variable not defined on Kameleoon's side
} catch (KameleoonException.VisitorCodeInvalid e) {
  // The visitor code passed to the method is invalid and can't be accepted by SDK.
}
```

##### Argumentos

| Nombre       | Tipo     | Descripción                                                             |
| ------------ | -------- | ----------------------------------------------------------------------- |
| featureKey   | `String` | Clave de la funcionalidad que desea obtener. Este campo es obligatorio. |
| variationKey | `String` | Clave de la variación que desea obtener. Este campo es obligatorio.     |

##### Valor de retorno

| Tipo                 | Descripción                                                                                                                                                                 |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Map<String,Object>` | Datos asociados con este feature flag. The values can be `Boolean`, `Integer`, `Double`, `String`, `JsonObject`, or `JsonArray` (the type is defined in the Kameleoon app). |

##### Excepciones lanzadas

| Tipo                                          | Descripción                                                                                                                                                                                                                                                                                                 |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| KameleoonException.FeatureNotFound            | Excepción que indica que la clave de funcionalidad solicitada no se encontró en la configuración interna del SDK. Esta excepción suele significar que el feature flag no se ha activado en la aplicación de Kameleoon (pero el código que implementa la funcionalidad ya está desplegado en su aplicación). |
| KameleoonException.FeatureEnvironmentDisabled | Excepción que indica que el feature flag está deshabilitado para el entorno actual del visitante (por ejemplo, production, staging o development).                                                                                                                                                          |
| KameleoonException.FeatureVariationNotFound   | Excepción que indica que la clave de variación solicitada no se encontró en la configuración interna del SDK. Esto suele significar que el experimento correspondiente a la variación no está activado en la aplicación de Kameleoon.                                                                       |
| KameleoonException.VisitorCodeInvalid         | Excepción que indica que el visitor code especificado no es válido. (Está vacío o tiene más de 255 caracteres).                                                                                                                                                                                             |

#### getFeatureVariationVariables()

<Note>
  * Use  [`getVariation()`](#getvariation) instead.
  * This method was previously called `getFeatureAllVariables`, which was removed in SDK version `4.0.0`.
</Note>

Llame a este método para recuperar todas las variables de funcionalidad de una funcionalidad. Puede modificar las variables de funcionalidad en la aplicación Kameleoon.

Este método toma two input parameters: `featureKey` and `variationKey`. It returns the data with the `Map<String, Object>` type as defined in the Kameleoon app. It throws an exception (`KameleoonException.FeatureNotFound`) if the feature you request isn't found in the SDK's internal configuration.

```java theme={null}
String featureKey = "featureKey";
String variationKey = "variationKey";

try {
  Map<String, Object> allVariables = kameleoonClient.getFeatureVariationVariables(featureKey, variationKey);
} catch (KameleoonException.FeatureNotFound e) {
  // The feature is not activated in the Kameleoon app.
} catch (KameleoonException.FeatureEnvironmentDisabled e) {
  // The feature flag is disabled for the environment.
} catch (KameleoonException.FeatureVariationNotFound e) {
  // The variation is not activated in the Kameleoon app (most likely, the associated experiment is not active)
} catch (Exception e) {
  // This is a generic Exception handler which will handle all exceptions.
  System.out.println("Exception occurred");
}
```

##### Argumentos

| Nombre       | Tipo   | Descripción                                                             |
| ------------ | ------ | ----------------------------------------------------------------------- |
| featureKey   | String | Clave de la funcionalidad que desea obtener. Este campo es obligatorio. |
| variationKey | String | Clave de la variación que desea obtener. Este campo es obligatorio.     |

##### Valor de retorno

| Tipo                 | Descripción                                                                                                                                                                        |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Map<String,Object>` | Datos asociados con este feature flag. The values can be `Boolean`, `Integer`, `Double`, `String`, `JsonObject`, `JsonArray` (depending on the type defined in the Kameleoon app). |

##### Excepciones lanzadas

| Tipo                                          | Descripción                                                                                                                                                                                                                           |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| KameleoonException.FeatureNotFound            | Excepción que indica que la funcionalidad solicitada no se encontró en la configuración interna del SDK. Esta excepción suele significar que el feature flag no está activado en la aplicación de Kameleoon.                          |
| KameleoonException.FeatureEnvironmentDisabled | Excepción que indica que el feature flag está deshabilitado para el entorno actual del visitante (por ejemplo, production, staging o development).                                                                                    |
| KameleoonException.FeatureVariationNotFound   | Excepción que indica que la clave de variación solicitada no se encontró en la configuración interna del SDK. Esto suele significar que el experimento correspondiente a la variación no está activado en la aplicación de Kameleoon. |