Bibliothèque JS - Kleep Docs

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)

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

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.

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. Copiez-le depuis cette page.

2. Installation

Pour commencer, incluez le fichier JavaScript du widget dans votre projet. Avant </body>, ajoutez :

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

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 :

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

3. Méthodes

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

Initialisez le widget avec kleep.load :

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

Ajoutez un conteneur où le widget doit s’afficher sur la page produit :
```
<div id="kleep-container"></div>
```

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.

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

Si lang ou market ne respectent pas leurs conventions respectives ou ne sont pas pris en charge, un avertissement s’affichera dans la console.

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

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

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

Exemple

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

Pendant l’implémentation, vous pouvez utiliser cette configuration de test :

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

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

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`

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

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

​2. Installation

​3. Méthodes

​3.1. kleep.load — Afficher le CTA de Kleep

​Paramètres

​Exemple

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

​3.3. kleep.track — Activer le tracking et l’accès au Dashboard

​product_viewed

​product_added_to_cart

​checkout_completed

​3.4. kleep.getTrackingId — Obtenir l’identifiant interne Kleep

​Cookies & confidentialité des données

1. Consentement aux cookies (obligation légale)

2. Installation

3. Méthodes

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

Paramètres

Exemple

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

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

`product_viewed`

`product_added_to_cart`

`checkout_completed`

3.4. `kleep.getTrackingId` — Obtenir l’identifiant interne Kleep

Cookies & confidentialité des données