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

# Biblioteca JS

> Instala y configura el widget de Kleep AI Sizing en cualquier tienda mediante nuestra biblioteca JavaScript.

Esta guía cubre la instalación del widget de Kleep AI Sizing en cualquier tienda usando nuestra biblioteca JavaScript. Úsala junto con la guía de integración backend específica de la plataforma (Prestashop, Magento, WooCommerce, WShop, etc.) — esa se encarga de la ingestión de datos, mientras que esta guía gestiona el CTA de frontend en tus páginas de producto.

## 1. Consentimiento de cookies (requisito legal)

<Warning>
  Cargar Kleep procesa datos personales mediante cookies y tecnologías similares. Por lo tanto, debes **condicionar legalmente la carga de Kleep al consentimiento previo del visitante con las cookies** — no llames a `kleep.load` (ni cargues la biblioteca) hasta que el visitante haya aceptado las cookies relevantes en tu Plataforma de Gestión del Consentimiento (CMP).
</Warning>

<Note>
  Concretamente: condiciona la etiqueta `<script src="https://module.kleep.ai/api/widget">` y la llamada a `kleep.load(...)` al callback de consentimiento de tu CMP, de modo que solo se ejecuten después de que se haya otorgado el consentimiento para ambas finalidades. Si el consentimiento se retira posteriormente, deja de cargar Kleep en las vistas de página siguientes.
</Note>

Tu CMP debe exponer dos finalidades de tratamiento, y Kleep solo puede cargarse una vez que el visitante haya dado su consentimiento a ambas. El texto exacto a mostrar en tu banner — en 15 idiomas — se encuentra en la página [Cookies, CMP y privacidad de datos](/es/cookie-consent). Cópialo desde allí.

## 2. Instalación

Para comenzar, incluye el archivo JavaScript del widget en tu proyecto.

Antes de `</body>`, añade:

```html theme={null}
<script src="https://module.kleep.ai/api/widget"></script>
```

<Tip>
  **Ver los registros durante la integración.** Por defecto el widget funciona en silencio. Para imprimir los registros completos de `[KLEEP] [Widget]` (flujo de carga, parámetros, creación del CTA, etc.) en la consola de tu navegador, añade `?debug=true` a la URL de la biblioteca:

  ```html theme={null}
  <script src="https://module.kleep.ai/api/widget?debug=true"></script>
  ```

  Este indicador en la URL es la única forma de habilitar los registros detallados — no existe una opción `debug` en `kleep.load(...)`. Las advertencias críticas (idioma/mercado `lang`/`market` no admitido, discrepancia `product_id`/`selectors`, llamar a `kleep.load` dos veces) se muestran **siempre**, incluso sin este indicador. Elimina `?debug=true` en producción.
</Tip>

## 3. Métodos

### 3.1. `kleep.load` — Mostrar el CTA de Kleep

1. Inicializa el widget con `kleep.load`:

   ```html theme={null}
   <script>kleep.load({ /* ...params */ })</script>
   ```

2. Añade un contenedor donde el widget debe mostrarse en la página de producto:

   ```html theme={null}
   <div id="kleep-container"></div>
   ```

<Note>
  Este div se usa para insertar nuestro botón dentro. Dejamos el estilo CSS del botón a tu cargo durante la implementación.
</Note>

#### Parámetros

`kleep.load` debe llamarse en cada página de producto (PDP) para cargar el CTA de Kleep, con los siguientes parámetros:

