Build your recommendation interface

This is for:

Developer

In this article

Using the Recommendations controller
Recommendations based on configured strategy

After creating a recommendation slot configuration, use the endpoint to retrieve items for your recommendation slots.

Although there are several possible approaches for building your recommendation interface, this article focuses on using Coveo Headless.

Using the `Recommendations` controller

You can use the Headless Recommendations controller to retrieve recommendations.

You can also use the Recommendations controller and its sub-controllers to assemble recommendations interfaces in your project.

A complete example, including a sample implementation of the recommendation interface, is available in the Headless repository.

Initialize the controller

Each Recommendations controller must point to a specific recommendation slot configuration through the slotId, which is defined when initializing the controller. There can be multiple recommendation interfaces on the same page, each pointing to a different recommendation slot and thus using a different controller instance.

The slotId is the unique identifier of the slot you want to retrieve recommendations for. This corresponds to the id field of the recommendation slot configuration you’ve created.

Do the following to initialize the Recommendations controller:

import { engine } from './Engine';
import {buildRecommendations} from '@coveo/headless-commerce';

const recommendationsController = buildRecommendations(engine, { 
    options: {slotId: 'af4fb7ba-6641-4b67-9cf9-be67e9f30174'},
});

Create an instance of the Recommendations controller by passing the previously initialized engine instance and the options object, which contains the slotId of the slot that you want to retrieve recommendations for.

Note

Depending on the seedType used in the recommendation slot configuration, you might need to pass additional details in the options object. For more details, see Recommendations based on configured strategy.

The Recommendations controller provides a refresh method that you can call to fetch new recommendations for the slot.

Use the controller in a component

Once the controller is initialized, it can be used in a component to display recommendations:

import {Cart, Recommendations} from '@coveo/headless/commerce';
import {useEffect, useState} from 'react';
import ProductList from '../../product-list/product-list';
import Pagination from '../pagination/pagination';

interface IRecommendationsInterfaceProps {
  recommendationsController: Recommendations; 
  cartController: Cart;
  navigate: (pathName: string) => void;
}

export default function RecommendationsInterface(
  props: IRecommendationsInterfaceProps
) {
  const {recommendationsController, cartController, navigate} = props;

  const [recommendationsState, setRecommendationsState] = useState(
    recommendationsController.state
  );

  useEffect(() => { 
    recommendationsController.subscribe(() => {
      setRecommendationsState(recommendationsController.state);
    });
  }, [recommendationsController]);

  return (
    <div className="RecommendationsInterface">
      <h3 className="RecommendationsHeadline">
        {recommendationsState.headline} 
      </h3>
      <ProductList 
        products={recommendationsState.products}
        cartController={cartController}
        controllerBuilder={recommendationsController.interactiveProduct}
        navigate={navigate}
      />
      <Pagination controller={recommendationsController.pagination()} /> 
    </div>
  );
}

	Pass an instance of the `Recommendations` controller. This controller and its sub-controllers will be used to fetch and display the recommendations.
	Subscribe to the controller state to update the component when the recommendations change.
	Display the `headline` returned by the recommendation slot.
	Access the current recommendations by reading the `products` field from the controller state. This example uses a custom `ProductList` component to display the recommendations.
	Access the pagination sub-controller to display pagination controls.

Recommendations based on configured strategy

While creating the recommendation slot configuration, you can specify a seedType to determine the strategy used to seed the recommendations. Seed types can have the following values:

unseeded
product
cart
purchased

The following sections describe how to fetch recommendations using Headless, based on the seedType used in the recommendation configuration.

Unseeded

If the seedType for your configuration is unseeded, you can initialize the Recommendations controller by passing in just the slotId.

Product

If the seedType for your configuration is product, you must pass an additional product ID to the options object to seed the recommendations with a specific product.

import { engine } from './Engine';
import {buildRecommendations} from '@coveo/headless-commerce';

const recommendationsController = buildRecommendations(engine, {
    options: {
        slotId: '<SLOT_ID>',
        productId: '<PRODUCT_ID>',
    },
});

Cart

If the seedType for your configuration is cart, you can initialize the Recommendations controller by passing in just the slotId.

Make sure you manage the cart state correctly with Headless. This will ensure that recommendation requests include the correct cart content.

You can verify this by checking that the Headless recommendation request to the Commerce API contains the correct cart content in the context.cart object.

Purchased

If the seedType for your configuration is purchased, you can initialize the Recommendations controller by passing in just the slotId.

Make sure you call the purchase method on the cart controller when you manage the cart state with Headless. This guarantees that recommendation requests are made with the correct history of purchased products.

You can verify this by checking that the Headless recommendation request to the Commerce API contains the correct purchase history in the context.purchased object.