Recommendations Functions

The Recommendations drop-in provides API functions that enable you to programmatically control behavior, fetch data, and integrate with Adobe Commerce backend services.

Function	Description
getRecommendationsByUnitIds	Retrieves product recommendations based on various parameters such as current SKU, recommendation ID, and user history.
getRecommendationsByUnits	Retrieves product recommendations for one or more units, selected by unit IDs or labels.
publishRecsItemAddToCartClick	Publishes an event when a user adds a recommended product to their cart, used for tracking recommendation performance.

getRecommendationsByUnitIds

The getRecommendationsByUnitIds function retrieves product recommendations based on various parameters such as current SKU, recommendation ID, and user history. It calls the recommendationsByUnitIds GraphQL query and transforms the response into a standardized format.

const getRecommendationsByUnitIds = async (
  params: GetRecommendationsProps
): Promise<RecommendationUnitModel[] | null>

Parameter	Type	Req?	Description
params	GetRecommendationsProps	Yes	Parameters for retrieving recommendations including `pageType` (where recommendations are shown), `currentSku` (product being viewed), `cartSkus` (items in cart), `userPurchaseHistory` (previous purchases), and `userViewHistory` (previously viewed products).

Events

Emits the recommendations/data event with the transformed recommendations data as the payload.

Returns

Returns an array of RecommendationUnitModel objects or null.

getRecommendationsByUnits

The getRecommendationsByUnits function retrieves product recommendations for one or more recommendation units, selected by unit IDs or labels. It calls the recommendations GraphQL query and transforms the response into a standardized format.

const getRecommendationsByUnits = async (
  params: GetRecommendationsByUnitsProps
): Promise<RecommendationUnitModel[] | null>

Parameter	Type	Req?	Description
params	GetRecommendationsByUnitsProps	Yes	Parameters for retrieving recommendations. Includes selector (required, an object with unitIds and/or labels that identifies the units to fetch) and optional context: currentSku, cartSkus, userPurchaseHistory, userViewHistory, and currentProduct.

Events

Emits the recommendations/data event with the transformed recommendations data as the payload.

Returns

Returns an array of RecommendationUnitModel objects or null.

publishRecsItemAddToCartClick

The publishRecsItemAddToCartClick function publishes an event when a user adds a recommended product to their cart, used for tracking recommendation performance.

const publishRecsItemAddToCartClick = async (
  params: PublishParams
): any

Parameter	Type	Req?	Description
params	PublishParams	Yes	Parameters for the add-to-cart event including the recommended product details and recommendation unit information.

Examples

From product recommendations block:

import { publishRecsItemAddToCartClick } from '@dropins/storefront-recommendations/api';

publishRecsItemAddToCartClick({
  recommendationUnit,
  pagePlacement: 'product-list',
  yOffsetTop: addToCart.getBoundingClientRect().top ?? 0,
  yOffsetBottom:
  addToCart.getBoundingClientRect().bottom ?? 0,
  productId: ctx.index,
})

Events

Does not emit any drop-in events.

Returns

Returns void.

Data Models

The following data models are used by functions in this drop-in.

RecommendationUnitModel

The RecommendationUnitModel object is returned by the following functions: getRecommendationsByUnitIds, getRecommendationsByUnits.

interface RecommendationUnitModel {
  displayOrder: number;
  pageType: PageType;
  title: string;
  items: Item[];
  totalProducts: number;
  typeId: string;
  unitId: string;
  unitName: string;
}