Libreria JS - Kleep Docs

Questa guida illustra come installare il widget Kleep AI Sizing su qualsiasi vetrina utilizzando la nostra libreria JavaScript. Usala insieme alla guida di integrazione backend specifica per la piattaforma (Prestashop, Magento, WooCommerce, WShop, ecc.) — quella gestisce l’acquisizione dei dati, mentre questa guida gestisce il CTA frontend nelle tue pagine prodotto.

Il caricamento di Kleep tratta dati personali tramite cookie e tecnologie simili. Devi quindi condizionare legalmente il caricamento di Kleep al previo consenso del visitatore ai cookie — non chiamare kleep.load (né caricare la libreria) finché il visitatore non ha accettato i cookie pertinenti nella tua Piattaforma di Gestione del Consenso (CMP).

In concreto: subordina il tag <script src="https://module.kleep.ai/api/widget"> e la chiamata kleep.load(...) al callback di consenso della tua CMP, in modo che vengano eseguiti solo dopo che il consenso è stato accordato per entrambe le finalità. Se il consenso viene successivamente ritirato, smetti di caricare Kleep nelle visualizzazioni di pagina successive.

La tua CMP deve esporre due finalità di trattamento, e Kleep può essere caricato solo dopo che il visitatore ha prestato il consenso a entrambe. La formulazione esatta da visualizzare nel tuo banner — in 15 lingue — è disponibile nella pagina Cookie, CMP e Privacy dei Dati. Copiali da lì.

2. Installazione

Per iniziare, includi il file JavaScript del widget nel tuo progetto. Prima di </body>, aggiungi:

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

Visualizzare i log durante l’integrazione. Di default il widget funziona silenziosamente. Per visualizzare i log completi [KLEEP] [Widget] (flusso di caricamento, parametri, creazione CTA, ecc.) nella console del browser, aggiungi ?debug=true all’URL della libreria:

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

Questo flag URL è l’unico modo per abilitare i log dettagliati — non esiste un’opzione debug su kleep.load(...). Gli avvisi critici (valori lang/market non supportati, mancata corrispondenza product_id/selectors, chiamata doppia a kleep.load) vengono sempre mostrati, anche senza questo flag. Rimuovi ?debug=true in produzione.

3. Metodi

3.1. `kleep.load` — Visualizza il CTA di Kleep

Inizializza il widget con kleep.load:

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

Aggiungi un contenitore dove deve essere visualizzato il widget nella pagina prodotto:
```
<div id="kleep-container"></div>
```

Questo div viene utilizzato per inserire il nostro pulsante al suo interno. Lo stile CSS del pulsante è lasciato a te durante l’implementazione.

Parametri

kleep.load deve essere chiamato su ogni pagina prodotto (PDP) per caricare il CTA di Kleep, con i seguenti parametri:

Parametro	Tipo	Descrizione	Priorità
`public_id`	UUID	L’UUID fornito durante l’onboarding	obbligatorio
`product_id`	string \| array	ID prodotto/i della PDP su cui viene chiamato `kleep.load`. Una singola stringa si applica a ogni selettore; un array deve corrispondere a `selectors.sizing` (vedi avviso sotto).	obbligatorio
`customer_id`	string	ID del cliente connesso (deve corrispondere a ciò che viene inviato tramite trasferimenti dati)	opzionale
`lang`	string	Lingua corrente della pagina. Seguire ISO 639-1. Default: `fr`. Vedi l’elenco delle lingue supportate sotto.	obbligatorio
`market`	string	Codice paese (posizione del visitatore del sito). Seguire ISO 3166-1 alpha-2. Default: `null`. Vedi l’elenco dei mercati supportati sotto.	opzionale
`selectors.sizing`	array	Selettori HTML del/i wrapper del pulsante di dimensionamento. Passa più selettori per aggiungere più CTA nella stessa PDP.	obbligatorio
`getSizes`	async function	Restituisce le taglie disponibili come array di `{ variantId, quantity }` in modo che il widget possa verificare se le taglie raccomandate sono disponibili.	obbligatorio per quell’utilizzo, altrimenti opzionale
`addToCart`	async function	Riceve un `variantId` come input e aggiunge la variante prodotto corrispondente al carrello.	obbligatorio per quell’utilizzo, altrimenti opzionale
`selectSize`	async function	Riceve un `variantId` come input e seleziona la variante corrispondente nell’UI del tuo negozio (consente al cliente di saltare un clic).	obbligatorio per quell’utilizzo, altrimenti opzionale

Se lang o market non seguono le rispettive convenzioni o non sono supportati, verrà visualizzato un avviso nella console.