| Parámetro          | Tipo            | Descripción                                                                                                                                                                                                                       | Prioridad                                          |
| ------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `public_id`        | UUID            | El UUID proporcionado durante el proceso de incorporación                                                                                                                                                                         | **obligatorio**                                    |
| `product_id`       | string \| array | ID(s) de producto de la PDP en la que se llama a `kleep.load`. Una cadena única se aplica a todos los selectores; un array debe coincidir con `selectors.sizing` (ver advertencia a continuación).                                | **obligatorio**                                    |
| `customer_id`      | string          | ID del cliente conectado (debe coincidir con lo enviado mediante transferencias de datos)                                                                                                                                         | opcional                                           |
| `lang`             | string          | Idioma actual de la página. Sigue [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes). Predeterminado: `fr`. Consulta la lista de idiomas admitidos a continuación.                                         | **obligatorio**                                    |
| `market`           | string          | Código de país (ubicación del visitante del sitio web). Sigue [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). Predeterminado: `null`. Consulta la lista de mercados admitidos a continuación. | opcional                                           |
| `selectors.sizing` | array           | Selectores HTML del/los contenedor(es) del botón de tallas. Pasa múltiples para añadir varios CTA en la misma PDP.                                                                                                                | **obligatorio**                                    |
| `getSizes`         | async function  | Devuelve las tallas disponibles como un array de `{ variantId, quantity }` para que el widget pueda verificar si las tallas recomendadas están en stock.                                                                          | obligatorio para ese uso, de lo contrario opcional |
| `addToCart`        | async function  | Recibe un `variantId` como entrada y añade la variante de producto correspondiente al carrito.                                                                                                                                    | obligatorio para ese uso, de lo contrario opcional |
| `selectSize`       | async function  | Recibe un `variantId` como entrada y selecciona la variante correspondiente en la interfaz de tu tienda (permite al cliente saltarse un clic).                                                                                    | obligatorio para ese uso, de lo contrario opcional |

<Note>
  Si `lang` o `market` no siguen sus respectivas convenciones o no son admitidos, verás un aviso en la consola.
</Note>

<Warning>
  **Correspondencia entre `product_id` y `selectors.sizing`.** Estos dos controlan qué producto se muestra en qué contenedor, por lo que deben estar alineados:

  * **Un producto en uno o varios contenedores** → pasa `product_id` como una **cadena única**. El mismo producto se aplica a todos los selectores en `selectors.sizing`.
  * **Productos diferentes, uno por contenedor** → pasa `product_id` como un **array con la misma longitud que `selectors.sizing`**. Se emparejan por índice, por lo que el orden debe coincidir (`product_id[0]` → `selectors.sizing[0]`, y así sucesivamente).

  Si `product_id` es un array cuya longitud es **diferente** de `selectors.sizing`, **no se renderiza ningún CTA** y se registra un aviso en la consola (imprime ambas longitudes y valores). Por ejemplo, `product_id: ["sku-1"]` (1 elemento) con dos selectores falla silenciosamente — corrígelo repitiendo el id (`["sku-1", "sku-1"]`) o pasándolo como cadena (`"sku-1"`).
</Warning>

<Accordion title="Idiomas admitidos (ISO 639-1)">
  Si el idioma que necesitas no está en la lista a continuación, contacta con tu representante de Kleep.

  * `fr` — Francés (predeterminado)
  * `br` — Portugués brasileño
  * `da` — Danés
  * `de` — Alemán
  * `en` — Inglés
  * `es` — Español
  * `fi` — Finlandés
  * `it` — Italiano
  * `ja` — Japonés
  * `ko` — Coreano
  * `nl` — Neerlandés
  * `pl` — Polaco
  * `pt` — Portugués
  * `sv` — Sueco
  * `zh` — Chino
</Accordion>

<Accordion title="Mercados admitidos (ISO 3166-1 alpha-2)">
  AF, AX, AL, DZ, AD, AO, AI, AG, AR, AM, AW, AC, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CA, CV, BQ, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, HR, CU, CW, CY, CZ, CI, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, SZ, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KP, XK, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MG, MW, MY, MV, ML, MT, MQ, MR, MU, YT, MX, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, MK, NO, OM, PK, PS, PA, PG, PY, PE, PH, PN, PL, PT, QA, CM, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, KR, SS, ES, LK, VC, SD, SR, SJ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TA, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, WF, EH, YE, ZM, ZW, ZZ
</Accordion>

#### Ejemplo

```javascript theme={null}
kleep.load({
  public_id: "UUID",
  product_id: ["id_1", "id_2"],
  customer_id: "customer_test",
  lang: "fr-FR",
  market: "EU",
  selectors: {
    sizing: ["#kleep-container-1", "#kleep-container-2"]
  },
  getSizes: async () => {
    return [
      { variantId: "variant-XYZ-XS", quantity: true },
      { variantId: "variant-XYZ-S", quantity: true },
      { variantId: "variant-XYZ-M", quantity: false },
      { variantId: "variant-XYZ-L", quantity: false },
      { variantId: "variant-XYZ-XL", quantity: true },
    ]
  },
  addToCart: async variantId => {
    document.querySelector(".sizes").value = variantId
    document.querySelector(".addToCart").click()
  },
  selectSize: async variantId => {
    document.querySelector(".sizes").value = variantId
  }
})
```

