JS 库 - Kleep Docs

本指南介绍如何通过 JavaScript 库在任意店面安装 Kleep AI 尺码推荐组件。请将本指南与各平台后端集成指南（Prestashop、Magento、WooCommerce、WShop 等）配合使用——后端指南负责数据接入，本指南负责产品页（PDP）的前端 CTA 按钮。

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

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

您的 CMP 必须公示两项处理目的，且仅在访客对两项目的均表示同意后，方可加载 Kleep。横幅中需展示的具体措辞（15 种语言）已收录于 Cookie、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 样式由您在集成过程中自行定义。

参数

应在每个产品页（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。默认值：`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 收集同意后加载，您必须相应地设置加载条件。有关追踪器的完整列表、处理的数据、目的和法律依据、托管、子处理商及安全信息，请参阅 Cookie、CMP 与数据隐私。

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

​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

​Cookie 与数据隐私

1. Cookie 同意（法律要求）

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

Cookie 与数据隐私