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

# Biblioteka JS

> Zainstaluj i skonfiguruj widget Kleep AI Sizing na dowolnej platformie sklepowej za pomocą naszej biblioteki JavaScript.

Ten przewodnik opisuje instalację widżetu Kleep AI Sizing na dowolnej platformie sklepowej za pomocą naszej biblioteki JavaScript. Korzystaj z niego razem z przewodnikiem integracji backendu dla konkretnej platformy (Prestashop, Magento, WooCommerce, WShop itd.) — ten obsługuje pozyskiwanie danych, a niniejszy przewodnik obsługuje front-endowy CTA na stronach produktów.

## 1. Zgoda na pliki cookie (wymóg prawny)

<Warning>
  Wczytanie Kleep przetwarza dane osobowe za pośrednictwem plików cookie i podobnych technologii. Musisz zatem **prawnie uzależnić wczytanie Kleep od uprzedniej zgody odwiedzającego na pliki cookie** — nie wywołuj `kleep.load` (ani nie wczytuj biblioteki), dopóki odwiedzający nie zaakceptuje odpowiednich plików cookie w swojej Platformie Zarządzania Zgodą (CMP).
</Warning>

<Note>
  Konkretnie: umieść tag `<script src="https://module.kleep.ai/api/widget">` oraz wywołanie `kleep.load(...)` za callbackiem zgody CMP, tak aby uruchamiały się tylko po udzieleniu zgody na oba cele. Jeśli zgoda zostanie później wycofana, przestań wczytywać Kleep przy kolejnych odsłonach strony.
</Note>

Twój CMP musi ujawnić dwa cele przetwarzania, a Kleep może być wczytany dopiero po wyrażeniu przez odwiedzającego zgody na oba. Dokładna treść do wyświetlenia w banerze — w 15 językach — znajduje się na stronie [Pliki cookie, CMP i prywatność danych](/pl/cookie-consent). Skopiuj ją stamtąd.

## 2. Instalacja

Aby rozpocząć, dołącz plik JavaScript widżetu do swojego projektu.

Przed `</body>` dodaj:

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

<Tip>
  **Przeglądanie logów podczas integracji.** Domyślnie widżet działa cicho. Aby wyświetlić pełne logi `[KLEEP] [Widget]` (przebieg wczytywania, parametry, tworzenie CTA itp.) w konsoli przeglądarki, dodaj `?debug=true` do adresu URL biblioteki:

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

  Ta flaga URL to jedyny sposób na włączenie szczegółowych logów — nie ma opcji `debug` w `kleep.load(...)`. Krytyczne ostrzeżenia (nieobsługiwany `lang`/`market`, niezgodność `product_id`/`selectors`, dwukrotne wywołanie `kleep.load`) są **zawsze** wyświetlane, nawet bez tej flagi. Usuń `?debug=true` na produkcji.
</Tip>

## 3. Metody

### 3.1. `kleep.load` — Wyświetl CTA Kleep

1. Zainicjuj widżet za pomocą `kleep.load`:

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

2. Dodaj kontener, w którym widżet ma być wyświetlany na stronie produktu:

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

<Note>
  Ten div służy do wstawienia naszego przycisku. Stylizację CSS przycisku pozostawiamy Tobie podczas implementacji.
</Note>

#### Parametry

`kleep.load` należy wywoływać na każdej stronie produktu (PDP) w celu wczytania CTA Kleep, z następującymi parametrami:

| Parametr           | Typ             | Opis                                                                                                                                                                                              | Priorytet                                                     |
| ------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `public_id`        | UUID            | UUID przekazany podczas wdrożenia                                                                                                                                                                 | **wymagany**                                                  |
| `product_id`       | string \| array | ID produktu/produktów na PDP, na której wywoływany jest `kleep.load`. Pojedynczy string stosuje się do każdego selektora; tablica musi odpowiadać `selectors.sizing` (zob. ostrzeżenie poniżej).  | **wymagany**                                                  |
| `customer_id`      | string          | ID zalogowanego klienta (musi odpowiadać temu, co jest przesyłane w transferach danych)                                                                                                           | opcjonalny                                                    |
| `lang`             | string          | Aktualny język strony. Zgodnie z [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes). Domyślnie: `fr`. Zob. lista obsługiwanych języków poniżej.                            | **wymagany**                                                  |
| `market`           | string          | Kod kraju (lokalizacja odwiedzającego). Zgodnie z [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). Domyślnie: `null`. Zob. lista obsługiwanych rynków poniżej. | opcjonalny                                                    |
| `selectors.sizing` | array           | Selektory HTML kontenerów przycisku rozmiarowania. Podaj kilka, aby dodać wiele CTA na tej samej PDP.                                                                                             | **wymagany**                                                  |
| `getSizes`         | async function  | Zwraca dostępne rozmiary jako tablicę `{ variantId, quantity }`, dzięki czemu widżet może sprawdzić, czy rekomendowane rozmiary są dostępne w magazynie.                                          | wymagany przy tym zastosowaniu, w przeciwnym razie opcjonalny |
| `addToCart`        | async function  | Przyjmuje `variantId` jako dane wejściowe i dodaje odpowiedni wariant produktu do koszyka.                                                                                                        | wymagany przy tym zastosowaniu, w przeciwnym razie opcjonalny |
| `selectSize`       | async function  | Przyjmuje `variantId` jako dane wejściowe i zaznacza odpowiedni wariant w interfejsie sklepu (umożliwia klientowi pominięcie jednego kliknięcia).                                                 | wymagany przy tym zastosowaniu, w przeciwnym razie opcjonalny |

