Query a Product Recommendation model with Headless
Query a Product Recommendation model with Headless
This article describes how to query a Product Recommendation (PR) model with the Coveo Headless library.
Configure your pipeline
To receive recommendations through Headless, you must ensure that your request is routed to the proper query pipeline and targets the correct model association within that pipeline.
To achieve this, your requests must fulfill two query pipeline conditions
Step 1: Target the proper query pipeline
To render recommendations, your request must trigger the pipeline that’s associated with the Product Recommendation (PR) model.
A query pipeline can be targeted by adding a query pipeline condition to it.
You can choose one or more of the following mechanisms to trigger the condition on your pipeline, depending on your specific requirements:
Search Hub
The search hub is a query parameter that indicates the name of the search interface from which the query originates. This parameter can be used to trigger a query pipeline condition.
First, from within the Coveo Administration Console, navigate to the Query Pipelines (platform-ca | platform-eu | platform-au) page. Double-click your pipeline and define a Condition by choosing SearchHub from the dropdown menu.
Next, you must ensure that the requests made with Headless use the same value as the one defined in the condition. This can be achieved in two ways:
Context
You can send custom context information with Headless to determine if a pipeline condition is triggered. For example:
First, navigate to the Query Pipelines (platform-ca | platform-eu | platform-au) page from within the Administration Console.
Double-click your pipeline and define a Condition by choosing Context from the dropdown menu.
Specify the Context Key as website
and the value as sports
.
Now, using the Context
controller, set the context for your Headless engine:
import {buildContext} from '@coveo/headless';
import {engine} from './Engine.ts'
export function Context() {
const ctx = buildContext(engine);
ctx.set({'website': 'sports'})
}
Step 2: Trigger the model associated within the pipeline
Once the Headless request is routed to the proper pipeline, you must ensure that the request triggers the correct machine learning model association in the pipeline, as many models can be associated to that pipeline.
This can be done with the recommendation
parameter.
When sending a PR request to the Search API with Headless, the controller automatically populates the recommendation
parameter with the identifier of the recommendation interface from which the request originates.
The value assigned to this field depends on which Headless controller you use.
You can add a condition to your query pipeline to trigger the correct machine learning model when the recommendation
field is populated with a specific value.
Let’s take a look at how this can be done using the Frequently bought together strategy and thus the FrequentlyBoughtTogetherList
controller.
Search API requests sent with this controller will populate the recommendation
field with the frequentBought
type value.
To ensure the correct model gets triggered on this request, choose Recommendations when creating the condition and set the value of the condition to be frequentBought
.
For more details on which controller maps to which type, see the reference documentation.
Render recommendations with Headless
You can use various Headless engines to implement a product recommendations component for your commerce implementation. If you haven’t already installed Headless, access the Usage page to get started.
|
Note
Headless can be used with any JavaScript/TypeScript framework or no framework at all. However, this article makes heavy use of the React library. If you have experience developing in a front-end framework that isn’t React, consult the React documentation. |
Depending on which PR strategy you are trying to implement, you will either have to use the ProductRecommendations
or the Recommendations
engine.
Some common PR strategies have a dedicated ProductRecommendation
(PR) controller.
A list of strategies for which a controller exists can be found within the reference documentation.
If a dedicated controller doesn’t exist for the strategy you are trying to implement, you will have to use the Recommendation
engine.
ProductRecommendation engine
-
Configure a headless engine for product recommendations.
import { buildProductRecommendationEngine, ProductRecommendationEngine, } from "@coveo/headless/product-recommendation";
export const productRecommendationsEngine: ProductRecommendationEngine = buildProductRecommendationEngine({
configuration: {
accessToken: "xxc23ce82a-3733-496e-b37e-9736168c4fd9", organizationId: "electronicscoveodemocomo0n2fu8v", }, });
Import the required builder function and data type from the @coveo/headless/product-recommendation
package.Use a builder function to initialize a PR engine. Specify the configuration
options of your engine. These determine how the engine connects to your Coveo organization. For now, we’re using a demo configuration so that you already have some data to work with.NoteThe query pipeline defined for the demo organization is triggered by requests whose
Recommendation
parameter is populated. -
import { productRecommendationsEngine } from "./Engine";
import { FrequentlyViewedTogetherList, buildFrequentlyViewedTogetherList, } from "@coveo/headless/product-recommendation"; export const frequentlyViewedTogether: FrequentlyViewedTogetherList = buildFrequentlyViewedTogetherList(productRecommendationsEngine, {
options: { maxNumberOfRecommendations: 4, }, });
Import the engine initialized above. Use the buildFrequentlyViewedTogetherList
function to create an instance of theFrequentlyViewedTogetherList
controller. The controller requires the engine you initialized insrc/Engine.ts
in addition to anoptions
object, which specifies the number of recommendations.Headless PR controllers return recommendations using the product’s
SKU
attribute. A SKU is a unique ID that distinguishes each product variant from all other variants.In order to get recommendations, call the
setSkus
method on the controller. This method will update the controller’s state with recommendations based on theSKU
passed to it. -
Create a component that utilizes the controller.
import { FrequentlyViewedTogetherList, ProductRecommendation, loadClickAnalyticsActions, } from "@coveo/headless/product-recommendation"; import { useEffect, useState } from "react"; import { productRecommendationsEngine } from "../Engine"; interface FreqViewedTogetherProps {
controller: FrequentlyViewedTogetherList; productID: string; } export const FreqViewedTogether: React.FC<FreqViewedTogetherProps> = ( props ) => { const { controller, productID } = props; const [state, setState] = useState(controller.state); useEffect(() => {
controller.subscribe(() => setState(controller.state)); controller.refresh(); }, [controller]); if (state.error) { return null; } const logClick = (recommendation: ProductRecommendation) => {
if (!productRecommendationsEngine) { return; } const { logProductRecommendationOpen } = loadClickAnalyticsActions( productRecommendationsEngine ); productRecommendationsEngine.dispatch( logProductRecommendationOpen(recommendation) ); }; controller.setSkus([productID]);
return ( <div className="recs-list"> <h2>People also viewed</h2> <ul> {state.recommendations.map((recommendation) => {
return ( <li key={recommendation.permanentid}> <h2>
<a onClick={() => logClick(recommendation)} onContextMenu={() => logClick(recommendation)} onMouseDown={() => logClick(recommendation)} onMouseUp={() => logClick(recommendation)} > {recommendation.ec_name} </a> </h2> </li> ); })} </ul> </div> ); }; export default FreqViewedTogether;
Specify the FrequentlyViewedTogetherList
controller and theproductID
as props for this component. TheproductID
acts as the uniqueSKU
of the item you want to get recommendations for.Use the useEffect
hook to re-render the component every time the state of the controller changes by bindingcontroller.state
to the local state. Also call therefresh
method on the controller to get the latest recommendations.Define the logClick
function that dispatches an action which sends a click event when a recommendation is opened.Call the setSkus
method on the controller by passing in theproductID
of the items you wish to use to fetch recommendations. The controller will then return frequently viewed items with the given products. The recommendations returned by the controller are those items that would be frequently viewed with all the SKUs you specify here.Use the controller’s state to loop through the recommendations array to list the recommended products. Call the logClick
method defined above if the user interacts with the recommendation. -
Render the recommendations component.
To display recommendations on your page, use the
FreqViewedTogether
component created above by passing in the controller and theSKU
of the product you wish to render recommendations for:import FreqViewedTogether from "./components/FreqViewedTogether"; import { frequentlyViewedTogether as FreqViewedTogetherController } from "../controllers"; // . . . return ( {/* ... */} <FreqViewedTogether controller={FreqViewedTogetherController} productID={productID} /> {/* ... */} )
Recommendation Engine
To implement a recommendation strategy for which there is no dedicated ProductRecommendation
controller available, you can use the RecommendationList
controller.
While implementation of components using this controller is similar to those done via a PR controller, you do need to ensure that you specify an id
parameter for the RecommendationListOptions
object of the RecommendationList
controller.
We recommend using an id that represents the purpose of the recommendation component.
import { buildRecommendationList } from "@coveo/headless/recommendation"
import { recommendationEngine } from "./Engine.ts"
// . . .
const controller = buildRecommendationList(recommendationEngine, {
options: {
id: <MY_ID>
}
})
Specify the id parameter for the RecommendationListOptions object.
This Once sent with Headless, the ID can then be used within Administration Console to accurately trigger the model in your pipeline. |
Product Recommendation controllers
The following table shows the Headless Product Recommendations controller of each ML PR strategy:
Controller | Strategy | Recommendation type |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|