Corrispondenza tra product_id e selectors.sizing. Questi due parametri controllano quale prodotto viene visualizzato in quale contenitore, quindi devono essere allineati:

Un prodotto in uno o più contenitori → passa product_id come stringa singola. Lo stesso prodotto viene applicato a ogni selettore in selectors.sizing.
Prodotti diversi, uno per contenitore → passa product_id come array con la stessa lunghezza di selectors.sizing. Sono abbinati per indice, quindi l’ordine deve corrispondere (product_id[0] → selectors.sizing[0], e così via).

Se product_id è un array con lunghezza diversa da selectors.sizing, non viene renderizzato alcun CTA e viene registrato un avviso nella console (vengono stampate entrambe le lunghezze e i valori). Ad esempio, product_id: ["sku-1"] (1 elemento) con due selettori fallisce silenziosamente — correggi ripetendo l’id (["sku-1", "sku-1"]) o passandolo come stringa ("sku-1").

Lingue supportate (ISO 639-1)

Se una lingua di cui hai bisogno non è nell’elenco seguente, contatta il tuo rappresentante Kleep.

fr — Francese (default)
br — Brasiliano
da — Danese
de — Tedesco
en — Inglese
es — Spagnolo
fi — Finlandese
it — Italiano
ja — Giapponese
ko — Coreano
nl — Olandese
pl — Polacco
pt — Portoghese
sv — Svedese
zh — Cinese

Mercati supportati (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

Esempio

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 l’implementazione, puoi usare questa configurazione di test:

public_id: "aadb1934-6e16-4c8a-a7cb-1fd6e00dd02c"
product_id: "12345"
variantId da usare per le callback (con la relativa etichetta di taglia):

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

3.2. `kleep.createButton` — Ricrea il CTA di Kleep

In alcuni casi il tuo sito potrebbe ricostruire componenti o ricaricare variabili di stato, causando la scomparsa del CTA di Kleep. Chiama kleep.createButton per farlo riapparire. Non è necessario alcun parametro — riutilizza le informazioni fornite quando hai chiamato kleep.load, quindi assicurati che kleep.load sia stato eseguito prima.

3.3. `kleep.track` — Abilita il tracciamento e l’accesso alla Dashboard

Oltre alla funzionalità di dimensionamento, aggiungiamo il tracciamento in modo che tu possa misurare le prestazioni della soluzione sul tuo sito. Usa kleep.track(event_type, event_info) per inviare informazioni ogni volta che si verifica un evento tracciato. Tracciamo tre eventi:

Tipo di evento	Trigger	Priorità
`product_viewed`	Alla visualizzazione della PDP	`obbligatorio`
`product_added_to_cart`	All’aggiunta del prodotto al carrello	`obbligatorio`
`checkout_completed`	Alla conferma dell’ordine dopo il pagamento	`obbligatorio`

`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` — Ottieni l’ID interno Kleep

Per casi d’uso personalizzati, puoi recuperare uno degli ID interni Kleep del visitatore. Restituisce:

null — se il visitatore non ha utilizzato Kleep, oppure
un UUID — se il visitatore ha un ID di tracciamento Kleep

Kleep è completamente subordinato al consenso del visitatore: lo script si carica solo dopo che il consenso è stato raccolto tramite la tua CMP, e devi condizionarne il caricamento di conseguenza. Per l’elenco completo dei tracker, i dati trattati, le finalità e le basi giuridiche, hosting, responsabili del trattamento e sicurezza, consulta Cookie, CMP & Privacy dei Dati.

​1. Consenso ai cookie (requisito legale)

​2. Installazione

​3. Metodi

​3.1. kleep.load — Visualizza il CTA di Kleep

​Parametri

​Esempio

​3.2. kleep.createButton — Ricrea il CTA di Kleep

​3.3. kleep.track — Abilita il tracciamento e l’accesso alla Dashboard

​product_viewed

​product_added_to_cart

​checkout_completed

​3.4. kleep.getTrackingId — Ottieni l’ID interno Kleep

​Cookie e privacy dei dati

1. Consenso ai cookie (requisito legale)

2. Installazione

3. Metodi

3.1. `kleep.load` — Visualizza il CTA di Kleep

Parametri

Esempio

3.2. `kleep.createButton` — Ricrea il CTA di Kleep

3.3. `kleep.track` — Abilita il tracciamento e l’accesso alla Dashboard

`product_viewed`

`product_added_to_cart`

`checkout_completed`

3.4. `kleep.getTrackingId` — Ottieni l’ID interno Kleep

Cookie e privacy dei dati