Biblioteca JS - Kleep Docs

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)

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

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.

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. Cópialo desde allí.

2. Instalación

Para comenzar, incluye el archivo JavaScript del widget en tu proyecto. Antes de </body>, añade:

<script src="https://module.kleep.ai/api/widget"></script>

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:

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

3. Métodos

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

Inicializa el widget con kleep.load:

<script>kleep.load({ /* ...params */ })</script>

Añade un contenedor donde el widget debe mostrarse en la página de producto:
```
<div id="kleep-container"></div>
```

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

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

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

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").

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

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

Ejemplo

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

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

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

`variantId`	Talla
`a`	34
`b`	36
`c`	38
`d`	40
`e`	42

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`

kleep.track("product_viewed", {
  productId: "123ABC456"
})

`product_added_to_cart`

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`

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.

​1. Consentimiento de cookies (requisito legal)

​2. Instalación

​3. Métodos

​3.1. kleep.load — Mostrar el CTA de Kleep

​Parámetros

​Ejemplo

​3.2. kleep.createButton — Recrear el CTA de Kleep

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

​product_viewed

​product_added_to_cart

​checkout_completed

​3.4. kleep.getTrackingId — Obtener el ID interno de Kleep

​Cookies y privacidad de datos

1. Consentimiento de cookies (requisito legal)

2. Instalación

3. Métodos

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

Parámetros

Ejemplo

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

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

`product_viewed`

`product_added_to_cart`

`checkout_completed`

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

Cookies y privacidad de datos