> ## 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

> Référence des méthodes Kameleoon.API.Products qui récupèrent les produits recommandés, les résultats de recherche, les interactions avec les produits, les données produit et les collections recommandées.

Utilisez ces méthodes pour récupérer les produits recommandés, les résultats de recherche, les interactions avec les produits, les données produit et les collections recommandées.

> [!NOTE]
>
> Ce module est disponible lorsque vous êtes abonné au module Recommandation de produits ou à l'extension Ciblage de produits.

Les recommandations nécessitent un suivi correct des produits pour renvoyer des résultats pertinents. Consultez [Kameleoon.API.Products: Tracking](https://docs.kameleoon.com/fr/developer-docs/apis/activation-api-js/api-reference/modules/products-tracking.md).

## obtainRecommendedProducts

La méthode `obtainRecommendedProducts()` récupère les produits recommandés calculés par l'algorithme spécifié via un appel serveur asynchrone.

```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) {
    // la fonctionnalité de rendu d'un bloc de recommandations de produits
  },
  function (error) {
    // when something went wrong
  }
);
```

> [!WARNING]
>
> Cette méthode nécessite un suivi correct des produits, tel que `trackProductView()` ou `trackCategoryView()`, pour retourner des résultats significatifs.

**Arguments**

| Name | Type | Description |
| - | - | - |
| code | String | Code unique du bloc de recommandation. |
| params | Object | [Paramètres pour contrôler les données renvoyées par la plateforme de recommandation.](#paramètres-pour-contrôler-les-données-renvoyées-par-la-plateforme-de-recommandation) |
| successCallback | Function | Fonction de rappel recevant l'objet de réponse de l'API. Ce champ est obligatoire. |
| errorCallback | Function | Fonction de rappel exécutée en cas d'erreur. Ce champ est optionnel. |

### Paramètres pour contrôler les données renvoyées par la plateforme de recommandation

| Name | Type | Description |
| - | - | - |
| item | String | ID du produit actuel. Obligatoire pour les algorithmes « Similaire » et « Ils ont aussi acheté ce produit ». |
| exclude | Array | Liste de codes de produits séparés par des virgules à exclure. |
| extended | Number | Lorsque « 1 », la méthode retourne les détails complets du produit. Si omis, elle retourne uniquement les ID de produit. |
| category | Number | Obligatoire pour les algorithmes sur les pages de catégories. Limite les recommandations à la catégorie spécifiée. |
| categories | Array | Ce champ est facultatif. S'il est utilisé, il retourne les produits recommandés uniquement des catégories spécifiées (une liste d'ID de catégories séparées par des virgules). |
| brands | Array | Ce champ est facultatif. S'il est utilisé, il retourne les produits recommandés uniquement des marques spécifiées (une liste de marques séparées par des virgules). |
| locations | Array | Ce champ est facultatif. S'il est utilisé, il retourne les produits recommandés disponibles dans les emplacements listés (une liste d'ID d'emplacements séparées par des virgules). |
| limit | Number | Ce champ est optionnel. Nombre maximum de produits recommandés. |
| exclude\_brands | Number | Ce champ est facultatif. Liste de marques, séparées par des virgules, à exclure de la recommandation. |

**API response**

La fonction de rappel reçoit l'objet de réponse de l'API avec les valeurs suivantes.

| Name | Type | Description |
| - | - | - |
| html | String | Le code HTML du bloc. Personnalisez le modèle HTML dans le compte personnel Kameleoon. |
| title | String | Le titre du bloc. Correspond à la valeur de l'élément « Action » dans les règles du bloc. |
| products | Array | Liste d’identifiants de produits. |
| id | Number | Identifiant unique du bloc. Correspond à l'ID du bloc dans la liste des blocs du compte personnel Kameleoon |

## obtainInstantSearchProducts

La méthode `obtainInstantSearchProducts()` récupère les résultats de recherche instantanée personnalisés de Kameleoon Search via un appel serveur asynchrone.

```javascript theme={null}
Kameleoon.API.Products.obtainInstantSearchProducts(
 {
  search_query: "To be or not to be"
 },
 function (response) {
  // la fonctionnalité de rendu d'un bloc à partir de la recherche instantanée
 },
 function (error) {
  // to handle when something goes wrong
 }
);
```

**Arguments**

| Name | Type | Description |
| - | - | - |
| search\_query | String | Requête de recherche fournie par l'utilisateur. Ce champ est obligatoire. |
| successCallback | Function | Fonction de rappel recevant l'objet de réponse de l'API. Ce champ est obligatoire. |
| errorCallback | Function | Fonction de rappel exécutée en cas d'erreur. Ce champ est optionnel. |

**API response**

La fonction de rappel reçoit l'objet de réponse de l'API avec les valeurs suivantes. Dans le tableau, `[]` indique un tableau d'objets ; ainsi, `products[].name` correspond au nom de chaque produit.

| Name | Type | Description |
| - | - | - |
| search\_query | String | Requête de recherche. |
| categories | Array | Tableau contenant les informations sur les catégories. |
| categories\[].id | String | ID de la catégorie. |
| categories\[].name | String | Nom de la catégorie. |
| categories\[].url | String | URL de la catégorie. |
| categories\[].count | Number | Nombre de produits dans la catégorie. |
| filters | Array | Tableau contenant les informations sur les filtres. |
| filters\[].filter.count | Number | Nombre total de produits correspondant à ces paramètres. |
| filters\[].filter.values\[].value | String | Libellé de la valeur. |
| filters\[].filter.values\[].count | Number | Nombre de produits ayant ce paramètre. |
| html | String | Code HTML du bloc de produits. Vous personnalisez le modèle dans votre compte personnel Kameleoon. |
| price\_range | Object | Prix minimum et maximum des produits. |
| price\_range.min | Number | Prix minimum. |
| price\_range.max | Number | Prix maximum. |
| products | Array | Tableau contenant les informations sur les produits. |
| products\[].description | String | Description du produit. |
| products\[].url | String | URL absolue du produit. |
| products\[].url\_handle | String | URL relative du produit. |
| products\[].picture | String | URL de l'image du produit dans le stockage Kameleoon. |
| products\[].name | String | Nom du produit. |
| products\[].price | Number / int | Prix du produit. |
| products\[].price\_full | Number / float | Prix du produit. |
| products\[].price\_formatted | String | Prix du produit avec la devise. |
| products\[].price\_full\_formatted | String | Prix du produit avec la devise. |
| products\[].image\_url | String | URL absolue de l'image du produit dans le stockage Kameleoon. |
| products\[].image\_url\_handle | String | URL relative de l'image du produit dans le stockage Kameleoon. |
| products\[].image\_url\_resized | Array | URL des versions redimensionnées de l'image du produit. |
| products\[].currency | String | Devise du produit. Correspond à la devise de votre compte personnel Kameleoon, ou à une valeur personnalisée définie dans les paramètres de la boutique de ce compte. |
| products\[].id | String | ID du produit. |
| products\[].old\_price | Number / int | Ancien prix du produit. La valeur par défaut est 0. |
| products\[].old\_price\_full | Number / float | Ancien prix du produit. |
| products\[].old\_price\_formatted | String | Ancien prix du produit avec la devise. |
| products\[].old\_price\_full\_formatted | String | Ancien prix du produit avec la devise. |
| products\[].categories | Array | Catégories du produit. Incluses uniquement lorsque la requête transmet le paramètre `extended`. |
| products\[].categories\[].id | String | ID de la catégorie. |
| products\[].categories\[].name | String | Nom de la catégorie. |
| products\[].categories\[].parent\_id | String | ID de la catégorie parente. |
| products\[].categories\[].url | String | URL de la catégorie. |
| products\[].categories\[].category\_ids | Array | ID des catégories du produit. |
| search\_query\_redirects | Array | Tableau contenant les informations sur les redirections. |
| search\_query\_redirects\[].query | String | Requête de recherche. |
| search\_query\_redirects\[].redirect\_link | String | URL de la redirection. |
| search\_query\_redirects\[].deep\_link | String | URL destinée aux applications mobiles. |
| products\_total | Number | Nombre total de produits. |

## obtainFullSearchProducts

Utilisez la méthode `obtainFullSearchProducts()` pour récupérer les résultats de recherche complets de la solution Kameleoon Search avec options de filtrage.

```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) {
  // la fonctionnalité de rendu d'un bloc à partir de la recherche complète
 },
 function (error) {
  // when something went wrong
 }
);
```

**Arguments**

| Name | Type | Description |
| - | - | - |
| search\_query | Object | Requête de recherche fournie par l'utilisateur et paramètres de filtre optionnels. Consultez les paramètres de filtrage dans la section suivante. Ce champ est obligatoire. |
| successCallback | Function | Fonction de rappel recevant l'objet de réponse de l'API. Ce champ est obligatoire. |
| errorCallback | Function | Fonction de rappel exécutée en cas d'erreur. Ce champ est optionnel. |

### Paramètres de filtrage des résultats

| Name | Type | Description |
| - | - | - |
| search\_query | String | Requête de recherche. Ce champ est obligatoire. |
| limit | Number | Limite des résultats. Ce champ est optionnel. |
| offset | Number | Décalage des résultats. Ce champ est optionnel. |
| category\_limit | Number | Nombre de catégories du filtre de barre latérale à retourner. Ce champ est optionnel. |
| categories | Array | Liste de catégories séparées par des virgules à filtrer. Ce champ est optionnel. |
| extended | Number | Définir sur `true` pour les résultats de recherche complets. |
| sort\_by | String | Paramètre de tri : `popular`, `price`, `discount`, `sales_rate`, `date`. Ce champ est optionnel. |
| order | String | Direction de tri : asc ou desc (par défaut). Ce champ est optionnel. |
| locations | Array | Liste de codes de localisation séparés par des virgules. Ce champ est optionnel. |
| brands | Array | Liste de marques séparées par des virgules à filtrer. Ce champ est optionnel. |
| filters | String | Chaîne JSON échappée facultative avec les paramètres de filtre. Par exemple: `{"bluetooth":["yes"],"offers":["15% cashback"],"weight":["1.6"]}`. Ce champ est facultatif. |
| price\_min | Number | Prix minimum. Ce champ est optionnel. |
| price\_max | Number | Prix maximum. Ce champ est optionnel. |
| colors  false | Array | Liste de couleurs séparées par des virgules. Ce champ est optionnel. |
| fashion\_sizes | Array | Liste de tailles séparées par des virgules. Ce champ est optionnel. |
| exclude | Array | Liste de codes de produits séparés par des virgules à exclure des résultats de recherche. Ce champ est optionnel. |
| email | String | Réservé uniquement à l'intégration S2S, lorsque le service ne dispose pas de la session de l'utilisateur. Le SDK mobile ne l'utilise pas. Ce champ est facultatif. |
| no\_clarification | Boolean | Désactive la recherche clarifiée. La valeur par défaut est **false**. N'utilisez pas ce paramètre, sauf si le support Kameleoon vous le demande. |
| merchants | Array | Liste de commerçants séparés par des virgules. Ce champ est optionnel. |
| filters\_search\_by | String | Options disponibles pour le filtre : `name`, `quantity`, `popularity`. Ce champ est optionnel. |

**API response**

La fonction de rappel reçoit l'objet de réponse de l'API avec les valeurs suivantes. Dans le tableau, `[]` indique un tableau d'objets ; ainsi, `products[].name` correspond au nom de chaque produit.

| Name | Type | Description |
| - | - | - |
| search\_query | String | Requête de recherche saisie par l'utilisateur. |
| brands | Array | Tableau contenant les informations sur les marques. |
| brands\[].name | String | Nom de la marque. |
| brands\[].picture | String | Image de la marque. |
| categories | Array | Tableau contenant les informations sur les catégories. |
| categories\[].alias | String | Alias de la catégorie. |
| categories\[].id | String | ID de la catégorie. |
| categories\[].name | String | Nom de la catégorie. |
| categories\[].parent | String | ID de la catégorie parente. |
| categories\[].url | String | URL de la catégorie. |
| filters | Array | Tableau contenant les informations sur les filtres. |
| filters\[].filter.count | Number | Nombre total de produits correspondant à ces paramètres. |
| filters\[].filter.values\[].value | String | Libellé de la valeur. |
| filters\[].filter.values\[].count | Number | Nombre de produits ayant ce paramètre. |
| html | String | Code HTML du bloc de produits. Vous personnalisez le modèle dans votre compte personnel Kameleoon. |
| price\_range | Object | Prix minimum et maximum des produits. |
| price\_range.min | Number | Prix minimum. |
| price\_range.max | Number | Prix maximum. |
| products | Array | Tableau contenant les informations sur les produits. |
| products\[].brand | String | Marque du produit. |
| products\[].currency | String | Devise du produit. Correspond à la devise de votre compte personnel Kameleoon, ou à une valeur personnalisée définie dans les paramètres de la boutique de ce compte. |
| products\[].id | String | ID du produit. |
| products\[].is\_new | Boolean | Propriété du produit. La valeur par défaut est null. |
| products\[].name | String | Nom du produit. |
| products\[].old\_price | String | Ancien prix du produit. La valeur par défaut est 0. |
| products\[].picture | String | URL de l'image du produit dans le stockage Kameleoon. |
| products\[].price | Number | Prix du produit. |
| products\[].price\_formatted | String | Prix du produit avec la devise. |
| products\[].url | String | URL du produit. |
| products\[].barcode | String | Code-barres du produit. Inclus uniquement lorsque la requête transmet le paramètre `extended`. |
| products\[].categories | Array | Catégories du produit. |
| products\[].categories\[].id | String | ID de la catégorie. |
| products\[].categories\[].name | String | Nom de la catégorie. |
| products\[].categories\[].parent | String | ID de la catégorie parente. |
| products\[].params | Array | Informations sur les paramètres du produit. |
| products\[].params\[].key | String | Nom du paramètre. |
| products\[].params\[].values | Array | Valeurs du paramètre. |
| products\_total | Number | Nombre total de produits. |

## obtainProductInteractions

La méthode `obtainProductInteractions()` récupère les mesures d'interaction pour les produits suivis via `trackProductView()`, `trackTransaction()`, ou `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
);
```

**Arguments**

| Name | Type | Description |
| - | - | - |
| eans | Array | Codes de produits (sous forme de chaînes). Ce champ est obligatoire. |
| callback | Function | Fonction de rappel recevant les données du produit. Ce champ est obligatoire. |
| timeBegin | Number | Début de la plage de dates (horodatage en millisecondes UNIX). |
| timeEnd | Number | Fin de la plage de dates (horodatage en millisecondes UNIX). |

**API response**

| Name | Type | Description |
| - | - | - |
| eans | Array | Identifiant unique du produit. Chaque code de produit correspond à un objet contenant les mesures d'interaction. |
| views | integer | Nombre de fois où les visiteurs ont consulté le produit. |
| cartQuantities | integer | Nombre total de fois où les visiteurs ont ajouté le produit à leur panier. |
| boughtQuantities | integer | Nombre total de fois où les visiteurs ont acheté le produit. |

## obtainProductData

La méthode `obtainProductData()` récupère les informations sur le produit pour les éléments envoyés via `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: '' }}
```

**Arguments**

| Name | Type | Description |
| - | - | - |
| eans | Array | Codes de produits (sous forme de chaînes). Ce champ est obligatoire. |
| callback | Function | Fonction de rappel recevant les données du produit. Ce champ est obligatoire. |
| parameters | Object | Paramètres facultatifs pour récupérer des champs spécifiques. Valeur par défaut `{ all: true }`. |

**API response**

| Name | Type | Description |
| - | - | - |
| eans | Array | Identifiant unique du produit. Chaque code de produit correspond à un objet contenant les mesures d'interaction. |
| productData | Object | [Objet Product](https://docs.kameleoon.com/fr/developer-docs/apis/activation-api-js/api-reference/objects/goal-segment-trigger-and-product.md#product). Ce champ reçoit le même objet que celui envoyé par `trackProductView`. |

## obtainRecommendedCollections

The `obtainRecommendedCollections()` method retrieves products de la specified collection.

```javascript theme={null}
Kameleoon.API.Products.obtainRecommendedCollections("123456", collections => {
    /* La fonctionnalité de rendu d'un bloc de collection de produits */
    console.log("collections", collections);
}, error => {
    /* Error handling logic if something goes wrong */
});
```

**Arguments**

| Name | Type | Description |
| - | - | - |
| collectionId | String | ID de la collection de produits, disponible dans la section Product Collections du tableau de bord. |
| successCallback | Function | Fonction de rappel recevant l'objet de réponse de l'API. Ce champ est obligatoire. |
| errorCallback | Function | Fonction de rappel exécutée en cas d'erreur. Ce champ est optionnel. |

**API response**

**Products**

L'API retourne un tableau d'objets. Chaque objet du tableau `products` contient les éléments suivants:

| **Parameter** | **Type** | **Description** |
| - | - | - |
| name | String | Nom du product |
| url | String (URL) | URL de la page produit |
| description | String | Description du produit |
| category\_ids | Tableau de Strings | Liste des ID de catégories auxquelles le produit appartient |
| brand | String | Marque du produit |
| fashion\_feature | String | Fashion feature (e.g., `"adult"`) |
| fashion\_gender | String | Genre destiné au produit |
| sales\_rate | Integer | Product's sales rate |
| relative\_sales\_rate | Float | Taux de vente relatif aux autres produits |
| picture | String (URL) | URL de l'image principale du produit |
| categories | Tableau de Objects | Liste des category objects (system-defined structure) |
| price\_formatted | String | Formatted product price (e.g., `$29.99`) |
| price\_full\_formatted | String | Formatted full/original price |
| price | Float | Current product price |
| price\_full | Float | Prix d’origine (plein tarif) avant toute remise |
| image\_url | String (URL) | URL de l'image redimensionnée du produit |
| image\_url\_handle | String (URL) | Processed image URL (handle-based) |
| image\_url\_resized | String (URL) | Resized image URL |
| url\_handle | String | Poignée URL utilisée pour accéder au produit dans la collection |
| currency | String | Code devise utilisé pour le prix du produit (par exemple, `USD`, `EUR`) |
| id | String | ID du produit (numérique ou chaîne selon le système) |
| html | String (HTML) | Le modèle HTML sélectionné lors de la création de la collection |