JS 라이브러리 - Kleep Docs

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

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

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

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

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

2. 설치

시작하려면 위젯의 JavaScript 파일을 프로젝트에 포함시키세요. </body> 앞에 다음을 추가하세요:

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

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

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

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

3. 메서드

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

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

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

상품 페이지에 위젯이 표시될 컨테이너를 추가하세요:
```
<div id="kleep-container"></div>
```

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

매개변수

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을 따르세요. 기본값: `fr`. 아래 지원 언어 목록을 참조하세요.	필수
`market`	string	국가 코드(웹사이트 방문자의 위치). ISO 3166-1 alpha-2를 따르세요. 기본값: `null`. 아래 지원 마켓 목록을 참조하세요.	선택적
`selectors.sizing`	array	사이즈 버튼 래퍼의 HTML 셀렉터. 여러 개를 전달하여 동일한 PDP에 여러 CTA를 추가할 수 있습니다.	필수
`getSizes`	async function	위젯이 추천 사이즈의 재고 여부를 확인할 수 있도록 `{ variantId, quantity }` 배열로 가용 사이즈를 반환합니다.	해당 기능 사용 시 필수, 그 외 선택적
`addToCart`	async function	`variantId`를 입력으로 받아 해당 상품 변형을 장바구니에 추가합니다.	해당 기능 사용 시 필수, 그 외 선택적
`selectSize`	async function	`variantId`를 입력으로 받아 스토어프론트 UI에서 해당 변형을 선택합니다(고객이 클릭 한 번을 건너뛸 수 있게 해줍니다).	해당 기능 사용 시 필수, 그 외 선택적

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

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") 수정하세요.

지원 언어 (ISO 639-1)

아래 목록에 필요한 언어가 없으면 Kleep 담당자에게 문의하세요.

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

지원 마켓 (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

예시

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

구현 중에 이 테스트 구성을 사용할 수 있습니다:

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

`variantId`	사이즈
`a`	34
`b`	36
`c`	38
`d`	40
`e`	42

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`

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

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

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

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

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

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

​2. 설치

​3. 메서드

​3.1. kleep.load — Kleep CTA 표시

​매개변수

​예시

​3.2. kleep.createButton — Kleep CTA 재생성

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

​product_viewed

​product_added_to_cart

​checkout_completed

​3.4. kleep.getTrackingId — Kleep 내부 ID 조회

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

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

2. 설치

3. 메서드

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

매개변수

예시

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

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

`product_viewed`

`product_added_to_cart`

`checkout_completed`

3.4. `kleep.getTrackingId` — Kleep 내부 ID 조회

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