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

# Bibliothèque JS

> Installez et configurez le widget Kleep AI Sizing sur n'importe quel storefront via notre bibliothèque JavaScript.

Ce guide couvre l'installation du widget Kleep AI Sizing sur n'importe quel storefront via notre bibliothèque JavaScript. Utilisez-le conjointement avec le guide d'intégration backend spécifique à votre plateforme (Prestashop, Magento, WooCommerce, WShop, etc.) — celui-ci gère l'ingestion des données, tandis que ce guide s'occupe du CTA frontend sur vos pages produits.

## 1. Consentement aux cookies (obligation légale)

<Warning>
  Le chargement de Kleep traite des données personnelles via des cookies et technologies similaires. Vous devez donc **légalement conditionner le chargement de Kleep au consentement préalable du visiteur aux cookies** — n'appelez pas `kleep.load` (ni ne chargez la bibliothèque) tant que le visiteur n'a pas accepté les cookies concernés dans votre Plateforme de Gestion du Consentement (CMP).
</Warning>

<Note>
  Concrètement : conditionnez la balise `<script src="https://module.kleep.ai/api/widget">` et l'appel `kleep.load(...)` au callback de consentement de votre CMP, afin qu'ils ne s'exécutent qu'après l'accord du consentement pour les deux finalités. Si le consentement est retiré ultérieurement, cessez de charger Kleep lors des pages vues suivantes.
</Note>

Votre CMP doit exposer deux finalités de traitement, et Kleep ne peut être chargé qu'une fois que le visiteur a consenti aux deux. Le libellé exact à afficher dans votre bandeau — disponible en 15 langues — se trouve sur la page [Cookies, CMP & confidentialité des données](/fr/cookie-consent). Copiez-le depuis cette page.

## 2. Installation

Pour commencer, incluez le fichier JavaScript du widget dans votre projet.

Avant `</body>`, ajoutez :

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

<Tip>
  **Voir les logs pendant l'intégration.** Par défaut, le widget s'exécute silencieusement. Pour afficher les logs complets `[KLEEP] [Widget]` (flux de chargement, paramètres, création du CTA, etc.) dans la console de votre navigateur, ajoutez `?debug=true` à l'URL de la bibliothèque :

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

  Ce paramètre d'URL est le seul moyen d'activer les logs verbeux — il n'existe pas d'option `debug` sur `kleep.load(...)`. Les avertissements critiques (`lang`/`market` non pris en charge, incompatibilité `product_id`/`selectors`, appel de `kleep.load` deux fois) sont **toujours** affichés, même sans ce paramètre. Supprimez `?debug=true` en production.
</Tip>

## 3. Méthodes

### 3.1. `kleep.load` — Afficher le CTA de Kleep

1. Initialisez le widget avec `kleep.load` :

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

2. Ajoutez un conteneur où le widget doit s'afficher sur la page produit :

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

<Note>
  Cette div est utilisée pour y insérer notre bouton. Nous laissons le style CSS du bouton à votre charge lors de l'implémentation.
</Note>

#### Paramètres

`kleep.load` doit être appelé sur chaque page produit (PDP) pour charger le CTA de Kleep, avec les paramètres suivants :

| Paramètre          | Type            | Description                                                                                                                                                                                                             | Priorité                               |
| ------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `public_id`        | UUID            | L'UUID fourni lors de l'onboarding                                                                                                                                                                                      | **requis**                             |
| `product_id`       | string \| array | Identifiant(s) produit de la PDP sur laquelle `kleep.load` est appelé. Une chaîne unique s'applique à tous les sélecteurs ; un tableau doit correspondre à `selectors.sizing` (voir avertissement ci-dessous).          | **requis**                             |
| `customer_id`      | string          | Identifiant du client connecté (doit correspondre à ce qui est envoyé via les transferts de données)                                                                                                                    | optionnel                              |
| `lang`             | string          | Langue courante de la page. Suivez la norme [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes). Défaut : `fr`. Voir la liste des langues prises en charge ci-dessous.                            | **requis**                             |
| `market`           | string          | Code pays (localisation du visiteur du site). Suivez la norme [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). Défaut : `null`. Voir la liste des marchés pris en charge ci-dessous. | optionnel                              |
| `selectors.sizing` | array           | Sélecteurs HTML du ou des conteneurs du bouton de dimensionnement. Passez-en plusieurs pour ajouter plusieurs CTAs sur la même PDP.                                                                                     | **requis**                             |
| `getSizes`         | async function  | Renvoie les tailles disponibles sous forme de tableau de `{ variantId, quantity }` pour que le widget puisse vérifier si les tailles recommandées sont en stock.                                                        | requis pour cet usage, sinon optionnel |
| `addToCart`        | async function  | Reçoit un `variantId` en entrée et ajoute la variante produit correspondante au panier.                                                                                                                                 | requis pour cet usage, sinon optionnel |
| `selectSize`       | async function  | Reçoit un `variantId` en entrée et sélectionne la variante correspondante dans l'interface de votre storefront (permet au client d'économiser un clic).                                                                 | requis pour cet usage, sinon optionnel |

