JS ライブラリ - Kleep Docs

このガイドでは、JavaScript ライブラリを使用して、あらゆるストアフロントに Kleep AI サイジングウィジェットをインストールする方法を説明します。プラットフォーム固有のバックエンド統合ガイド（Prestashop、Magento、WooCommerce、WShop など）と併用してください。そちらはデータ取り込みを担当し、本ガイドはプロダクトページのフロントエンド CTA を担当します。

Kleep を読み込むと、Cookie および類似技術を通じて個人データが処理されます。そのため、訪問者がコンセント管理プラットフォーム（CMP）で関連 Cookie に事前同意するまで、Kleep の読み込みを条件付けることが法的に必要です — 訪問者が同意するまで kleep.load を呼び出したり、ライブラリを読み込んだりしないでください。

具体的には：<script src="https://module.kleep.ai/api/widget"> タグと kleep.load(...) 呼び出しを CMP の同意コールバックの背後に配置し、両方の目的について同意が得られた後にのみ実行されるようにしてください。後に同意が撤回された場合は、以降のページビューで Kleep の読み込みを停止してください。

CMP は 2 つの処理目的 を公開する必要があり、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 を 2 回呼び出した場合）は、このフラグなしでも常に表示されます。本番環境では ?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 は、各プロダクトページ（PDP）で Kleep の CTA を読み込むために呼び出す必要があります。以下のパラメーターを使用します：

パラメーター	型	説明	優先度
`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 で対応するバリアントを選択します（顧客のクリックを 1 回省略できます）。	その用途には必須、それ以外は任意

lang または market がそれぞれの規則に従っていないか、サポートされていない場合、コンソールに警告が表示されます。

product_id と selectors.sizing の対応。 この 2 つはどのプロダクトをどのコンテナに表示するかを制御するため、一致させる必要があります：

1 つのプロダクトを 1 つまたは複数のコンテナに → product_id を単一の文字列として渡します。selectors.sizing のすべてのセレクターに同じプロダクトが適用されます。
コンテナごとに異なるプロダクト → product_id を selectors.sizing と同じ長さの配列として渡します。インデックスでペアリングされるため、順序が一致する必要があります（product_id[0] → selectors.sizing[0]、以下同様）。

product_id が selectors.sizing と異なる長さの配列の場合、CTA はまったく表示されず、コンソールに警告が記録されます（両方の長さと値が表示されます）。例えば、product_id: ["sku-1"]（1 要素）でセレクターが 2 つある場合は失敗します — ["sku-1", "sku-1"] のように ID を繰り返すか、文字列として渡す（"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) を使用して情報を送信してください。追跡するイベントは 3 種類です：

イベントタイプ	トリガー	優先度
`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 の 1 つを取得できます。返される値は次のいずれかです：

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 とデータプライバシー