> ## 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 라이브러리

> JavaScript 라이브러리를 통해 모든 스토어프론트에 Kleep AI 사이즈 위젯을 설치하고 구성하세요.

이 가이드는 JavaScript 라이브러리를 사용하여 모든 스토어프론트에 Kleep AI 사이즈 위젯을 설치하는 방법을 다룹니다. 플랫폼별 백엔드 통합 가이드(Prestashop, Magento, WooCommerce, WShop 등)와 함께 사용하세요 — 백엔드 가이드는 데이터 수집을 담당하고, 이 가이드는 상품 페이지의 프론트엔드 CTA를 담당합니다.

## 1. 쿠키 동의 (법적 요건)

<Warning>
  Kleep을 로딩하면 쿠키 및 유사 기술을 통해 개인 데이터가 처리됩니다. 따라서 방문자가 귀하의 동의 관리 플랫폼(CMP)에서 관련 쿠키에 동의하기 전까지 **법적으로 Kleep 로딩을 방문자의 사전 쿠키 동의에 조건부로 설정해야 합니다** — 방문자가 관련 쿠키에 동의하기 전에 `kleep.load`를 호출하거나 라이브러리를 로드하지 마세요.
</Warning>

<Note>
  구체적으로: CMP의 동의 콜백 뒤에 `<script src="https://module.kleep.ai/api/widget">` 태그와 `kleep.load(...)` 호출을 배치하여 두 가지 목적에 대한 동의가 부여된 후에만 실행되도록 하세요. 이후 동의가 철회된 경우, 이후 페이지 조회에서 Kleep 로딩을 중단하세요.
</Note>

귀하의 CMP는 두 가지 처리 목적을 노출해야 하며, Kleep은 방문자가 두 가지 모두에 동의한 경우에만 로드될 수 있습니다. 배너에 표시할 정확한 문구(15개 언어)는 [쿠키, CMP 및 데이터 개인정보 보호](/ko/cookie-consent) 페이지에서 확인하실 수 있습니다. 해당 페이지에서 복사하세요.

## 2. 설치

시작하려면 위젯의 JavaScript 파일을 프로젝트에 포함시키세요.

`</body>` 앞에 다음을 추가하세요:

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

<Tip>
  **통합 중 로그 확인.** 기본적으로 위젯은 자동으로 실행됩니다. 브라우저 콘솔에서 전체 `[KLEEP] [Widget]` 로그(로딩 흐름, 매개변수, CTA 생성 등)를 출력하려면 라이브러리 URL에 `?debug=true`를 추가하세요:

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

  이 URL 플래그는 상세 로그를 활성화하는 유일한 방법입니다 — `kleep.load(...)`에는 `debug` 옵션이 없습니다. 중요 경고(지원되지 않는 `lang`/`market`, `product_id`/`selectors` 불일치, `kleep.load` 두 번 호출)는 이 플래그 없이도 **항상** 표시됩니다. 프로덕션에서는 `?debug=true`를 제거하세요.
</Tip>

## 3. 메서드

### 3.1. `kleep.load` — Kleep CTA 표시

1. `kleep.load`로 위젯을 초기화하세요:

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

2. 상품 페이지에 위젯이 표시될 컨테이너를 추가하세요:

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

<Note>
  이 div는 버튼을 추가하는 데 사용됩니다. 구현 중 버튼의 CSS 스타일링은 귀하가 직접 담당합니다.
</Note>

#### 매개변수

`kleep.load`는 Kleep의 CTA를 로드하기 위해 각 상품 페이지(PDP)에서 다음 매개변수와 함께 호출해야 합니다:

| 매개변수               | 유형              | 설명                                                                                                                                              | 우선순위                   |
| ------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `public_id`        | UUID            | 온보딩 시 제공된 UUID                                                                                                                                  | **필수**                 |
| `product_id`       | string \| array | `kleep.load`가 호출되는 PDP의 상품 ID. 단일 문자열은 모든 셀렉터에 적용되며, 배열은 `selectors.sizing`과 일치해야 합니다(아래 경고 참조).                                                | **필수**                 |
| `customer_id`      | string          | 연결된 고객의 ID (데이터 전송 시 전송되는 값과 일치해야 함)                                                                                                            | 선택적                    |
| `lang`             | string          | 페이지의 현재 언어. [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes)을 따르세요. 기본값: `fr`. 아래 지원 언어 목록을 참조하세요.                     | **필수**                 |
| `market`           | string          | 국가 코드(웹사이트 방문자의 위치). [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)를 따르세요. 기본값: `null`. 아래 지원 마켓 목록을 참조하세요. | 선택적                    |
| `selectors.sizing` | array           | 사이즈 버튼 래퍼의 HTML 셀렉터. 여러 개를 전달하여 동일한 PDP에 여러 CTA를 추가할 수 있습니다.                                                                                    | **필수**                 |
| `getSizes`         | async function  | 위젯이 추천 사이즈의 재고 여부를 확인할 수 있도록 `{ variantId, quantity }` 배열로 가용 사이즈를 반환합니다.                                                                       | 해당 기능 사용 시 필수, 그 외 선택적 |
| `addToCart`        | async function  | `variantId`를 입력으로 받아 해당 상품 변형을 장바구니에 추가합니다.                                                                                                     | 해당 기능 사용 시 필수, 그 외 선택적 |
| `selectSize`       | async function  | `variantId`를 입력으로 받아 스토어프론트 UI에서 해당 변형을 선택합니다(고객이 클릭 한 번을 건너뛸 수 있게 해줍니다).                                                                       | 해당 기능 사용 시 필수, 그 외 선택적 |

