Product Recommendations Deployment

Coveo Machine Learning (Coveo ML) Product Recommendations (PR) use usage analytics (UA) events to provide your customers with relevant and adaptive item suggestions.

This article describes the required steps to create and deploy Coveo ML PR in a Coveo for Commerce search interface created with the Coveo JavaScript Search Framework or the Coveo Headless library.

Product Recommendation Model Prerequisites

  1. Coveo Machine Learning (Coveo ML) Product Recommendations (PR) models use usage analytics (UA) events to relevantly target and suggest products to your customers. Therefore, you must ensure that your commerce interfaces track commerce usage analytics events.

  2. Depending on the recommendation strategy you want to leverage, ensure your commerce interface is tracking the proper events:

    Recommendation strategy Required events Optional events

    Cart recommender (cart)

    detail

    purchase

    None

    Frequently bought together (frequentlyBought)

    purchase

    refund

    add (to cart)

    remove (from cart)

    Frequently viewed together (frequentlyViewed)

    detail

    click

    Popular items (Bought) (popularBought)

    purchase

    refund

    Popular items (Viewed) (popularViewed)

    detail

    click

    User recommender (user)

    detail

    purchase

    refund

    add (to cart)

    remove (from cart)

If there are less than 100 events available for your PR model, the model is empty and doesn’t provide recommendations. With 100 events or more, your model starts to learn and improve.

Step 1: Create the Product Recommendation Model

Once you ensured that your commerce interface tracks the proper usage analytics events, you can create your Coveo ML PR model.

Step 2: Associate the Product Recommendation Model With a Query Pipeline

Once your model has been created, you must associate your model with a query pipeline and select an appropriate strategy.

Step 3: Query the Desired Product Recommendation Model

The procedure to query a Coveo ML Product Recommendations model differs depending on whether your commerce interface relies on the Coveo JavaScript Search Framework or on the Coveo Headless library.

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": {
               "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 on 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.

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>"}}

Ensure that your commerce interface sends the product category to Coveo Analytics.
brandFilter

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

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

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

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.

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>"}}

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

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

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

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

Render Recommendations with the Headless Library

The following instructions list the different steps required to leverage the headless library to implement a product recommendations component using a product recommendation controller. If you haven’t already installed Headless, access the Usage page to get started.

  1. Configure a headless engine for product recommendations.

    EXAMPLE
     // app/Engine.ts
 import {
   HeadlessEngine,
   productRecommendationsAppReducers,
 } from "@coveo/headless";
 export const productRecommendationsEngine = new HeadlessEngine({
   configuration: {
     ...
   },
   reducers: productRecommendationsAppReducers,
 });

  2. Initialize your controller.

    EXAMPLE
     // src/Components/MyPopularBoughtRecommendationsList.ts
 import {
   buildPopularBoughtRecommendationsList,
   PopularBoughtRecommendationsList
 } from "@coveo/headless";
 import { productRecommendationsEngine } from '../Engine';
 export const myPopularBoughtRecommendationsList: PopularBoughtRecommendationsList = buildPopularBoughtRecommendationsList(
   productRecommendationsEngine
 );

  3. You can now interact with it.

    EXAMPLE
     // src/Playground.ts
 import { myPopularBoughtRecommendationsList } from "../Components/MyPopularBoughtRecommendationsList";
 const unsubscribe = myPopularBoughtRecommendationsList.subscribe(() => {
   const state = myPopularBoughtRecommendationsList.state;
   // Use the state here
 });
 myPopularBoughtRecommendationsList.refresh();
   // Call `unsubscribe` only when the component is destroyed and you don't need the subscription anymore.
 unsubscribe();

    If the subscribe method is used on your specific framework, refer to Subscribe to controller state changes.

The following is a complete example of a controller for items frequently bought together.

EXAMPLE
  import {
    HeadlessEngine,
    productRecommendationsAppReducers,
  } from "@coveo/headless";
  export const productRecommendationsEngine = new HeadlessEngine({
    configuration: {
      ...
    },
    reducers: productRecommendationsAppReducers,
  });
  import {
    buildFrequentlyBoughtTogetherList,
    FrequentlyBoughtTogetherList
  } from "@coveo/headless";
  export const myFrequentlyBoughtTogetherList: FrequentlyBoughtTogetherList = buildFrequentlyBoughtTogetherList(
    productRecommendationsEngine
  );
  const unsubscribe = myFrequentlyBoughtTogetherList.subscribe(() => {
    const state = myFrequentlyBoughtTogetherList.state;
    // Use the state here
  });
  myFrequentlyBoughtTogetherList.setSku(<YOUR_ITEM_SKU>);
  myFrequentlyBoughtTogetherList.refresh();
    // Call `unsubscribe` only when the component is destroyed and you don't need the subscription anymore.
  unsubscribe();

Where you would replace <YOUR_ITEM_SKU> with the actual sku.

Product Recommendation Controllers

The following table shows the headless controller of each ML PR strategy:

Controller Strategy

CartRecommendationsList

Cart Recommender

FrequentlyBoughtTogetherList

Frequently Bought Together

FrequentlyViewedTogetherList

Frequently Viewed Together

PopularBoughtRecommendationsList

Popular Items (Bought)

PopularViewedRecommendationsList

Popular Items (Viewed)

UserInterestRecommendationsList

User Recommender
Recommended Articles