> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kameleoon.API.Products: Recommendations and search

> おすすめの製品、検索結果、製品とのやり取り、製品データ、おすすめのコレクションを取得する Kameleoon.API.Products メソッドのリファレンスです。

これらのメソッドを使用して、おすすめの製品、検索結果、製品とのやり取り、製品データ、おすすめのコレクションを取得します。

> [!NOTE]
>
> このモジュールは、Product Recommendation モジュールまたは Product Targeting アドオンを購読している場合に利用できます。

推奨結果を正しく返すには、製品トラッキングを正しく設定しておく必要があります。[Kameleoon.API.Products: Tracking](https://docs.kameleoon.com/ja/developer-docs/apis/activation-api-js/api-reference/modules/products-tracking.md) を参照してください。

## obtainRecommendedProducts

`obtainRecommendedProducts()` メソッドは、指定されたアルゴリズムによって計算された推奨商品を非同期サーバー呼び出しで取得します。

```javascript theme={null}
Kameleoon.API.Products.obtainRecommendedProducts(
  "1a2b3c4d",
  {
    item: 123500,
    exclude: [3, 14, 159, 26535],
    category: 146,
    search_query: "To be or not to be",
    limit: 15,
    brands: ["Alas", "poor", "Yorick", 'kameleooner'],
    categories: [1, 146, 123500]
  },
  function (response) {
    // the functionality of rendering a block of product recommendations
  },
  function (error) {
    // when something went wrong
  }
);
```

> [!WARNING]
>
> このメソッドが意味のある結果を返すには、`trackProductView()` や `trackCategoryView()` などの正しい商品トラッキングが必要です。

**引数**

| 名前 | 型 | 説明 |
| - | - | - |
| code | String | 推奨ブロックの一意のコード。 |
| params | Object | [推奨プラットフォームから返されるデータを制御するパラメータ。](#推奨プラットフォームから返されるデータを制御するパラメータ) |
| successCallback | Function | API レスポンスオブジェクトを受け取るコールバック関数。このフィールドは必須です。 |
| errorCallback | Function | エラーが発生した場合に実行されるコールバック関数。このフィールドは省略可能です。 |

### 推奨プラットフォームから返されるデータを制御するパラメータ

| 名前 | 型 | 説明 |
| - | - | - |
| item | String | 現在の商品の ID。「類似」および「この商品も購入されています」アルゴリズムでは必須です。 |
| exclude | Array | 除外する商品識別子のカンマ区切りリスト。 |
| extended | Number | "1" の場合、メソッドは商品の詳細情報を返します。省略された場合、商品 ID のみを返します。 |
| category | Number | カテゴリページのアルゴリズムでは必須です。推奨を指定されたカテゴリに制限します。 |
| categories | Array | このフィールドは省略可能です。使用された場合、指定されたカテゴリ (カテゴリ ID のカンマ区切りリスト) からの推奨商品のみを返します。 |
| brands | Array | このフィールドは省略可能です。使用された場合、指定されたブランド (ブランドのカンマ区切りリスト) からの推奨商品のみを返します。 |
| locations | Array | このフィールドは省略可能です。使用された場合、リストされた場所 (場所 ID のカンマ区切りリスト) で利用可能な推奨商品を返します。 |
| limit | Number | このフィールドは省略可能です。推奨商品の最大数。 |
| exclude\_brands | Number | このフィールドは省略可能です。レコメンデーションから除外するブランドのカンマ区切りのリストです。 |

**API レスポンス**

コールバック関数は、次の値を持つ API レスポンスオブジェクトを受け取ります。

| 名前 | 型 | 説明 |
| - | - | - |
| html | String | ブロックの HTML コード。Kameleoon の個人アカウントで HTML テンプレートをカスタマイズします。 |
| title | String | ブロックのタイトル。ブロックルールの "Action" 要素の値に対応します。 |
| products | Array | 商品 ID のリスト。 |
| id | Number | 一意のブロック識別子。Kameleoon の個人アカウント内のブロックリストにあるブロック ID に対応します。 |

## obtainInstantSearchProducts

`obtainInstantSearchProducts()` メソッドは、Kameleoon Search からパーソナライズされたインスタント検索結果を非同期サーバー呼び出しで取得します。

```javascript theme={null}
Kameleoon.API.Products.obtainInstantSearchProducts(
 {
  search_query: "To be or not to be"
 },
 function (response) {
  // the functionality to render a block from instant search
 },
 function (error) {
  // to handle when something goes wrong
 }
);
```

**引数**

| 名前 | 型 | 説明 |
| - | - | - |
| search\_query | String | ユーザーが提供する検索クエリ。このフィールドは必須です。 |
| successCallback | Function | API レスポンスオブジェクトを受け取るコールバック関数。このフィールドは必須です。 |
| errorCallback | Function | エラーが発生した場合に実行されるコールバック関数。このフィールドは省略可能です。 |

**API レスポンス**

コールバック関数は、以下の値を含む API レスポンスオブジェクトを受け取ります。表では、`[]` はオブジェクトの配列を示します。つまり、`products[].name` は各製品の名前です。

| 名前 | 型 | 説明 |
| - | - | - |
| search\_query | String | 検索クエリ。 |
| categories | Array | カテゴリに関する情報を含む配列。 |
| categories\[].id | String | カテゴリ ID。 |
| categories\[].name | String | カテゴリ名。 |
| categories\[].url | String | カテゴリの URL。 |
| categories\[].count | Number | カテゴリ内の製品数。 |
| filters | Array | フィルターに関する情報を含む配列。 |
| filters\[].filter.count | Number | これらのパラメータを持つ製品の総数。 |
| filters\[].filter.values\[].value | String | 値のラベル。 |
| filters\[].filter.values\[].count | Number | このパラメータを持つ製品の数。 |
| html | String | 製品を含むブロックの HTML コード。テンプレートは Kameleoon の個人アカウントでカスタマイズします。 |
| price\_range | Object | 製品の最低価格と最高価格。 |
| price\_range.min | Number | 最低価格。 |
| price\_range.max | Number | 最高価格。 |
| products | Array | 製品に関する情報を含む配列。 |
| products\[].description | String | 製品の説明。 |
| products\[].url | String | 製品の絶対 URL。 |
| products\[].url\_handle | String | 製品の相対 URL。 |
| products\[].picture | String | Kameleoon ストレージ内の製品画像の URL。 |
| products\[].name | String | 製品名。 |
| products\[].price | Number / int | 製品価格。 |
| products\[].price\_full | Number / float | 製品価格。 |
| products\[].price\_formatted | String | 通貨記号付きの製品価格。 |
| products\[].price\_full\_formatted | String | 通貨記号付きの製品価格。 |
| products\[].image\_url | String | Kameleoon ストレージ内の製品画像の絶対 URL。 |
| products\[].image\_url\_handle | String | Kameleoon ストレージ内の製品画像の相対 URL。 |
| products\[].image\_url\_resized | Array | 製品画像のリサイズ URL。 |
| products\[].currency | String | 製品の通貨。Kameleoon の個人アカウントの通貨、またはアカウントのショップ設定で指定されたカスタム値に対応します。 |
| products\[].id | String | 製品 ID。 |
| products\[].old\_price | Number / int | 製品の旧価格。デフォルトは 0 です。 |
| products\[].old\_price\_full | Number / float | 製品の旧価格。 |
| products\[].old\_price\_formatted | String | 通貨記号付きの製品の旧価格。 |
| products\[].old\_price\_full\_formatted | String | 通貨記号付きの製品の旧価格。 |
| products\[].categories | Array | 製品のカテゴリ。リクエストで `extended` パラメータを渡した場合にのみ含まれます。 |
| products\[].categories\[].id | String | カテゴリ ID。 |
| products\[].categories\[].name | String | カテゴリ名。 |
| products\[].categories\[].parent\_id | String | 親カテゴリ ID。 |
| products\[].categories\[].url | String | カテゴリの URL。 |
| products\[].categories\[].category\_ids | Array | 製品のカテゴリ ID。 |
| search\_query\_redirects | Array | リダイレクトに関する情報を含む配列。 |
| search\_query\_redirects\[].query | String | 検索クエリ。 |
| search\_query\_redirects\[].redirect\_link | String | リダイレクト先の URL。 |
| search\_query\_redirects\[].deep\_link | String | モバイルアプリ用の URL。 |
| products\_total | Number | 製品の総数。 |

## obtainFullSearchProducts

`obtainFullSearchProducts()` メソッドを使用して、フィルタリングオプション付きの Kameleoon Search ソリューションから完全な検索結果を取得します。

```javascript theme={null}
Kameleoon.API.Products.obtainFullSearchProducts(
 {
  search_query: "To be or not to be",
  limit: 15,
  brands: ["Alas", "poor", "Yorick"],
  categories: [1, 146, 100500],
  filters: { key: ["value"], key: ["value"] },
  sort_by: "price",
  order: "asc"
 },
 function (response) {
  // the functionality to render a block from full search
 },
 function (error) {
  // when something went wrong
 }
);
```

**引数**

| 名前 | 型 | 説明 |
| - | - | - |
| search\_query | Object | ユーザーが提供する検索クエリとオプションのフィルターパラメータ。次のセクションでフィルタリングパラメータを確認してください。このフィールドは必須です。 |
| successCallback | Function | API レスポンスオブジェクトを受け取るコールバック関数。このフィールドは必須です。 |
| errorCallback | Function | エラーが発生した場合に実行されるコールバック関数。このフィールドは省略可能です。 |

### 結果をフィルタリングするためのパラメータ

| 名前 | 型 | 説明 |
| - | - | - |
| search\_query | String | 検索クエリ。このフィールドは必須です。 |
| limit | Number | 結果の上限数。このフィールドは省略可能です。 |
| offset | Number | 結果のオフセット。このフィールドは省略可能です。 |
| category\_limit | Number | サイドバーフィルターに返すカテゴリの数。このフィールドは省略可能です。 |
| categories | Array | フィルターするカテゴリのカンマ区切りリスト。このフィールドは省略可能です。 |
| extended | Number | 完全な検索結果を取得するには `true` に設定します。 |
| sort\_by | String | ソートパラメータ: `popular`、`price`、`discount`、`sales_rate`、`date`。このフィールドは省略可能です。 |
| order | String | ソート方向: asc または desc (デフォルト)。このフィールドは省略可能です。 |
| locations | Array | 場所 ID のカンマ区切りリスト。このフィールドは省略可能です。 |
| brands | Array | フィルターするブランドのカンマ区切りリスト。このフィールドは省略可能です。 |
| filters | String | フィルターパラメータ付きのオプションのエスケープされた JSON 文字列。例: `{"bluetooth":["yes"],"offers":["15% cashback"],"weight":["1.6"]}`。このフィールドは省略可能です。 |
| price\_min | Number | 最低価格。このフィールドは省略可能です。 |
| price\_max | Number | 最高価格。このフィールドは省略可能です。 |
| colors  false | Array | 色のカンマ区切りリスト。このフィールドは省略可能です。 |
| fashion\_sizes | Array | サイズのカンマ区切りリスト。このフィールドは省略可能です。 |
| exclude | Array | 検索結果から除外する商品 ID のカンマ区切りリスト。このフィールドは省略可能です。 |
| email | String | S2S 統合用のみ、サービスがユーザーのセッションを持たない場合に使用します。Mobile SDK では使用しません。このフィールドは省略可能です。 |
| no\_clarification | Boolean | 明確化検索を無効にします。デフォルトは **false** です。Kameleoon のサポートから指示されない限り、このパラメータは使用しないでください。 |
| merchants | Array | マーチャントのカンマ区切りリスト。このフィールドは省略可能です。 |
| filters\_search\_by | String | フィルターで使用可能なオプション: `name`、`quantity`、`popularity`。このフィールドは省略可能です。 |

**API レスポンス**

コールバック関数は、以下の値を含む API レスポンスオブジェクトを受け取ります。表では、`[]` はオブジェクトの配列を示します。つまり、`products[].name` は各製品の名前です。

| 名前 | 型 | 説明 |
| - | - | - |
| search\_query | String | ユーザーが入力した検索クエリ。 |
| brands | Array | ブランドに関する情報を含む配列。 |
| brands\[].name | String | ブランド名。 |
| brands\[].picture | String | ブランドの画像。 |
| categories | Array | カテゴリに関する情報を含む配列。 |
| categories\[].alias | String | カテゴリのエイリアス。 |
| categories\[].id | String | カテゴリ ID。 |
| categories\[].name | String | カテゴリ名。 |
| categories\[].parent | String | 親カテゴリ ID。 |
| categories\[].url | String | カテゴリの URL。 |
| filters | Array | フィルターに関する情報を含む配列。 |
| filters\[].filter.count | Number | これらのパラメータを持つ製品の総数。 |
| filters\[].filter.values\[].value | String | 値のラベル。 |
| filters\[].filter.values\[].count | Number | このパラメータを持つ製品の数。 |
| html | String | 製品を含むブロックの HTML コード。テンプレートは Kameleoon の個人アカウントでカスタマイズします。 |
| price\_range | Object | 製品の最低価格と最高価格。 |
| price\_range.min | Number | 最低価格。 |
| price\_range.max | Number | 最高価格。 |
| products | Array | 製品に関する情報を含む配列。 |
| products\[].brand | String | 製品のブランド。 |
| products\[].currency | String | 製品の通貨。Kameleoon の個人アカウントの通貨、またはアカウントのショップ設定で指定されたカスタム値に対応します。 |
| products\[].id | String | 製品 ID。 |
| products\[].is\_new | Boolean | 製品のプロパティ。デフォルトは null です。 |
| products\[].name | String | 製品名。 |
| products\[].old\_price | String | 製品の旧価格。デフォルトは 0 です。 |
| products\[].picture | String | Kameleoon ストレージ内の製品画像の URL。 |
| products\[].price | Number | 製品価格。 |
| products\[].price\_formatted | String | 通貨記号付きの製品価格。 |
| products\[].url | String | 製品の URL。 |
| products\[].barcode | String | 製品のバーコード。リクエストで `extended` パラメータを渡した場合にのみ含まれます。 |
| products\[].categories | Array | 製品のカテゴリ。 |
| products\[].categories\[].id | String | カテゴリ ID。 |
| products\[].categories\[].name | String | カテゴリ名。 |
| products\[].categories\[].parent | String | 親カテゴリ ID。 |
| products\[].params | Array | 製品パラメータに関する情報。 |
| products\[].params\[].key | String | パラメータ名。 |
| products\[].params\[].values | Array | パラメータの値。 |
| products\_total | Number | 製品の総数。 |

## obtainProductInteractions

`obtainProductInteractions()` メソッドは、`trackProductView()`、`trackTransaction()`、または `trackAddToCart()` 経由で追跡された商品のインタラクション指標を取得します。

```javascript theme={null}
Kameleoon.API.Products.obtainProductInteractions("123456", product => {
  console.log("product", product); // {123456: {views: 1, cartQuantities: 0, boughtQuantities: 0}}
});
Kameleoon.API.Products.obtainProductInteractions(["123456", "654321"], products => {
  console.log("products", products);
});
Kameleoon.API.Products.obtainProductInteractions(
  "123456",
  callback,
  new Date().getTime() - 1000 * 60 * 60 * 24, // timeBegin
  new Date().getTime() // timeEnd
);
```

**引数**

| 名前 | 型 | 説明 |
| - | - | - |
| eans | Array | 商品 ID (String として)。このフィールドは必須です。 |
| callback | Function | 商品データを受け取るコールバック関数。このフィールドは必須です。 |
| timeBegin | Number | 日付範囲の開始 (UNIX ミリ秒のタイムスタンプ)。 |
| timeEnd | Number | 日付範囲の終了 (UNIX ミリ秒のタイムスタンプ)。 |

**API レスポンス**

| 名前 | 型 | 説明 |
| - | - | - |
| eans | Array | 商品の一意の識別子。各商品 ID は、インタラクション指標を含むオブジェクトにマッピングされます。 |
| views | integer | ビジターが製品を閲覧した回数。 |
| cartQuantities | integer | ビジターが製品をカートに追加した総回数。 |
| boughtQuantities | integer | ビジターが製品を購入した総回数。 |

## obtainProductData

`obtainProductData()` メソッドは、`trackProductView()` を介して送信されたアイテムの商品情報を取得します。

```javascript theme={null}
Kameleoon.API.Products.obtainProductData("123456", product => {
  console.log("product", product);
});
Kameleoon.API.Products.obtainProductData(["123456", "654321"], products => {
  console.log("products", products);
});
Kameleoon.API.Products.obtainProductData("123456", callback, {
  name: true,
  categoryId: true
}); // {123456: {name: '', categoryId: '' }}
```

**引数**

| 名前 | 型 | 説明 |
| - | - | - |
| eans | Array | 商品 ID (String として)。このフィールドは必須です。 |
| callback | Function | 商品データを受け取るコールバック関数。このフィールドは必須です。 |
| parameters | Object | 特定のフィールドを取得するためのオプションパラメータ。デフォルトは `{ all: true }` です。 |

**API レスポンス**

| 名前 | 型 | 説明 |
| - | - | - |
| eans | Array | 商品の一意の識別子。各商品 ID は、インタラクション指標を含むオブジェクトにマッピングされます。 |
| productData | Object | [Product オブジェクト](https://docs.kameleoon.com/ja/developer-docs/apis/activation-api-js/api-reference/objects/goal-segment-trigger-and-product.md#product)。このフィールドには、`trackProductView` が送信するものと同じオブジェクトが渡されます。 |

## obtainRecommendedCollections

`obtainRecommendedCollections()` メソッドは、指定されたコレクションから商品を取得します。

```javascript theme={null}
Kameleoon.API.Products.obtainRecommendedCollections("123456", collections => {
    /* The functionality of rendering a product collection block */
    console.log("collections", collections);
}, error => {
    /* Error handling logic if something goes wrong */
});
```

**引数**

| 名前 | 型 | 説明 |
| - | - | - |
| collectionId | String | 商品コレクション ID。Product Collections ダッシュボードセクションで利用可能です。 |
| successCallback | Function | API レスポンスオブジェクトを受け取るコールバック関数。このフィールドは必須です。 |
| errorCallback | Function | エラーが発生した場合に実行されるコールバック関数。このフィールドは省略可能です。 |

**API レスポンス**

**Products**

API はオブジェクトの配列を返します。`products` 配列の各オブジェクトには以下が含まれます。

| **パラメータ** | **型** | **説明** |
| - | - | - |
| name | String | 商品の名前 |
| url | String (URL) | 商品ページの URL |
| description | String | 商品の説明 |
| category\_ids | Array of Strings | 商品が属するカテゴリ ID のリスト |
| brand | String | 商品のブランド |
| fashion\_feature | String | ファッション機能 (例: `"adult"`) |
| fashion\_gender | String | 商品の対象性別 |
| sales\_rate | Integer | 商品の販売率 |
| relative\_sales\_rate | Float | 他の商品と比較した相対的な販売率 |
| picture | String (URL) | メイン商品画像の URL |
| categories | Array of Objects | カテゴリオブジェクトのリスト (システム定義の構造) |
| price\_formatted | String | フォーマットされた商品価格 (例: `$29.99`) |
| price\_full\_formatted | String | フォーマットされた完全価格/元の価格 |
| price | Float | 現在の商品価格 |
| price\_full | Float | 割引前の元の価格/完全価格 |
| image\_url | String (URL) | リサイズされた商品画像の URL |
| image\_url\_handle | String (URL) | 処理済み画像 URL (ハンドルベース) |
| image\_url\_resized | String (URL) | リサイズされた画像 URL |
| url\_handle | String | コレクション内で商品にアクセスするために使用される URL ハンドル |
| currency | String | 商品価格に使用される通貨コード (例: `USD`、`EUR`) |
| id | String | 商品 ID (システムによっては数値または文字列) |
| html | String (HTML) | コレクションの作成時に選択された HTML テンプレート |