Biblioteka JS - Kleep Docs

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.

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

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.

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. Skopiuj ją stamtąd.

2. Instalacja

Aby rozpocząć, dołącz plik JavaScript widżetu do swojego projektu. Przed </body> dodaj:

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

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:

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

3. Metody

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

Zainicjuj widżet za pomocą kleep.load:

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

Dodaj kontener, w którym widżet ma być wyświetlany na stronie produktu:
```
<div id="kleep-container"></div>
```

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

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

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

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

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

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

Przykład

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

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

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`

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

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.

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

​2. Instalacja

​3. Metody

​3.1. kleep.load — Wyświetl CTA Kleep

​Parametry

​Przykład

​3.2. kleep.createButton — Odtwórz CTA Kleep

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

​product_viewed

​product_added_to_cart

​checkout_completed

​3.4. kleep.getTrackingId — Pobierz wewnętrzny ID Kleep

​Pliki cookie i prywatność danych

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

2. Instalacja

3. Metody

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

Parametry

Przykład

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

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

`product_viewed`

`product_added_to_cart`

`checkout_completed`

3.4. `kleep.getTrackingId` — Pobierz wewnętrzny ID Kleep

Pliki cookie i prywatność danych