<Note>
  `lang` 또는 `market`이 각각의 형식을 따르지 않거나 지원되지 않는 경우 콘솔 경고가 표시됩니다.
</Note>

<Warning>
  **`product_id`와 `selectors.sizing` 매칭.** 이 두 가지는 어떤 상품이 어떤 컨테이너에 표시되는지를 제어하므로 일치해야 합니다:

  * **하나의 컨테이너 또는 여러 컨테이너에 하나의 상품** → `product_id`를 **단일 문자열**로 전달하세요. 동일한 상품이 `selectors.sizing`의 모든 셀렉터에 적용됩니다.
  * **컨테이너당 다른 상품** → `product_id`를 **`selectors.sizing`와 동일한 길이의 배열**로 전달하세요. 인덱스별로 쌍을 이루므로 순서가 일치해야 합니다(`product_id[0]` → `selectors.sizing[0]`, 이하 동일).

  `product_id`의 길이가 `selectors.sizing`와 **다른** 배열인 경우, **CTA가 전혀 렌더링되지 않으며** 콘솔에 경고가 기록됩니다(두 길이와 값을 모두 출력합니다). 예를 들어, `product_id: ["sku-1"]`(1개 항목)에 셀렉터 두 개가 있으면 자동으로 실패합니다 — id를 반복하거나(`["sku-1", "sku-1"]`) 문자열로 전달하여(`"sku-1"`) 수정하세요.
</Warning>

<Accordion title="지원 언어 (ISO 639-1)">
  아래 목록에 필요한 언어가 없으면 Kleep 담당자에게 문의하세요.

  * `fr` — 프랑스어 (기본값)
  * `br` — 브라질 포르투갈어
  * `da` — 덴마크어
  * `de` — 독일어
  * `en` — 영어
  * `es` — 스페인어
  * `fi` — 핀란드어
  * `it` — 이탈리아어
  * `ja` — 일본어
  * `ko` — 한국어
  * `nl` — 네덜란드어
  * `pl` — 폴란드어
  * `pt` — 포르투갈어
  * `sv` — 스웨덴어
  * `zh` — 중국어
</Accordion>

<Accordion title="지원 마켓 (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>

#### 예시

```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>
  구현 중에 이 테스트 구성을 사용할 수 있습니다:

  * `public_id`: `"aadb1934-6e16-4c8a-a7cb-1fd6e00dd02c"`
  * `product_id`: `"12345"`
  * 콜백에 사용할 `variantId`(해당 사이즈 레이블 포함):

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

### 3.2. `kleep.createButton` — Kleep CTA 재생성

경우에 따라 웹사이트가 컴포넌트를 다시 빌드하거나 상태 변수를 다시 로드하면 Kleep의 CTA가 사라질 수 있습니다. `kleep.createButton`을 호출하여 다시 나타나게 하세요.

매개변수가 필요하지 않습니다 — `kleep.load` 호출 시 제공한 정보를 재사용하므로 `kleep.load`가 먼저 실행되었는지 확인하세요.

### 3.3. `kleep.track` — 추적 활성화 및 대시보드 접근

사이즈 추천 기능 외에도 솔루션이 웹사이트에서 어떻게 작동하는지 측정할 수 있도록 추적을 추가합니다. 추적 이벤트가 발생할 때마다 `kleep.track(event_type, event_info)`를 사용하여 정보를 전송하세요.

세 가지 이벤트를 추적합니다:

| 이벤트 유형                  | 트리거             | 우선순위       |
| ----------------------- | --------------- | ---------- |
| `product_viewed`        | PDP 조회 시        | `required` |
| `product_added_to_cart` | 상품이 장바구니에 추가될 때 | `required` |
| `checkout_completed`    | 결제 후 주문 확인 시    | `required` |

#### `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` — Kleep 내부 ID 조회

커스텀 사용 사례를 위해 방문자의 Kleep 내부 ID 중 하나를 검색할 수 있습니다.

반환값:

* `null` — 방문자가 Kleep을 사용한 적이 없는 경우, 또는
* UUID — 방문자에게 Kleep 추적 ID가 있는 경우

***

## 쿠키 및 데이터 개인정보 보호

Kleep은 방문자 동의에 의해 완전히 제어됩니다: 스크립트는 CMP를 통해 동의가 수집된 **후에만** 로드되며, 이에 따라 로딩 조건을 설정해야 합니다. 추적기의 전체 목록, 처리되는 데이터, 목적 및 법적 근거, 호스팅, 하위 처리자 및 보안에 대한 내용은 [쿠키, CMP 및 데이터 개인정보 보호](/ko/cookie-consent)를 참조하세요.