<Note>
  Si `lang` ou `market` ne respectent pas leurs conventions respectives ou ne sont pas pris en charge, un avertissement s'affichera dans la console.
</Note>

<Warning>
  **Correspondance entre `product_id` et `selectors.sizing`.** Ces deux paramètres contrôlent quel produit est affiché dans quel conteneur, ils doivent donc être alignés :

  * **Un produit dans un ou plusieurs conteneurs** → passez `product_id` comme une **chaîne unique**. Le même produit est appliqué à tous les sélecteurs dans `selectors.sizing`.
  * **Des produits différents, un par conteneur** → passez `product_id` comme un **tableau de même longueur que `selectors.sizing`**. Ils sont associés par index, l'ordre doit donc correspondre (`product_id[0]` → `selectors.sizing[0]`, etc.).

  Si `product_id` est un tableau dont la longueur est **différente** de `selectors.sizing`, **aucun CTA n'est rendu** et un avertissement est journalisé dans la console (il affiche les deux longueurs et valeurs). Par exemple, `product_id: ["sku-1"]` (1 élément) avec deux sélecteurs échoue silencieusement — corrigez-le en répétant l'id (`["sku-1", "sku-1"]`) ou en le passant comme chaîne (`"sku-1"`).
</Warning>

<Accordion title="Langues prises en charge (ISO 639-1)">
  Si une langue dont vous avez besoin ne figure pas dans la liste ci-dessous, contactez votre représentant Kleep.

  * `fr` — Français (défaut)
  * `br` — Brésilien
  * `da` — Danois
  * `de` — Allemand
  * `en` — Anglais
  * `es` — Espagnol
  * `fi` — Finnois
  * `it` — Italien
  * `ja` — Japonais
  * `ko` — Coréen
  * `nl` — Néerlandais
  * `pl` — Polonais
  * `pt` — Portugais
  * `sv` — Suédois
  * `zh` — Chinois
</Accordion>

<Accordion title="Marchés pris en charge (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>

#### Exemple

```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>
  Pendant l'implémentation, vous pouvez utiliser cette configuration de test :

  * `public_id`: `"aadb1934-6e16-4c8a-a7cb-1fd6e00dd02c"`
  * `product_id`: `"12345"`
  * `variantId`s à utiliser pour les callbacks (avec leur libellé de taille correspondant) :

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

### 3.2. `kleep.createButton` — Recréer le CTA de Kleep

Dans certains cas, votre site peut reconstruire des composants ou recharger des variables d'état, entraînant la disparition du CTA de Kleep. Appelez `kleep.createButton` pour le faire réapparaître.

Aucun paramètre n'est nécessaire — il réutilise les informations que vous avez fournies lors de l'appel à `kleep.load`, assurez-vous donc que `kleep.load` a bien été exécuté en premier.

### 3.3. `kleep.track` — Activer le tracking et l'accès au Dashboard

En plus de la fonctionnalité de dimensionnement, nous ajoutons du tracking afin que vous puissiez mesurer les performances de la solution sur votre site. Utilisez `kleep.track(event_type, event_info)` pour envoyer des informations chaque fois qu'un événement tracké se produit.

Nous trackons trois événements :

| Type d'événement        | Déclencheur                                  | Priorité |
| ----------------------- | -------------------------------------------- | -------- |
| `product_viewed`        | À la consultation de la PDP                  | `requis` |
| `product_added_to_cart` | À l'ajout au panier                          | `requis` |
| `checkout_completed`    | À la confirmation de commande après paiement | `requis` |

#### `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` — Obtenir l'identifiant interne Kleep

Pour des cas d'usage personnalisés, vous pouvez récupérer l'un des identifiants internes Kleep du visiteur.

Il retourne soit :

* `null` — si le visiteur n'a pas utilisé Kleep, ou
* un UUID — si le visiteur dispose d'un identifiant de tracking Kleep

***

## Cookies & confidentialité des données

Kleep est entièrement conditionné par le consentement du visiteur : le script ne se charge **qu'après** que le consentement a été collecté via votre CMP, et vous devez conditionner son chargement en conséquence. Pour la liste complète des traceurs, les données traitées, les finalités et bases légales, l'hébergement, les sous-traitants et la sécurité, consultez [Cookies, CMP & confidentialité des données](/fr/cookie-consent).