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

> Installieren und konfigurieren Sie das Kleep KI-Größenberatungs-Widget auf jedem Storefront über unsere JavaScript-Bibliothek.

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.

## 1. Cookie-Einwilligung (gesetzliche Anforderung)

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

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

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](/de/cookie-consent). 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:

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

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

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

## 3. Methoden

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

1. Initialisieren Sie das Widget mit `kleep.load`:

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

2. Fügen Sie einen Container hinzu, in dem das Widget auf der Produktseite angezeigt werden soll:

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

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

#### 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](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes). 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](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes). 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 |

<Note>
  Wenn `lang` oder `market` nicht ihren jeweiligen Konventionen folgen oder nicht unterstützt werden, erscheint eine Konsolenwarnung.
</Note>

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

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

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

#### Beispiel

```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>
  Während der Implementierung können Sie diese Testkonfiguration verwenden:

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

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

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

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