JS-Bibliothek - Kleep Docs

Dieser Leitfaden behandelt die Installation des Kleep KI-Größenberatungs-Widgets auf jedem Storefront über unsere JavaScript-Bibliothek. Verwenden Sie ihn zusammen mit dem plattformspezifischen Backend-Integrationsleitfaden (Prestashop, Magento, WooCommerce, WShop, etc.) — dieser regelt die Datenaufnahme, während dieser Leitfaden den Frontend-CTA auf Ihren Produktseiten behandelt.

Das Laden von Kleep verarbeitet personenbezogene Daten über Cookies und ähnliche Technologien. Sie müssen daher rechtlich das Laden von Kleep von der vorherigen Einwilligung des Besuchers zu Cookies abhängig machen — rufen Sie kleep.load nicht auf (oder laden Sie die Bibliothek), bis der Besucher die relevanten Cookies in Ihrer Consent Management Platform (CMP) akzeptiert hat.

Konkret: Verknüpfen Sie den <script src="https://module.kleep.ai/api/widget">-Tag und den kleep.load(...)-Aufruf mit dem Einwilligungs-Callback Ihrer CMP, sodass sie nur nach erteilter Einwilligung für beide Zwecke ausgeführt werden. Wenn die Einwilligung später widerrufen wird, laden Sie Kleep bei nachfolgenden Seitenaufrufen nicht mehr.

Ihre CMP muss zwei Verarbeitungszwecke offenlegen, und Kleep darf erst geladen werden, wenn der Besucher beiden zugestimmt hat. Den genauen Wortlaut für Ihr Banner — in 15 Sprachen — finden Sie auf der Seite Cookies, CMP & Datenschutz. Kopieren Sie ihn von dort.

2. Installation

Um zu beginnen, binden Sie die JavaScript-Datei des Widgets in Ihr Projekt ein. Fügen Sie vor </body> folgendes hinzu:

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

Logs während der Integration anzeigen. Standardmäßig läuft das Widget lautlos. Um die vollständigen [KLEEP] [Widget]-Logs (Ladeflow, Parameter, CTA-Erstellung usw.) in Ihrer Browser-Konsole anzuzeigen, fügen Sie ?debug=true zur Bibliotheks-URL hinzu:

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

Dieses URL-Flag ist die einzige Möglichkeit, die ausführlichen Logs zu aktivieren — es gibt keine debug-Option für kleep.load(...). Kritische Warnungen (nicht unterstützte lang/market, product_id/selectors-Nichtübereinstimmung, doppelter Aufruf von kleep.load) werden immer angezeigt, auch ohne dieses Flag. Entfernen Sie ?debug=true in der Produktion.

3. Methoden

3.1. `kleep.load` — Kleep-CTA anzeigen

Initialisieren Sie das Widget mit kleep.load:

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

Fügen Sie einen Container hinzu, in dem das Widget auf der Produktseite angezeigt werden soll:
```
<div id="kleep-container"></div>
```

Dieser div wird verwendet, um unsere Schaltfläche darin einzufügen. Das CSS-Styling der Schaltfläche überlassen wir Ihnen während der Implementierung.

Parameter

kleep.load sollte auf jeder Produktseite (PDP) aufgerufen werden, um den Kleep-CTA zu laden, mit folgenden Parametern:

Parameter	Typ	Beschreibung	Priorität
`public_id`	UUID	Die UUID, die Ihnen beim Onboarding bereitgestellt wurde	erforderlich
`product_id`	string \| array	Produkt-ID(s) des PDP, auf dem `kleep.load` aufgerufen wird. Ein einzelner String gilt für jeden Selektor; ein Array muss mit `selectors.sizing` übereinstimmen (siehe Warnung unten).	erforderlich
`customer_id`	string	ID des angemeldeten Kunden (muss mit dem übereinstimmen, was über Datenübertragungen gesendet wird)	optional
`lang`	string	Aktuelle Sprache der Seite. Folgen Sie ISO 639-1. Standard: `fr`. Weitere Informationen finden Sie in der Liste der unterstützten Sprachen.	erforderlich
`market`	string	Ländercode (Standort des Website-Besuchers). Folgen Sie ISO 3166-1 alpha-2. Standard: `null`. Weitere Informationen finden Sie in der Liste der unterstützten Märkte.	optional
`selectors.sizing`	array	HTML-Selektoren der Größenschaltflächen-Wrapper. Übergeben Sie mehrere, um mehrere CTAs auf demselben PDP hinzuzufügen.	erforderlich
`getSizes`	async function	Gibt die verfügbaren Größen als Array von `{ variantId, quantity }` zurück, damit das Widget prüfen kann, ob empfohlene Größen vorrätig sind.	für diese Nutzung erforderlich, sonst optional
`addToCart`	async function	Erhält eine `variantId` als Eingabe und fügt die entsprechende Produktvariante dem Warenkorb hinzu.	für diese Nutzung erforderlich, sonst optional
`selectSize`	async function	Erhält eine `variantId` als Eingabe und wählt die entsprechende Variante in Ihrer Storefront-UI aus (ermöglicht dem Kunden, einen Klick zu überspringen).	für diese Nutzung erforderlich, sonst optional

Wenn lang oder market nicht ihren jeweiligen Konventionen folgen oder nicht unterstützt werden, erscheint eine Konsolenwarnung.

