docs
  1. Discovery
  2. Recommendations
  3. Rule-based Recommendations

Rule-Based Recommendations

Show a ranked product slider that needs no reference product. The product detail page ships a trending slider for the product's category, and your editors can place a smart sorting slider on any CMS page and pick the ranking rule in the CMS.

Why it matters

A "trending in this category" slider works from category data alone. The same ranking rules are available to your editors on homepages, landing pages and collection pages. They choose the rule, an optional category, an optional brand and a product count in the CMS, and your team ships no code for it.

Try it

Try it: Rule-based recommendations

Try the trending slider on a live product detail page.

Recording of the rule-based recommendations slider on a product detail page

What's included

  • Category recommendations: RecommendationsService.fetchCategoryRecommendations from @scayle/storefront/services fetches the products of one category in the order of a smart sorting key, leaves out one product you name, and caches the result.
  • Trending slider on the product detail page: The trendingProducts prop of the product detail page is a deferred prop, so the slider loads after the first render. The add-to-basket slide-in reuses the same products.
  • Smart sorting RPC for CMS blocks: The oRPC procedure cms.getProductsBySmartSorting in src/server/api/cms.ts returns ranked products for a smart sorting key and an optional category and brand. The client calls it through useRpcClient().
  • Smart sorting slider blocks: Each of the four supported CMS providers has a SmartSortingProductsSliderComponent that maps the block's fields to a query. All of them share the useCmsSmartSortingProducts composable, which calls the RPC.

What you can change

Configure

  • In your CMS, choose the smart sorting key, the category, the brand and the product count for each slider block.
  • In the SCAYLE Panel, give every product at least one category, because the trending slider on the product detail page ranks the product's deepest category.

Theme

  • Restyle the slider by editing SFProductSlider in src/client/components/product/slider/SFProductSlider.vue or the block component of your CMS provider in src/client/cms/providers/<provider>/components/SmartSortingProductsSliderComponent.vue.

Extend

  • Use a different sorting key or limit for the trending slider by editing fetchTrendingProducts in your ProductDetailController.
  • Subclass RecommendationsService, override fetchCategoryRecommendations, and register the subclass in the recommendations slot of src/server/registries.ts to change how the Storefront API is queried for the trending slider.
  • Transform or filter the products of every CMS slider block in useCmsSmartSortingProducts in src/client/cms/shared/useCmsSmartSortingProducts.ts. A change in the block component of one provider affects that provider only.
  • Change the cache time of the CMS slider with SMART_SORTING_CACHE_TTL_SECONDS and its brand filter in buildSmartSortingWhere, both in src/server/api/cms.ts.

Constraints and limits

Permanent

  • The Storefront API ranks the products. The Storefront Application V3 sorts nothing itself, so the order changes only through the sorting key or the key's setup in the SCAYLE Panel.
  • The trending slider leaves out the product you are viewing. The CMS RPC has no product to leave out, so it returns the first products of the ranking up to its limit.

Known limitations

  • The default ProductDetailController always asks for the TRENDING key and ten products. The SCAYLE documentation states that the Trending key only works with SCAYLE native Checkout, while the other system keys still work from the remaining variables without it. If your shop does not use SCAYLE native Checkout, switch the key with the guide below.
  • The trending slider needs a main category. The main category is the deepest category on the product's longest category path, so a product without any category gets no slider.
  • The trending slider can hold fewer products than the limit. The query asks for one extra product so it can drop the current one, then trims the list to the limit. A category with fewer products than the limit gives a shorter slider.
  • A failed Storefront API call gives an empty slider. For the trending slider, the controller logs the error and returns an empty list, so the slider is not rendered. For a CMS slider, useCmsSmartSortingProducts logs the error and the block shows no products.
  • The add-to-basket slide-in shows the first six trending products and only on a product detail page. On every other page it has no trendingProducts to show. A limit below six shrinks it.
  • The RPC accepts only the system Smart Sorting Keys, so a Custom Smart Sorting Key from the SCAYLE Panel fails validation. It also accepts only a limit from 1 to 100 and whole numbers for the category and the brand. A rejected request leaves the slider empty and logs an error.
  • A CMS slider without a smart sorting key sends no request and shows no products.
  • A CMS slider is empty when its filters match nothing.
  • The brand filter matches the product attribute with the key brand. If your shop stores the brand under another key, the filter finds nothing until you change ATTRIBUTE_KEY_BRAND in src/shared/constants/attributeKeys.ts. The product mappers read the same constant.
  • A new ranking, or a product that becomes sellable, reaches the page after the cached entry expires. The server caches the trending slider for up to 15 minutes and the CMS slider for up to 5 minutes, see Data cache TTLs. The products of a CMS slider are part of the server-rendered page, so on the cacheable routes for the home page and CMS content pages (600 seconds in cacheableRoutes in storefront.config.ts) a CDN that honors s-maxage can serve the old ranking for longer.

How it works

