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

> Asenna ja konfiguroi Kleep AI Sizing -widget millä tahansa verkkokauppaalustalla JavaScript-kirjastomme avulla.

Tämä opas kattaa Kleep AI Sizing -widgetin asentamisen millä tahansa verkkokauppaalustalla JavaScript-kirjastomme avulla. Käytä sitä yhdessä alustakohtaisen backend-integrointioppaan (Prestashop, Magento, WooCommerce, WShop jne.) kanssa — se hoitaa tietojen käsittelyn, kun taas tämä opas hoitaa tuotesivujen (PDP) frontend-CTA:n.

## 1. Evästeiden suostumus (lakisääteinen vaatimus)

<Warning>
  Kleepin lataaminen käsittelee henkilötietoja evästeiden ja vastaavien teknologioiden avulla. Sinun on siksi **laillisesti ehdollistettava Kleepin lataaminen kävijän aiempaan evästeiden hyväksyntään** — älä kutsu `kleep.load`-funktiota (tai lataa kirjastoa), ennen kuin kävijä on hyväksynyt asiaankuuluvat evästeet Consent Management Platform (CMP) -järjestelmässäsi.
</Warning>

<Note>
  Käytännössä: aseta `<script src="https://module.kleep.ai/api/widget">`-tagi ja `kleep.load(...)`-kutsu CMP:si suostumuskutsun taakse, jotta ne suoritetaan vasta, kun molemmat tarkoitukset on hyväksytty. Jos suostumus peruutetaan myöhemmin, lopeta Kleepin lataaminen seuraavilla sivunäkymillä.
</Note>

CMP:si on esitettävä **kaksi käsittelytarkoitusta**, ja Kleep voidaan ladata vasta, kun kävijä on hyväksynyt molemmat. Täsmälliset tekstit, jotka näytetään bannereissasi — 15 kielellä — löytyvät [Evästeet, CMP ja tietosuoja](/fi/cookie-consent) -sivulta. Kopioi ne sieltä.

## 2. Asennus

Aloita lisäämällä widgetin JavaScript-tiedosto projektiisi.

Lisää ennen `</body>`-tagia:

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

<Tip>
  **Lokien tarkastelu integroinnin aikana.** Oletusarvoisesti widget toimii hiljaisesti. Tulosta täydet `[KLEEP] [Widget]`-lokit (latauskulku, parametrit, CTA:n luonti jne.) selaimesi konsoliin lisäämällä `?debug=true` kirjaston URL-osoitteeseen:

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

  Tämä URL-lippu on ainoa tapa ottaa käyttöön laajat lokit — `kleep.load(...)`-funktiossa ei ole `debug`-vaihtoehtoa. Kriittiset varoitukset (ei-tuettu `lang`/`market`, `product_id`/`selectors`-yhteensopimattomuus, `kleep.load`:n kutsuminen kahdesti) näytetään **aina**, jopa ilman tätä lippua. Poista `?debug=true` tuotantoympäristöstä.
</Tip>

## 3. Metodit

### 3.1. `kleep.load` — Näytä Kleepin CTA

1. Alusta widget `kleep.load`-funktiolla:

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

2. Lisää kontti, johon widget näytetään tuotesivulla:

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

<Note>
  Tätä div-elementtiä käytetään painikkeemme lisäämiseen sisälle. Jätämme painikkeen CSS-tyylittelyn sinulle toteutuksen aikana.
</Note>

#### Parametrit

`kleep.load` tulee kutsua jokaisella tuotesivulla (PDP) Kleepin CTA:n lataamiseksi seuraavilla parametreilla:

| Parametri          | Tyyppi          | Kuvaus                                                                                                                                                                                                                | Prioriteetti                                       |
| ------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `public_id`        | UUID            | UUID, joka on toimitettu sinulle käyttöönoton aikana                                                                                                                                                                  | **pakollinen**                                     |
| `product_id`       | string \| array | PDP:n tuote-ID(t), joilla `kleep.load` kutsutaan. Yksittäinen merkkijono koskee jokaista valitsinta; taulukon on vastattava `selectors.sizing`-arvoa (katso alla oleva varoitus).                                     | **pakollinen**                                     |
| `customer_id`      | string          | Kirjautuneen asiakkaan ID (vastattava tiedonsiirroissa lähetettyä)                                                                                                                                                    | valinnainen                                        |
| `lang`             | string          | Sivun nykyinen kieli. Noudata [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) -standardia. Oletus: `fr`. Katso alla oleva tuettujen kielten luettelo.                                       | **pakollinen**                                     |
| `market`           | string          | Maakoodi (verkkosivuston kävijän sijainti). Noudata [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) -standardia. Oletus: `null`. Katso alla oleva tuettujen markkinoiden luettelo. | valinnainen                                        |
| `selectors.sizing` | array           | Kokopainikekehyksen/-kehysten HTML-valitsimet. Välitä useita lisätäksesi useita CTA:ita samalle PDP:lle.                                                                                                              | **pakollinen**                                     |
| `getSizes`         | async function  | Palauttaa saatavilla olevat koot taulukkona `{ variantId, quantity }` -muodossa, jotta widget voi tarkistaa, ovatko suositellut koot saatavilla.                                                                      | pakollinen kyseiseen käyttöön, muutoin valinnainen |
| `addToCart`        | async function  | Vastaanottaa `variantId`:n syötteenä ja lisää vastaavan tuotevariantin ostoskoriin.                                                                                                                                   | pakollinen kyseiseen käyttöön, muutoin valinnainen |
| `selectSize`       | async function  | Vastaanottaa `variantId`:n syötteenä ja valitsee vastaavan variantin verkkokauppasi käyttöliittymässä (antaa asiakkaan ohittaa yhden napsautuksen).                                                                   | pakollinen kyseiseen käyttöön, muutoin valinnainen |

