Recommendations

This is for:

Developer
Important

The Headless commerce engine, controllers, and actions are in open beta and therefore under active development. Reach out to your Coveo team for support in adopting them.

Example Implementation

recommendations.fn.tsx

import {Recommendations as HeadlessRecommendations} from '@coveo/headless/commerce';
import {useEffect, useState, FunctionComponent} from 'react';
 
interface RecommendationsProps {
  controller: HeadlessRecommendations;
}
 
export const Recommendations: FunctionComponent<RecommendationsProps> = (
  props
) => {
  const {controller} = props;
  const [state, setState] = useState(controller.state);
 
  useEffect(() => controller.subscribe(() => setState(controller.state)), []);
 
  if (!state.products.length) {
    return <button onClick={() => controller.refresh()}>Refresh</button>;
  }
 
  return (
    <ul>
      {state.products.map(({ec_name, clickUri, permanentid}) => (
        <li key={permanentid}>
          <a href={clickUri}>{ec_name}</a>
        </li>
      ))}
    </ul>
  );
};
 
// usage
 
/**
 * ```tsx
 * const controller = buildRecommendations(engine);
 *
 * <Recommendations controller={controller} />;
 * ```
 */

The Recommendations controller exposes a method for retrieving recommendations content in a commerce interface.

Methods

promoteChildToParent

Finds the specified parent product and the specified child product of that parent, and makes that child the new parent. The children and totalNumberOfChildren properties of the original parent are preserved in the new parent.

This method is useful when leveraging the product grouping feature to allow users to select nested products.

E.g., if a product has children (such as color variations), you can call this method when the user selects a child to make that child the new parent product, and re-render the product as such in the storefront.

Note: In the controller state, a product that has children will always include itself as its own child so that it can be rendered as a nested product, and restored as the parent product through this method as needed.

Parameters

  • childPermanentId: string

    The permanentid of the child product that will become the new parent.

  • parentPermanentId: string

    The permanentid of the current parent product of the child product to promote.

refresh

Fetches the recommendations.

subscribe

Adds a callback that’s invoked on state change.

Parameters

  • listener: () => void

    A callback that’s invoked on state change.

Returns Unsubscribe: A function to remove the listener.

interactiveProduct

Creates an InteractiveProduct sub-controller.

Parameters

  • props: Omit<InteractiveProductCoreProps, 'responseIdSelector'>

    The properties for the InteractiveProduct sub-controller.

Returns InteractiveProduct: An InteractiveProduct sub-controller.

pagination

Creates a Pagination sub-controller.

Parameters

  • props: PaginationProps

    The optional properties for the Pagination sub-controller.

Returns Pagination: A Pagination sub-controller.

Attributes

state

A scoped and simplified part of the headless state that is relevant to the Recommendations controller.

Properties

  • error: CommerceAPIErrorStatusResponse | null

  • headline: string

  • isLoading: boolean

  • products: Product[]

  • responseId: string

Initialize

buildRecommendations

Creates a Recommendations controller instance.

Parameters

  • engine: CommerceEngine

    The headless commerce engine.

  • props: RecommendationsProps

    The configurable Recommendations controller properties.

Returns Recommendations

RecommendationsProps

The configurable Recommendations controller properties.

Properties

RecommendationsOptions

The options for the Recommendations controller.

Properties

  • slotId: string

    The unique identifier of the recommendations slot (e.g., b953ab2e-022b-4de4-903f-68b2c0682942).

  • productId?: string

    The unique identifier of the product to use for seeded recommendations.

Sub-controllers

Pagination

Properties

  • state: PaginationState

    A scoped and simplified part of the headless state that is relevant to the Pagination controller.

  • fetchMoreProducts: function

    Fetches the next page of products, and appends them to the current list of products.

  • nextPage: function

    Navigates to the next page.

  • previousPage: function

    Navigates to the previous page.

  • selectPage: function

    Navigates to a specific page.

    Parameters

    • page: number

      The page to navigate to.

  • setPageSize: function

    Sets the page size.

    Parameters

    • pageSize: number

      The page size.

  • subscribe: function

    Adds a callback that’s invoked on state change.

    Parameters

    • listener: () ⇒ void

      A callback that’s invoked on state change.

      Returns Unsubscribe: A function to remove the listener.

InteractiveProduct

Properties

  • warningMessage?: string

  • beginDelayedSelect: function

    Prepares to select the result after a certain delay, sending analytics if it was never selected before.

In a DOM context, it’s recommended to call this method on the touchstart event.

  • cancelPendingSelect: function

    Cancels the pending selection caused by beginDelayedSelect.

In a DOM context, it’s recommended to call this method on the touchend event.

  • select: function

    Selects the result, logging a UA event to the Coveo Platform if the result wasn’t selected before.

In a DOM context, it’s recommended to call this method on all of the following events: * contextmenu * click * mouseup * mousedown

PaginationProps

Properties

  • options?: Omit<CorePaginationOptions, 'slotId'>

PaginationState

Properties

  • page: number

  • pageSize: number

  • totalEntries: number

  • totalPages: number

Product

Properties

  • position: number

    The 1-based product’s position across the non-paginated result set.

    E.g., if the product is the third one on the second page, and there are 10 products per page, its position is 13 (not 3).

  • additionalFields: Record<string, unknown>

    The requested additional fields for the product.

  • children: Omit<BaseProduct, 'children' | 'totalNumberOfChildren'>

    The child products of the product, fetched through product grouping.

  • clickUri: string

    The URL of the product.

  • permanentid: string

    The SKU of the product.

  • totalNumberOfChildren: number

    The total number of child products fetched through product grouping.

  • ec_brand?: string

    The brand of the product.

    From the ec_brand field.

  • ec_category?: string

    The category of the product (e.g., "Electronics;Electronics|Televisions;Electronics|Televisions|4K Televisions").

    From the ec_category field.

  • ec_description?: string

    The description of the product.

    From the ec_description field.

  • ec_gender?: string

    The gender the product is intended for.

  • ec_images?: string[]

    The URLs of additional product images.

    From the ec_images field.

  • ec_in_stock?: boolean

    Whether the product is currently in stock.

    From the ec_in_stock field.

  • ec_item_group_id?: string

    The ID used for the purpose of product grouping.

    From the ec_item_group_id field.

  • ec_name?: string

    The name of the product.

    From the ec_name field.

  • ec_price?: number

    The base price of the product.

    From the ec_price field.

  • ec_product_id?: string

    The product ID.

  • ec_promo_price?: number

    The promotional price of the product.

    From the ec_promo_price field.

  • ec_rating?: number

    The product rating, from 0 to 10.

    From the ec_rating field.

  • ec_shortdesc?: string

    A short description of the product.

    From the ec_shortdesc field.

  • ec_thumbnails?: string[]

    The URLs of the product image thumbnails.

    From the ec_thumbnails field.

Unsubscribe

Call signatures

  • (): void;