Recommendations

This is for:

Developer

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

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

    The child product that will become the new parent.

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.

summary

Creates a Summary sub-controller.

Returns Summary<S>: A Summary 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.

Summary<S>

Properties

  • state: State

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

  • 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.

HighlightKeyword

Properties

  • length: number

    The length of the offset.

  • offset: number

    The 0 based offset inside the string where the highlight should start.

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.

  • ec_brand: string | null

    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_color: string | null

    The color of the product.

  • ec_description: string | null

    The description of the product.

    From the ec_description field.

  • ec_gender: string | null

    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 | null

    Whether the product is currently in stock.

    From the ec_in_stock field.

  • ec_item_group_id: string | null

    The ID used for the purpose of product grouping.

    From the ec_item_group_id field.

  • ec_listing: string | null

    The listing that the product belongs to.

  • ec_name: string | null

    The name of the product.

    From the ec_name field.

  • ec_price: number | null

    The base price of the product.

    From the ec_price field.

  • ec_product_id: string | null

    The product ID.

  • ec_promo_price: number | null

    The promotional price of the product.

    From the ec_promo_price field.

  • ec_rating: number | null

    The product rating, from 0 to 10.

    From the ec_rating field.

  • ec_shortdesc: string | null

    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.

  • permanentid: string

    The SKU of the product.

  • totalNumberOfChildren: number | null

    The total number of child products fetched through product grouping.

  • excerpt?: string | null

    The contextual excerpt generated for the product.

  • excerptsHighlights?: HighlightKeyword[]

    The length and offset of each word to highlight in the product excerpt string.

  • nameHighlights?: HighlightKeyword[]

    The length and offset of each word to highlight in the product name.

Unsubscribe

Call signatures

  • (): void;