JS Library - Kleep Docs

This guide covers installing the Kleep AI Sizing widget on any storefront using our JavaScript library. Use it together with the platform-specific backend integration guide (Prestashop, Magento, WooCommerce, WShop, etc.) — that handles data ingestion, while this guide handles the front-end CTA on your product pages.

Loading Kleep processes personal data through cookies and similar technologies. You must therefore legally condition the loading of Kleep on the visitor’s prior consent to cookies — do not call kleep.load (or load the library) until the visitor has accepted the relevant cookies in your Consent Management Platform (CMP).

Concretely: gate the <script src="https://module.kleep.ai/api/widget"> tag and the kleep.load(...) call behind your CMP’s consent callback, so they only run after consent is granted. If consent is later withdrawn, stop loading Kleep on subsequent page views.

Your CMP must expose two processing purposes, and Kleep may only be loaded once the visitor has consented to both. The exact wording to display in your banner — in 15 languages — lives on the Cookies, CMP & Data Privacy page. Copy it from there.

2. Installation

To get started, include the widget’s JavaScript file in your project. Before </body>, add:

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

Load the library globally, on every page of your site — not just product pages. Add the <script src="https://module.kleep.ai/api/widget"> tag site-wide so the kleep object is available on all pages. This is required because kleep.track events fire outside of PDPs too (e.g. product_added_to_cart on the cart page, checkout_completed on the order-confirmation page), and those pages need the kleep object to be present. The product-page-specific call kleep.load(...) should still only run on PDPs.

Seeing the logs while you integrate. By default the widget runs silently. To print the full [KLEEP] [Widget] logs (loading flow, parameters, CTA creation, etc.) in your browser console, add ?debug=true to the library URL:

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

This URL flag is the only way to enable the verbose logs — there is no debug option on kleep.load(...). Critical warnings (unsupported lang/market, product_id/selectors mismatch, calling kleep.load twice) are always shown, even without this flag. Remove ?debug=true in production.

3. Methods

3.1. `kleep.load` — Display Kleep’s CTA

Initialize the widget with kleep.load:

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

Add a container where the widget should be displayed on the product page:
```
<div id="kleep-container"></div>
```

This div is used to append our button inside. We leave CSS styling of the button to you during the implementation.

Parameters

kleep.load should be called on each product page (PDP) to load Kleep’s CTA, with the following parameters:

Parameter	Type	Description	Priority
`public_id`	UUID	The UUID provided to you during onboarding	required
`product_id`	string \| array	Product ID(s) of the PDP on which `kleep.load` is called. A single string applies to every selector; an array must match `selectors.sizing` (see warning below).	required
`customer_id`	string	ID of the connected customer (must match what is sent via data transfers)	optional
`lang`	string	Current language of the page. Follow ISO 639-1. Default: `fr`. See list of supported languages below.	required
`market`	string	Country code (location of the website visitor). Follow ISO 3166-1 alpha-2. Default: `null`. See list of supported markets below.	optional
`selectors.sizing`	array	HTML selectors of the sizing button wrapper(s). Pass multiple to add several CTAs on the same PDP.	required
`getSizes`	async function	Returns the available sizes as an array of `{ variantId, quantity }` so the widget can check whether recommended sizes are in stock.	required for that usage, otherwise optional
`addToCart`	async function	Receives a `variantId` as input and adds the matching product variant to the cart.	required for that usage, otherwise optional
`selectSize`	async function	Receives a `variantId` as input and selects the matching variant in your storefront UI (lets the customer skip one click).	required for that usage, otherwise optional

If lang or market don’t follow their respective conventions or aren’t supported, you’ll see a console warning.

Matching product_id with selectors.sizing. These two control which product is shown in which container, so they have to line up:

One product in one or several containers → pass product_id as a single string. The same product is applied to every selector in selectors.sizing.
Different products, one per container → pass product_id as an array with the same length as selectors.sizing. They are paired by index, so the order must match (product_id[0] → selectors.sizing[0], and so on).

If product_id is an array whose length is different from selectors.sizing, no CTA is rendered at all and a warning is logged in the console (it prints both lengths and values). For example, product_id: ["sku-1"] (1 item) with two selectors fails silently — fix it by repeating the id (["sku-1", "sku-1"]) or passing it as a string ("sku-1").

Supported languages (ISO 639-1)

If a language you need isn’t in the list below, please contact your Kleep representative.

fr — French (default)
br — Brazilian
da — Danish
de — German
en — English
es — Spanish
fi — Finnish
it — Italian
ja — Japanese
ko — Korean
nl — Dutch
pl — Polish
pt — Portuguese
sv — Swedish
zh — Chinese

Supported markets (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

Example

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

While implementing, you can use this test config:

public_id: "aadb1934-6e16-4c8a-a7cb-1fd6e00dd02c"
product_id: "12345"
variantIds to use for the callbacks (with their corresponding size label):

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

3.2. `kleep.createButton` — Recreate Kleep’s CTA

In some cases your website might rebuild components or reload state variables, causing Kleep’s CTA to disappear. Call kleep.createButton to make it reappear. No parameter is needed — it reuses the information you provided when calling kleep.load, so make sure kleep.load ran first.

3.3. `kleep.track` — Enable tracking & Dashboard access

On top of the sizing functionality, we add tracking so you can measure how the solution performs on your website. Use kleep.track(event_type, event_info) to send information each time a tracked event occurs.

These events track your store’s standard customer journey — a product being viewed, added to cart, or purchased through your usual storefront flow. They are not Kleep-specific actions (e.g. an add-to-cart triggered from the Kleep widget); fire each one wherever it naturally happens on your site.

We track three events:

Event type	Trigger	Priority
`product_viewed`	Upon PDP viewed	`required`
`product_added_to_cart`	Upon product added to the cart	`required`
`checkout_completed`	Upon order confirmation after payment	`required`

`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` — Get internal Kleep ID

For custom use cases, you can retrieve one of the visitor’s Kleep internal IDs. It returns either:

null — if the visitor has not used Kleep, or
a UUID — if the visitor has a Kleep tracking ID

Cookies & data privacy

Kleep is fully gated by visitor consent: the script only loads after consent is collected through your CMP, and you must condition its loading accordingly. For the complete list of trackers, the data processed, the purposes and legal bases, hosting, subprocessors and security, see Cookies, CMP & Data Privacy.

​1. Cookie consent (legal requirement)

​2. Installation

​3. Methods

​3.1. kleep.load — Display Kleep’s CTA

​Parameters

​Example

​3.2. kleep.createButton — Recreate Kleep’s CTA

​3.3. kleep.track — Enable tracking & Dashboard access

​product_viewed

​product_added_to_cart

​checkout_completed

​3.4. kleep.getTrackingId — Get internal Kleep ID

​Cookies & data privacy

1. Cookie consent (legal requirement)

2. Installation

3. Methods

3.1. `kleep.load` — Display Kleep’s CTA

Parameters

Example

3.2. `kleep.createButton` — Recreate Kleep’s CTA

3.3. `kleep.track` — Enable tracking & Dashboard access

`product_viewed`

`product_added_to_cart`

`checkout_completed`

3.4. `kleep.getTrackingId` — Get internal Kleep ID

Cookies & data privacy