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

# JS Library

> Install and configure the Kleep AI Sizing widget on any storefront via our JavaScript library.

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.

## 1. Cookie consent (legal requirement)

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

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

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](/cookie-consent#consent-wording-to-display-in-your-cmp) page. Copy it from there.

## 2. Installation

To get started, include the widget's JavaScript file in your project.

Before `</body>`, add:

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

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

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

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

## 3. Methods

### 3.1. `kleep.load` — Display Kleep's CTA

1. Initialize the widget with `kleep.load`:

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

2. Add a container where the widget should be displayed on the product page:

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

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

#### 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](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes). Default: `fr`. See list of supported languages below.                            | **required**                                |
| `market`           | string          | Country code (location of the website visitor). Follow [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). 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 |

<Note>
  If `lang` or `market` don't follow their respective conventions or aren't supported, you'll see a console warning.
</Note>

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

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

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

#### Example

```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>
  While implementing, you can use this test config:

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

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

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

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

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`

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