Leveraging Machine Learning Product Recommendations
Coveo Machine Learning (Coveo ML) Product Recommendations (PR) use usage analytics events to provide your customers with relevant and adaptive item (PR) suggestions.
This article describes the required steps to deploy Coveo ML PR in a Coveo for Commerce search interface created with the Coveo JavaScript Search Framework or the Coveo Headless library.
Configure a Product Recommendation Model
-
Ensure your commerce interfaces track commerce usage analytics events.
-
Create a PR model and associate it with the desired query pipeline.
- If rendering recommendations with the Headless library, refer to this more specific procedure instead of step 8 from the link above.
Associate the PR Model With a Query Pipeline
-
Ensure you’ve added your query pipeline with the condition
Recommendation is not empty
. -
Access the query pipeline with which you want to associate a Coveo ML model.
-
In the Machine Learning tab, click Associate model.
-
In the Associate a Machine Learning Model dialog that appears:
-
In the Model drop-down menu, select the desired model.
-
In the Select a condition drop-down menu, select a condition that requires the recommendation to be equal to the strategy that you’re using. If you don’t already have such a condition, then create one.
Condition value Strategy cart
Cart Recommender frequentlyBought
Frequently Bought Together frequentlyViewed
Frequently Viewed Together popularBought
Popular Items (Bought) popularViewed
Popular Items (Viewed) user
User Recommender -
Select the appropriate Strategy in the Advanced Configuration section.
-
-
Click Associate Model.
If you are using more than one strategy, you should repeat this process with the appropriate models and conditions.
Query the Desired Product Recommendation Model
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.
-
Use the JavaScript Search Framework to request and render recommendations.
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>
-
Depending on the strategy used by the targeted ML PR model, the query may have to include the following ML query parameters:
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.
{"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.
{"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.
{"mlParameters": {"itemIds": ["<ITEM1_SKU>", "<ITEM2_SKU>", "<ITEM3_SKU>"]}}
You can specify as many ITEM_SKU
values as you want.
Popular Items: Viewed (popularViewed
)
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.
Popular Items: Bought (popularBought
)
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 new 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.
-
Configure a headless engine for product recommendations.
// app/Engine.ts import { HeadlessEngine, productRecommendationsAppReducers, } from "@coveo/headless"; export const productRecommendationsEngine = new HeadlessEngine({ configuration: { ... }, reducers: productRecommendationsAppReducers, });
-
// src/Components/MyPopularBoughtRecommendationsList.ts import { buildPopularBoughtRecommendationsList, PopularBoughtRecommendationsList } from "@coveo/headless"; import { productRecommendationsEngine } from '../Engine'; export const myPopularBoughtRecommendationsList: PopularBoughtRecommendationsList = buildPopularBoughtRecommendationsList( productRecommendationsEngine );
-
You can now interact with it.
// 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.
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 |