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

# Libreria JS

> Installa e configura il widget Kleep AI Sizing su qualsiasi vetrina tramite la nostra libreria JavaScript.

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.

## 1. Consenso ai cookie (requisito legale)

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

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

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](/it/cookie-consent). Copiali da lì.

## 2. Installazione

Per iniziare, includi il file JavaScript del widget nel tuo progetto.

Prima di `</body>`, aggiungi:

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

<Tip>
  **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:

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

## 3. Metodi

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

1. Inizializza il widget con `kleep.load`:

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

2. Aggiungi un contenitore dove deve essere visualizzato il widget nella pagina prodotto:

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

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

#### 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](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes). 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](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). 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 |

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

<Warning>
  **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"`).
</Warning>

<Accordion title="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
</Accordion>

<Accordion title="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
</Accordion>

#### Esempio

```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 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     |
</Tip>

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

```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` — 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

***

## Cookie e privacy dei dati

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](/it/cookie-consent).