product_id mit selectors.sizing abgleichen. Diese beiden steuern, welches Produkt in welchem Container angezeigt wird, daher müssen sie übereinstimmen:

Ein Produkt in einem oder mehreren Containern → übergeben Sie product_id als einzelnen String. Dasselbe Produkt wird auf jeden Selektor in selectors.sizing angewendet.
Verschiedene Produkte, eines pro Container → übergeben Sie product_id als Array mit derselben Länge wie selectors.sizing. Sie werden nach Index gepaart, daher muss die Reihenfolge übereinstimmen (product_id[0] → selectors.sizing[0] usw.).

Wenn product_id ein Array ist, dessen Länge sich von selectors.sizing unterscheidet, wird kein CTA gerendert und eine Warnung wird in der Konsole protokolliert (sie gibt beide Längen und Werte aus). Beispielsweise schlägt product_id: ["sku-1"] (1 Element) mit zwei Selektoren lautlos fehl — beheben Sie es, indem Sie die ID wiederholen (["sku-1", "sku-1"]) oder als String übergeben ("sku-1").

Unterstützte Sprachen (ISO 639-1)

Wenn eine Sprache, die Sie benötigen, nicht in der folgenden Liste aufgeführt ist, wenden Sie sich bitte an Ihren Kleep-Ansprechpartner.

fr — Französisch (Standard)
br — Brasilianisch
da — Dänisch
de — Deutsch
en — Englisch
es — Spanisch
fi — Finnisch
it — Italienisch
ja — Japanisch
ko — Koreanisch
nl — Niederländisch
pl — Polnisch
pt — Portugiesisch
sv — Schwedisch
zh — Chinesisch

Unterstützte Märkte (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

Beispiel

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

Während der Implementierung können Sie diese Testkonfiguration verwenden:

public_id: "aadb1934-6e16-4c8a-a7cb-1fd6e00dd02c"
product_id: "12345"
variantIds für die Callbacks (mit entsprechender Größenbeschriftung):

`variantId`	Größe
`a`	34
`b`	36
`c`	38
`d`	40
`e`	42

3.2. `kleep.createButton` — Kleep-CTA neu erstellen

In manchen Fällen kann Ihre Website Komponenten neu aufbauen oder Zustandsvariablen neu laden, was dazu führt, dass der Kleep-CTA verschwindet. Rufen Sie kleep.createButton auf, um ihn wieder erscheinen zu lassen. Es werden keine Parameter benötigt — es verwendet die Informationen, die Sie beim Aufruf von kleep.load bereitgestellt haben. Stellen Sie daher sicher, dass kleep.load zuerst ausgeführt wurde.

3.3. `kleep.track` — Tracking & Dashboard-Zugang aktivieren

Zusätzlich zur Größenfunktionalität fügen wir Tracking hinzu, damit Sie messen können, wie die Lösung auf Ihrer Website abschneidet. Verwenden Sie kleep.track(event_type, event_info), um Informationen zu senden, wenn ein getrackes Ereignis eintritt. Wir tracken drei Ereignisse:

Ereignistyp	Auslöser	Priorität
`product_viewed`	Beim Aufrufen des PDP	`erforderlich`
`product_added_to_cart`	Beim Hinzufügen eines Produkts zum Warenkorb	`erforderlich`
`checkout_completed`	Bei der Bestellbestätigung nach der Zahlung	`erforderlich`

`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` — Interne Kleep-ID abrufen

Für benutzerdefinierte Anwendungsfälle können Sie eine der internen Kleep-IDs des Besuchers abrufen. Gibt entweder zurück:

null — wenn der Besucher Kleep noch nicht verwendet hat, oder
eine UUID — wenn der Besucher eine Kleep-Tracking-ID hat

Cookies & Datenschutz

Kleep wird vollständig durch die Besuchereinwilligung gesteuert: Das Skript wird erst nach der Einwilligung durch Ihre CMP geladen, und Sie müssen das Laden entsprechend bedingen. Die vollständige Liste der Tracker, der verarbeiteten Daten, der Zwecke und Rechtsgrundlagen, des Hostings, der Unterauftragsverarbeiter und der Sicherheit finden Sie unter Cookies, CMP & Datenschutz.

​1. Cookie-Einwilligung (gesetzliche Anforderung)

​2. Installation

​3. Methoden

​3.1. kleep.load — Kleep-CTA anzeigen

​Parameter

​Beispiel

​3.2. kleep.createButton — Kleep-CTA neu erstellen

​3.3. kleep.track — Tracking & Dashboard-Zugang aktivieren

​product_viewed

​product_added_to_cart

​checkout_completed

​3.4. kleep.getTrackingId — Interne Kleep-ID abrufen

​Cookies & Datenschutz

1. Cookie-Einwilligung (gesetzliche Anforderung)

2. Installation

3. Methoden

3.1. `kleep.load` — Kleep-CTA anzeigen

Parameter

Beispiel

3.2. `kleep.createButton` — Kleep-CTA neu erstellen

3.3. `kleep.track` — Tracking & Dashboard-Zugang aktivieren

`product_viewed`

`product_added_to_cart`

`checkout_completed`

3.4. `kleep.getTrackingId` — Interne Kleep-ID abrufen

Cookies & Datenschutz