diff --git a/src/content/docs/dropins/recommendations/containers/product-list.mdx b/src/content/docs/dropins/recommendations/containers/product-list.mdx index 0fdadc9e9..509a49bd6 100644 --- a/src/content/docs/dropins/recommendations/containers/product-list.mdx +++ b/src/content/docs/dropins/recommendations/containers/product-list.mdx @@ -1,12 +1,13 @@ --- title: ProductList container -description: Show Adobe Commerce product recommendations for the active SKU using routing callbacks plus recId and placement configuration. +description: Show Adobe Commerce product recommendations using recId, optional currentProduct context, routing callbacks, and placement configuration. --- import Diagram from '@components/Diagram.astro'; import OptionsTable from '@components/OptionsTable.astro'; +import Aside from '@components/Aside.astro'; -The `ProductList` container manages and displays a list of recommended products based on the current product. Its behavior is driven by configuration options such as `currentSku`, `recId`, and `routing` through `routeProduct` callbacks. +The `ProductList` container manages and displays a list of recommended products based on the current product. Its behavior is driven by configuration options such as `currentProduct`, `recId`, and routing through `routeProduct` callbacks. ![ProductList container](@images/dropins/recommendations/product-list.png) @@ -21,7 +22,8 @@ The `ProductList` container provides the following configuration options: options={[ ['Option', 'Type', 'Req?', 'Description'], ['recId', 'string', 'Yes', 'Unique identifier for the recommendation unit.'], - ['currentSku', 'string', 'Yes', 'Current SKU for recommendation context.'], + ['currentProduct', 'object', 'No', 'Current product context (`{ sku: string; price?: number }`). See [Product context](#product-context).'], + ['currentSku', 'string', 'No', 'Deprecated as of v4.0.3. Use `currentProduct` instead.'], ['cartSkus', 'string[]', 'No', 'Cart SKUs for recommendation context.'], ['userPurchaseHistory', 'any[]', 'No', 'User Purchase History for recommendation context.'], ['userViewHistory', 'any[]', 'No', 'User View History for recommendation context.'], @@ -33,12 +35,44 @@ The `ProductList` container provides the following configuration options: ]} /> + + +## Product context + +Pass product context with the optional `currentProduct` prop: + +```ts +currentProduct?: { sku: string; price?: number }; +``` + +How context is supplied depends on where the unit is rendered: + +- **PDP pages**: The Commerce boilerplate block reads `currentProduct` from the Adobe Client Data Layer (ACDL) product context. You do not need to pass `currentProduct` in block configuration. +- **Non-PDP pages**: Set `currentsku` and/or `currentprice` in the [product-recommendations block configuration](/merchants/content-customizations/product-recommendations/#configuration) table to provide product context explicitly. +- **Context-free units**: If neither `currentsku` nor ACDL product context is available, `currentProduct` is `undefined`. The dropin still renders as long as `recId` is provided. + +## Query routing + +The container selects a GraphQL query based on the `currentProduct` shape: + +- When `currentProduct.price` is present (**Adobe Commerce Optimizer and Adobe Commerce as a Cloud Service only**), the container uses `GetRecommendationsByUnitIdsWithCurrentProduct`, which supports dynamic price filter operators. +- When only `currentProduct.sku` is present, or `currentProduct` is absent, the container uses `GetRecommendationsByUnitIds`, which is compatible with all backend types, including PaaS. + The `ProductListProps` interface has the following shape: ```ts export interface ProductListProps extends HTMLAttributes { recId: string; - currentSku: string; + currentProduct?: { + sku: string; + price?: number; + }; + /** @deprecated As of v4.0.3. Use `currentProduct` instead. */ + currentSku?: string; initialData?: { recommendations?: { results: RecommendationUnitModel[]; @@ -148,7 +182,7 @@ Each slot receives context data relevant to its purpose, allowing for highly cus ## Example configuration -The following example demonstrates how to render the `ProductList` container with the `recId`, `currentSku`, and `routeProduct` callbacks with different slots: +The following example demonstrates how to render the `ProductList` container with `recId`, `currentProduct`, and `routeProduct` callbacks with different slots: ```js @@ -156,7 +190,7 @@ The following example demonstrates how to render the `ProductList` container wit provider.render(ProductList, { recId: 'recommendation-unit-1', routeProduct: (item) => `/products/${item.urlKey}`, - currentSku: 'ADB150', + currentProduct: { sku: 'ADB150', price: 49.99 }, hideHeading: false, slots: { // Example of how to prepend or append to the default Heading @@ -227,7 +261,7 @@ provider.render(ProductList, { ## Key Features -- **Automatic Data Fetching**: Fetches recommendations based on `currentSku` and other context +- **Automatic Data Fetching**: Fetches recommendations based on `currentProduct` (or legacy `currentSku`) and other context - **Intersection Observer**: Automatically tracks when recommendations are viewed - **Event Publishing**: Publishes render and view events for analytics - **Loading States**: Handles loading states during data fetching diff --git a/src/content/docs/merchants/content-customizations/product-recommendations.mdx b/src/content/docs/merchants/content-customizations/product-recommendations.mdx index ae927ba72..8cbcd3d5f 100644 --- a/src/content/docs/merchants/content-customizations/product-recommendations.mdx +++ b/src/content/docs/merchants/content-customizations/product-recommendations.mdx @@ -23,24 +23,31 @@ Add this table to your document to configure the block: product-recommendations -currentSku +recId +2ed7ea09-d9bd-4691-91c3-2c0a6d4fd869 (example) + + +currentsku crz-eco-tr-std-2017 (example) -recId -2ed7ea09-d9bd-4691-91c3-2c0a6d4fd869 (example) +currentprice +49.99 (example) -- **recId**: Recommendation ID for targeting specific recommendation types. Required for all pages. No default value. +- **recId**: Recommendation unit ID from the Admin. Required for all pages. + +- **currentsku**: Current product SKU. Required on non-PDP pages when the recommendation unit needs product context. On PDP pages, the boilerplate reads this automatically from the product context (Adobe Client Data Layer). -- **currentSku**: Current product SKU for recommendation context. Required for non-PDP pages only. Not needed for product detail pages. No default value. +- **currentprice**: Current product price (numeric). Required on non-PDP pages when using dynamic price filter operators (Adobe Commerce Optimizer and Adobe Commerce as a Cloud Service only). On PDP pages, the boilerplate reads this automatically from the product context. @@ -123,9 +130,9 @@ You can configure each page to display a specific recommendation unit by setting :::note - PDP pages require only the `recId` to be set as shown above. + PDP pages require only `recId`, as shown above. - Other pages require both the `recId` and `currentSku` to be set. For example: + Other pages that need product context require `recId` and `currentsku`. For example: @@ -133,13 +140,35 @@ You can configure each page to display a specific recommendation unit by setting - + + + + + + +
product-recommendations
currentSkurecId2ed7ea09-d9bd-4691-91c3-2c0a6d4fd869
currentsku crz-eco-tr-std-2017
+ + When using dynamic price filter operators on Adobe Commerce Optimizer or Adobe Commerce as a Cloud Service, set `currentprice` on non-PDP pages: + + + + + + + + + + + + + +
product-recommendations
recId 2ed7ea09-d9bd-4691-91c3-2c0a6d4fd869
currentskucrz-eco-tr-std-2017
currentprice49.99