<Tip>
  Durante la implementación, puedes usar esta configuración de prueba:

  * `public_id`: `"aadb1934-6e16-4c8a-a7cb-1fd6e00dd02c"`
  * `product_id`: `"12345"`
  * `variantId`s a usar para los callbacks (con su etiqueta de talla correspondiente):

  | `variantId` | Talla |
  | ----------- | ----- |
  | `a`         | 34    |
  | `b`         | 36    |
  | `c`         | 38    |
  | `d`         | 40    |
  | `e`         | 42    |
</Tip>

### 3.2. `kleep.createButton` — Recrear el CTA de Kleep

En algunos casos tu sitio web puede reconstruir componentes o recargar variables de estado, haciendo que el CTA de Kleep desaparezca. Llama a `kleep.createButton` para que vuelva a aparecer.

No se necesita ningún parámetro — reutiliza la información que proporcionaste al llamar a `kleep.load`, así que asegúrate de que `kleep.load` se ejecutó primero.

### 3.3. `kleep.track` — Habilitar el seguimiento y acceso al panel

Además de la funcionalidad de tallas, añadimos seguimiento para que puedas medir el rendimiento de la solución en tu sitio web. Usa `kleep.track(event_type, event_info)` para enviar información cada vez que ocurra un evento rastreado.

Rastreamos tres eventos:

| Tipo de evento          | Disparador                                       | Prioridad     |
| ----------------------- | ------------------------------------------------ | ------------- |
| `product_viewed`        | Al visualizar la PDP                             | `obligatorio` |
| `product_added_to_cart` | Al añadir producto al carrito                    | `obligatorio` |
| `checkout_completed`    | Tras la confirmación del pedido después del pago | `obligatorio` |

#### `product_viewed`

```javascript theme={null}
kleep.track("product_viewed", {
  productId: "123ABC456"
})
```

#### `product_added_to_cart`

```javascript theme={null}
kleep.track("product_added_to_cart", {
  productId: "123ABC456",
  variantId: "123ABC456-00R",
  cart: [
    {
      productId: "123ABC456",
      variantId: "123ABC456-00R",
      sku: "XYZ",
      size: "S",
      quantity: 2,
      price: {
        amount: "50",
        currencyCode: "EUR"
      }
    },
    {
      productId: "123ABC456",
      variantId: "123ABC456-00R",
      sku: "XYZ",
      size: "S",
      quantity: 1,
      price: {
        amount: "40",
        currencyCode: "USD"
      }
    }
    // ...
  ],
})
```

#### `checkout_completed`

```javascript theme={null}
kleep.track("checkout_completed", {
  orderId: "000001",
  cart: [
    {
      lineItemId: "000001#1",
      productId: "123ABC456",
      variantId: "123ABC456-00R",
      sku: "XYZ",
      size: "S",
      quantity: 2,
      price: {
        amount: "50",
        currencyCode: "EUR"
      }
    },
    {
      lineItemId: "000000#2",
      productId: "123ABC456",
      variantId: "123ABC456-00R",
      sku: "XYZ",
      size: "S",
      quantity: 1,
      price: {
        amount: "40",
        currencyCode: "USD"
      }
    }
    // ...
  ],
})
```

### 3.4. `kleep.getTrackingId` — Obtener el ID interno de Kleep

Para casos de uso personalizados, puedes recuperar uno de los IDs internos de Kleep del visitante.

Devuelve:

* `null` — si el visitante no ha usado Kleep, o
* un UUID — si el visitante tiene un ID de seguimiento de Kleep

***

## Cookies y privacidad de datos

Kleep está completamente condicionado por el consentimiento del visitante: el script solo se carga **después** de que se recopile el consentimiento a través de tu CMP, y debes condicionar su carga en consecuencia. Para la lista completa de rastreadores, los datos tratados, las finalidades y bases legales, el alojamiento, los subencargados y la seguridad, consulta [Cookies, CMP y privacidad de datos](/es/cookie-consent).