<Note>
  Jeśli `lang` lub `market` nie spełniają odpowiednich konwencji lub nie są obsługiwane, w konsoli pojawi się ostrzeżenie.
</Note>

<Warning>
  **Dopasowanie `product_id` do `selectors.sizing`.** Te dwa parametry kontrolują, który produkt jest wyświetlany w którym kontenerze, dlatego muszą być ze sobą zsynchronizowane:

  * **Jeden produkt w jednym lub kilku kontenerach** → podaj `product_id` jako **pojedynczy string**. Ten sam produkt jest stosowany do każdego selektora w `selectors.sizing`.
  * **Różne produkty, po jednym w każdym kontenerze** → podaj `product_id` jako **tablicę o tej samej długości co `selectors.sizing`**. Są one parowane według indeksu, więc kolejność musi być zgodna (`product_id[0]` → `selectors.sizing[0]` itd.).

  Jeśli `product_id` jest tablicą o długości **różniącej się** od `selectors.sizing`, **żaden CTA nie zostanie wyrenderowany** i w konsoli zostanie zalogowane ostrzeżenie (wyświetla obie długości i wartości). Na przykład `product_id: ["sku-1"]` (1 element) z dwoma selektorami zakończy się cichym niepowodzeniem — napraw to, powtarzając id (`["sku-1", "sku-1"]`) lub przekazując je jako string (`"sku-1"`).
</Warning>

<Accordion title="Obsługiwane języki (ISO 639-1)">
  Jeśli potrzebny język nie znajduje się na poniższej liście, skontaktuj się ze swoim przedstawicielem Kleep.

  * `fr` — Francuski (domyślny)
  * `br` — Brazylijski
  * `da` — Duński
  * `de` — Niemiecki
  * `en` — Angielski
  * `es` — Hiszpański
  * `fi` — Fiński
  * `it` — Włoski
  * `ja` — Japoński
  * `ko` — Koreański
  * `nl` — Holenderski
  * `pl` — Polski
  * `pt` — Portugalski
  * `sv` — Szwedzki
  * `zh` — Chiński
</Accordion>

<Accordion title="Obsługiwane rynki (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>

#### Przykład

```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>
  Podczas implementacji możesz użyć tej testowej konfiguracji:

  * `public_id`: `"aadb1934-6e16-4c8a-a7cb-1fd6e00dd02c"`
  * `product_id`: `"12345"`
  * `variantId` do użycia w callbackach (z odpowiadającymi etykietami rozmiarów):

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

### 3.2. `kleep.createButton` — Odtwórz CTA Kleep

W niektórych przypadkach Twoja witryna może przebudowywać komponenty lub ponownie ładować zmienne stanu, powodując zniknięcie CTA Kleep. Wywołaj `kleep.createButton`, aby przywrócić jego wyświetlanie.

Żaden parametr nie jest wymagany — metoda ponownie wykorzystuje informacje podane podczas wywołania `kleep.load`, więc upewnij się, że `kleep.load` zostało wcześniej uruchomione.

### 3.3. `kleep.track` — Włącz śledzenie i dostęp do panelu

Oprócz funkcji rozmiarowania dodajemy śledzenie, dzięki któremu możesz mierzyć wydajność rozwiązania na swojej witrynie. Użyj `kleep.track(event_type, event_info)`, aby wysyłać informacje za każdym razem, gdy wystąpi śledzony zdarzenie.

Śledzimy trzy zdarzenia:

| Typ zdarzenia           | Wyzwalacz                                | Priorytet  |
| ----------------------- | ---------------------------------------- | ---------- |
| `product_viewed`        | Po wyświetleniu PDP                      | `wymagany` |
| `product_added_to_cart` | Po dodaniu produktu do koszyka           | `wymagany` |
| `checkout_completed`    | Po potwierdzeniu zamówienia po płatności | `wymagany` |

#### `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` — Pobierz wewnętrzny ID Kleep

W niestandardowych przypadkach użycia możesz pobrać jeden z wewnętrznych identyfikatorów Kleep odwiedzającego.

Zwraca:

* `null` — jeśli odwiedzający nie korzystał z Kleep, lub
* UUID — jeśli odwiedzający posiada identyfikator śledzenia Kleep

***

## Pliki cookie i prywatność danych

Kleep jest w pełni uzależniony od zgody odwiedzającego: skrypt wczytuje się tylko **po** zebraniu zgody przez Twój CMP i musisz odpowiednio uzależnić jego wczytanie. Pełna lista modułów śledzących, przetwarzanych danych, celów i podstaw prawnych, hostingu, podprzetwarzających i zabezpieczeń znajduje się w sekcji [Pliki cookie, CMP i prywatność danych](/pl/cookie-consent).