> ## 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 等）配合使用——后端指南负责数据接入，本指南负责产品页（PDP）的前端 CTA 按钮。

## 1. Cookie 同意（法律要求）

<Warning>
  加载 Kleep 会通过 Cookie 及类似技术处理个人数据。因此，您**必须在法律层面将 Kleep 的加载与访客事先对 Cookie 的同意相绑定**——在访客通过您的同意管理平台（CMP）接受相关 Cookie 之前，请勿调用 `kleep.load`（或加载该库）。
</Warning>

<Note>
  具体实现：将 `<script src="https://module.kleep.ai/api/widget">` 标签和 `kleep.load(...)` 调用置于 CMP 的同意回调之后，确保仅在访客对两项目的均同意后才执行。若同意随后被撤回，请在后续页面浏览中停止加载 Kleep。
</Note>

您的 CMP 必须公示两项处理目的，且仅在访客对两项目的均表示同意后，方可加载 Kleep。横幅中需展示的具体措辞（15 种语言）已收录于 [Cookie、CMP 与数据隐私](/zh/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>

#### 参数

应在每个产品页（PDP）上调用 `kleep.load` 以加载 Kleep CTA，参数如下：

| 参数                 | 类型              | 描述                                                                                                                           | 优先级         |
| ------------------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `public_id`        | UUID            | 入职时提供给您的 UUID                                                                                                                | **必填**      |
| `product_id`       | string \| array | 调用 `kleep.load` 的 PDP 上的产品 ID。单个字符串适用于所有选择器；数组长度必须与 `selectors.sizing` 匹配（见下方警告）。                                            | **必填**      |
| `customer_id`      | string          | 已登录客户的 ID（须与数据传输中发送的 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

***

## Cookie 与数据隐私

Kleep 完全受访客同意控制：脚本仅在通过您的 CMP 收集同意**后**加载，您必须相应地设置加载条件。有关追踪器的完整列表、处理的数据、目的和法律依据、托管、子处理商及安全信息，请参阅 [Cookie、CMP 与数据隐私](/zh/cookie-consent)。