> ## 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. Cookie の同意（法的要件）

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

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

CMP は **2 つの処理目的** を公開する必要があり、Kleep は訪問者が両方に同意した後にのみ読み込まれます。バナーに表示する正確な文言（15 言語対応）は、[Cookie、CMP とデータプライバシー](/ja/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` を 2 回呼び出した場合）は、このフラグなしでも**常に**表示されます。本番環境では `?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` は、各プロダクトページ（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](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 で対応するバリアントを選択します（顧客のクリックを 1 回省略できます）。                                                                                    | その用途には必須、それ以外は任意 |

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

<Warning>
  **`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"`）ことで修正できます。
</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)` を使用して情報を送信してください。

追跡するイベントは 3 種類です：

| イベントタイプ                 | トリガー              | 優先度        |
| ----------------------- | ----------------- | ---------- |
| `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 の 1 つを取得できます。

返される値は次のいずれかです：

* `null` — 訪問者が Kleep を使用したことがない場合、または
* UUID — 訪問者に Kleep トラッキング ID がある場合

***

## Cookie とデータプライバシー

Kleep は訪問者の同意によって完全にゲート管理されています：スクリプトは CMP を通じて同意が収集された**後**にのみ読み込まれ、それに応じて読み込みを条件付けなければなりません。トラッカーの完全なリスト、処理されるデータ、目的と法的根拠、ホスティング、サブプロセッサー、セキュリティについては、[Cookie、CMP とデータプライバシー](/ja/cookie-consent) をご覧ください。