ProductDetailController calls the cached RecommendationsService for trending products. A CMS slider block calls the cached cms.getProductsBySmartSorting RPC. Both go to the Storefront API only on a cache miss.

On the product detail page, ProductDetailController returns trendingProducts as a deferred prop in the recommendations group, next to the similar products. The page renders first with a skeleton in place of the sliders, then the browser requests the group. The controller calls fetchCategoryRecommendations with the product's main category, the TRENDING key and a limit of ten. The signature is:

The service restricts the query to products that are sellable at the sellableAt time. It also passes the active campaign key to the Storefront API. A product that becomes sellable appears after the cached entry expires.

The CMS slider takes the other path. Each provider's block component turns its own fields into a CmsSmartSortingQuery and hands it to useCmsSmartSortingProducts. The composable calls cms.getProductsBySmartSorting and refetches whenever the query changes, for example during live preview. The block awaits the first fetch inside its Suspense boundary, so on a full page request the products are part of the server-rendered HTML. The Storyblok block parses its fields with parseOptionalInt first, because Storyblok number fields are free-text strings and authors can save any text.

The RPC builds the query from the key, the optional category, the optional brand and the limit. A brand becomes a filter on the brand product attribute. The RPC restricts the query to sellable products and includes the campaign key in the same way as the trending slider.

Setup

The trending slider ships with the Storefront Application V3 and needs no setup. The smart sorting slider block is part of the content model of all four supported CMS providers, so your editors add it to a page from the block picker of your CMS.

Configuration

SCAYLE Panel

The system Smart Sorting Keys, for example Trending, Sales Push and Topseller, are listed under Shops ➜ [Shop] ➜ Products ➜ Sorting. The keys draw on revenue and stock turnover data.

Assign categories to each product under Products ➜ [Product] ➜ Categories.

CMS blocks

Each provider names the block fields in its own way, for example smart_sorting_key in Contentstack and Amplience and smartSortingKey in Storyblok and Contentful. The block component maps them to the input of cms.getProductsBySmartSorting, which has these fields and validates them as follows.

FieldRequiredRule
smartSortingKeyYesOne of the system Smart Sorting Keys.
categoryIdNoA whole number. Without it the ranking spans all categories.
brandIdNoA whole number.
limitNoA whole number from 1 to 100. The RPC defaults to 10.

The RPC also accepts an optional pricePromotionKey. The slider blocks do not send it.

In your code

SettingWhereValue
RECOMMENDATION_LIMITsrc/server/controllers/product-detail.ts10
SMART_SORTING_CACHE_TTL_SECONDSsrc/server/api/cms.ts5 minutes

The cache time of the trending slider is fixed in the SDK. Data cache TTLs explains how to use another one.

Customization guides

You end up with a trending slider that ranks by a key you choose, for example because your shop does not use SCAYLE native Checkout.

Before you start, pick a key from the Smart Sorting Keys in the Storefront API. The SmartSortingKey object in @scayle/storefront-api lists them.

  1. Open src/server/controllers/product-detail.ts.
  2. Replace SmartSortingKey.TRENDING in fetchTrendingProducts with your key.
  3. To change the limit of the trending slider only, pass a number to the call in getViewProps, for example this.fetchTrendingProducts(product, 12). Changing RECOMMENDATION_LIMIT changes the similar products slider too.
  4. Change the slider title in the product_detail_page.trending_products key in every locale file in src/i18n/locales/.
  5. Open a product detail page.

After a rebuild, the slider shows the products in the order of your key. A new key or limit starts a new cache entry, so the change shows on the next page load.

The // ... markers stand for the other imports, the log and RECOMMENDATION_LIMIT constants and the other members of the class. Keep the mainCategory check, because product.mainCategory.id throws for a product without a category. Keep the try and catch, because without them a failed Storefront API call has no empty list to fall back to and the slider can stay on its loading skeleton.

Best practices

Keep the CMS content model and the sorting keys in step

When the Storefront API adds a smart sorting key, add it to the smart sorting block in your CMS content model. The RPC accepts the new key once you update @scayle/storefront-api. For Contentful, also add the label to SORTING_KEY_MAP in the block component. The other three providers store the key itself in the content model.

A new component on the product detail page reads trendingProducts through usePage<'ProductDetail'>(), the way the add-to-basket slide-in does. It then shows the same ranking without a second Storefront API call and without a copy that can go stale.

Troubleshooting

A slider stays empty and the log shows a failed fetch

Issue: The trending slider or a CMS slider has no products, although the category holds products and the key and filters are valid.

Possible causes: The Storefront API call failed, or your own override of fetchTrendingProducts or fetchCategoryRecommendations threw. Look for the log message Failed to fetch trending products for the trending slider or Failed to fetch CMS products by smart sorting for a CMS slider.

Solution:

  1. Find the log message and read its err field.
  2. If the error comes from the Storefront API, check its status and reload the page after it recovers. The next request after the cache entry expires fetches the ranking again.
  3. If the error comes from your override, fix the override.

Reference

SCAYLE documentation