<Note>
  Jos `lang` tai `market` eivät noudata niiden vastaavia käytäntöjä tai niitä ei tueta, näet konsolivaroituksen.
</Note>

<Warning>
  **`product_id`:n sovittaminen `selectors.sizing`-arvoon.** Nämä kaksi ohjaavat, mikä tuote näytetään missä kontissa, joten niiden on vastattava toisiaan:

  * **Yksi tuote yhdessä tai useammassa kontissa** → välitä `product_id` **yksittäisenä merkkijonona**. Sama tuote koskee jokaista `selectors.sizing`-valitsinta.
  * **Eri tuotteet, yksi per kontti** → välitä `product_id` **taulukkona, jonka pituus on sama kuin `selectors.sizing`-taulukolla**. Ne yhdistetään indeksin mukaan, joten järjestyksen on vastattava toisiaan (`product_id[0]` → `selectors.sizing[0]` jne.).

  Jos `product_id` on taulukko, jonka pituus **poikkeaa** `selectors.sizing`-taulukon pituudesta, **CTA:ta ei renderöidä lainkaan** ja varoitus kirjataan konsoliin (se tulostaa molemmat pituudet ja arvot). Esimerkiksi `product_id: ["sku-1"]` (1 kohde) kahdella valitsimella epäonnistuu hiljaisesti — korjaa se toistamalla id (`["sku-1", "sku-1"]`) tai välittämällä se merkkijonona (`"sku-1"`).
</Warning>

<Accordion title="Tuetut kielet (ISO 639-1)">
  Jos tarvitsemaasi kieltä ei ole alla olevassa luettelossa, ota yhteyttä Kleep-edustajaan.

  * `fr` — Ranska (oletus)
  * `br` — Brasilia
  * `da` — Tanska
  * `de` — Saksa
  * `en` — Englanti
  * `es` — Espanja
  * `fi` — Suomi
  * `it` — Italia
  * `ja` — Japani
  * `ko` — Korea
  * `nl` — Hollanti
  * `pl` — Puola
  * `pt` — Portugali
  * `sv` — Ruotsi
  * `zh` — Kiina
</Accordion>

<Accordion title="Tuetut markkinat (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>

#### Esimerkki

```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>
  Toteutuksen aikana voit käyttää tätä testikonfiguraatiota:

  * `public_id`: `"aadb1934-6e16-4c8a-a7cb-1fd6e00dd02c"`
  * `product_id`: `"12345"`
  * `variantId`:t käytettäväksi takaisinkutsuissa (vastaavine kokoselitteineen):

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

### 3.2. `kleep.createButton` — Luo Kleepin CTA uudelleen

Joissakin tapauksissa verkkosivustosi saattaa rakentaa komponentit uudelleen tai ladata tilamuuttujat uudelleen, jolloin Kleepin CTA katoaa. Kutsu `kleep.createButton`-funktiota, jotta se ilmestyy uudelleen.

Parametreja ei tarvita — se käyttää uudelleen `kleep.load`-kutsun yhteydessä antamiasi tietoja, joten varmista, että `kleep.load` on suoritettu ensin.

### 3.3. `kleep.track` — Ota seuranta käyttöön ja pääsy kojelautaan

Kokomitatoiminnon lisäksi lisäämme seurannan, jotta voit mitata ratkaisun suorituskykyä verkkosivustollasi. Käytä `kleep.track(event_type, event_info)` -funktiota tietojen lähettämiseen aina, kun seurattu tapahtuma ilmenee.

Seuraamme kolmea tapahtumaa:

| Tapahtumatyyppi         | Laukaisija                                       | Prioriteetti |
| ----------------------- | ------------------------------------------------ | ------------ |
| `product_viewed`        | PDP:n katselun yhteydessä                        | `pakollinen` |
| `product_added_to_cart` | Tuotteen lisäämisen yhteydessä ostoskoriin       | `pakollinen` |
| `checkout_completed`    | Tilausvahvistuksen yhteydessä maksamisen jälkeen | `pakollinen` |

#### `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` — Hae Kleepin sisäinen ID

Mukautettuja käyttötapauksia varten voit hakea yhden kävijän Kleep-sisäisistä ID:istä.

Se palauttaa joko:

* `null` — jos kävijä ei ole käyttänyt Kleepiä, tai
* UUID — jos kävijällä on Kleep-seuranta-ID

***

## Evästeet ja tietosuoja

Kleep on täysin kävijän suostumuksen alainen: skripti latautuu vasta **sen jälkeen**, kun suostumus on kerätty CMP:n kautta, ja sinun on ehdollistettava sen lataaminen vastaavasti. Täydellinen luettelo seuraimista, käsitellyistä tiedoista, tarkoituksista ja oikeusperusteista, isännöinnistä, alitoimittajista ja tietoturvasta löytyy täältä: [Evästeet, CMP ja tietosuoja](/fi/cookie-consent).