Query a Product Recommendation model

This is for:

Developer

This article describes how to query a Product Recommendation (PR) model with the Coveo JavaScript Search Framework.

If you wish to query a PR model with the Coveo Headless library, see Query a Product Recommendation model with Headless.

In order to render recommendations with JSUI, you must have first completed the prerequiste steps described in Leverage Coveo Machine Learning Product Recommendations (PR).

Render recommendations in a JSUI search interface

Coveo ML PR offers different strategies to adapt its recommendations according to the current user context.

To leverage one of those strategies in your commerce solution, you must write code that:

  • Calls the Coveo Search API to query the desired ML PR model.

  • Renders the recommendations returned by the Coveo Search API.

    1. Use the JavaScript Search Framework to request and render recommendations.

      Example

      Here’s an example of a product page that renders a list of recommendations:

       <!DOCTYPE html>
       <html lang="en">
       <head>
         <!-- The product id is stored as metadata, which is retrieved later on. -->
         <!-- You may replace this with your own method of storage. -->
         <meta name="productid" content="123">
         <link rel="stylesheet" href="./css/CoveoFullSearch.css" />
         <script class="coveo-script" src="js/CoveoJsSearch.Lazy.js"></script>
         <script>
           document.addEventListener('DOMContentLoaded', function () {
             // The product id is retrieved.
             // You may replace this with your own method of retrieval.
             const productId = document.querySelector('meta[name="productid"]').content;
             // The search endpoint is configured here with the itemId parameter
             // because it leverages the Frequently bought together strategy.
             Coveo.SearchEndpoint.configureCloudV2Endpoint(
               <MY_ORGANIZATION_ID>,
               <MY_SEARCH_TOKEN>,
               "https://platform.cloud.coveo.com/rest/search",
               {
                "queryStringArguments": {
                  "mlParameters": JSON.stringify({
                    "itemId": productId
                  })
                }
              });
             const root = document.getElementById('coveoFrequentlyBoughtTogetherRecommendations');
             // The framework is initialized with a recommendation interface.
             Coveo.initRecommendation(root);
           })
         </script>
       </head>
       <body>
         <!-- ... -->
         <!-- The CoveoRecommendation component is a CoveoSearchInterface -->
         <!-- that displays recommendations. -->
         <div id="coveoFrequentlyBoughtTogetherRecommendations"
             class="CoveoRecommendation"
             data-pipeline="MyFrequentBoughtPipeline">
           <div class="coveo-recommendation-body">
             <div class="CoveoResultList">
               <!-- ... -->
             </div>
           </div>
         </div>
         <!-- ... -->
       </body>
       </html>
    2. Depending on the strategy used by the targeted ML PR model, the query may have to include additional ML query parameters. To learn which parameters need to be included, click the chosen strategy:

User recommender (user)

No additional ML query parameters need to be configured for the model to provide its recommendations.

Frequently bought together (frequentBought)

When leveraging the Frequently bought together strategy, you need to pass the input product SKU in the itemId ML query parameter for the model to provide its recommendations.

Example
{"mlParameters": {"itemId": "<ITEM_SKU>"}}

Frequently viewed together (frequentViewed)

When leveraging the Frequently viewed together strategy, you need to pass the input product SKU in the itemId ML query parameter for the model to provide its recommendations.

Example
{"mlParameters": {"itemId": "<ITEM_SKU>"}}

If the model is queried from a commerce interface where multiple items are shown, multiple SKUs can be provided by using the itemIds ML query parameter instead.

{"mlParameters": {"itemIds": ["<ITEM1_SKU>", "<ITEM2_SKU>", "<ITEM3_SKU>"]}}

Cart recommender (cart)

When leveraging the Cart recommender strategy, you need to pass the input product SKU in the itemIds ML query parameter for the model to provide its recommendations.

Example
{"mlParameters": {"itemIds": ["<ITEM1_SKU>", "<ITEM2_SKU>", "<ITEM3_SKU>"]}}

You can specify as many ITEM_SKU values as you want.

No additional ML query parameters need to be configured for the model to provide its recommendations.

However, you may want to filter the provided recommendations by specific category or brand. You can achieve this by passing the input product category and brand respectively in the categoryFilter and brandfilter ML query parameters.

Note

Currently, analytics data is used by the model to retrieve the product’s category and brand. In the future, this information will be retrieved from the commerce catalog directly.

categoryFilter

Passing the input product category in the categoryFilter ML query parameter:

{"mlParameters": {"categoryFilter": "<CATEGORY>"}}
Important

Ensure that your commerce interface sends the product category to Coveo Usage Analytics (Coveo UA)

brandFilter

Passing the input product brand in the brandFilter ML query parameter:

{"mlParameters": {"brandFilter": "<BRAND>"}}
Important

Make sure that your commerce interface sends the product brand to Coveo UA.

No additional ML query parameters need to be configured for the model to provide its recommendations.

However, you may want to filter the provided recommendations by specific category or brand. You can achieve this by passing the input product category and brand respectively in the categoryFilter and brandfilter ML query parameters.

Note

Currently, analytics data is used by the model to retrieve the product’s category and brand. In the future, this information will be retrieved from the commerce catalog directly.

categoryFilter

Passing the input product category in the categoryFilter ML query parameter:

{"mlParameters": {"categoryFilter": "<CATEGORY>"}}
Important

Make sure that your commerce interface sends the product category to Coveo UA.

brandFilter

Passing the input product brand in the brandFilter ML query parameter:

{"mlParameters": {"brandFilter": "<BRAND>"}}
Important

Make sure that your commerce interface sends the product brand to Coveo UA.