Implementation Guide

1. Define your Goal and Placement

Before configuring Similar Product Recommendations, clearly define what you want to achieve and where recommendations should appear in your storefront.

Typical goals include:

• Offering relevant alternatives when a product is not the right fit.
• Increasing discovery of the assortment.
• Supporting cross-selling on the Product Detail Page by highlighting specific brands, products or categories.

Common placement:

• Product Detail Page (PDP) below the main product information
• Carousels (“You may also like”, “Similar items”)

Having a clear goal and placement upfront ensures that all following configuration steps are aligned with the intended customer experience.

2. Configure Attribute-Based Similarity and Set Weights

Start by defining which product attributes should determine similarity in your catalog. These attributes describe what makes two products alike from a business perspective.

Typical attributes include:

• Category or product type
• Brand
• Material, fit, or style-related properties

Each selected attribute is assigned a weight, which controls how strongly it influences the similarity ranking.

Best practices:

• Use attributes that are consistently maintained across your catalog.
• Assign higher weights to attributes that are essential for your business logic.
• Avoid using too many attributes at once. Clarity usually leads to better results.
• Do not worry too much about the weights initially. You can always fine-tune later on.

Attribute-based similarity forms the foundation of Similar Product Recommendations and acts as a reliable baseline, even when image similarity is not enabled.

For more information on attribute configuration, please see "Define Attribute-Based Similarity".

3. Configure Image Similarity

If you prefer not to use image similarity, you can choose to only use tagged images for image similarity without tagging any image.
If you decide to use image similarity, you can enhance recommendations by comparing products based on their visual appearance using AI-powered image analysis. It complements attribute-based similarity by capturing aspects such as color, shape, texture, and overall look.

Image similarity threshold:

To ensure recommendations remain relevant, you can set a minimum similarity threshold. This acts as a quality filter: the higher the threshold, the more visually similar a product must be to be recommended.

• Higher Threshold: Ensures strict visual matching (good for finding exact lookalikes).
• Threshold at 0: Disables the filter. Image similarity will apply to all products, regardless of how high or low the AI scores their visual resemblance.

Key decisions in this step:

• Enable or disable image similarity depending on how visually driven your assortment is.
• Choose which image is used per product to ensure consistent and meaningful visual comparisons.
• Set a minimum image confidence threshold to filter out visually dissimilar products.

Best practices:

• Consistent image setups (e.g. same background, lighting, or model) often lead to higher image similarity scores across products.
• Diverse or creative imagery can result in more nuanced visual distinctions.
• Image similarity is optional and should be complemented by attribute-based similarity.

For more information on attribute configuration, please see "Configure Image Similarity".

4. Validate the Setup with Representative Products

After configuring attribute-based and image similarity, review the recommendations for a representative set of products from your catalog using the preview functionality in the SCAYLE Panel. This step helps ensure that the setup behaves as expected across different product types.

What to validate:

• Products from different categories and brands
• Items with strong visual similarity and items where attributes matter more
• Edge cases, such as products with limited data or atypical images

Questions to ask during validation:

• Do the top results feel relevant from a customer perspective?
• Do visually similar products appear where expected?

Validation should focus on overall quality, not individual outliers. If needed, adjust attributes, weights, or image thresholds before moving on.

5. Add Custom Recommendations for Key Items

This is an optional step, but it can be useful to manually control which products are recommended for specific items. This can be used when business priorities or editorial decisions should override the automated logic.

Typical use cases:

• Promoting strategically important products
• Ensuring strong alternatives for key or high-traffic items
• Handling new releases of a product you want to point the customer towards.

Best practices:

• Custom recommendations are always returned first and in the defined order.
• If a predefined product becomes inactive or unsellable, it will automatically be skipped.
• Custom recommendations should be used selectively, not as a replacement for a solid configuration.

This step helps fine-tune the experience for important products without compromising the overall recommendation quality. You can always set up or adjust the custom recommendations later on.

For more information on custom recommendations, please see "Define Similar Products".

6. Configure Filters and Exclusion Rules

Filters and exclusion rules allow you to adapt Similar Product Recommendations to specific use cases without changing the underlying similarity logic.

Common examples:

• Restrict recommendations to the same brand or category
• Exclude products from the same brand to encourage discovery
• Filter by sale status or availability
• Exclude products that share the same master key (e.g. color variants)

Best practices:

• Use filters to tailor recommendations to the context of each placement.
• Keep exclusions minimal to avoid overly narrow result sets.
• Treat filters as a presentation-layer tool rather than core similarity logic.

For a list of filters and other parameters to use to customize your recommendations, please see #request-parameters.

7. Integrate the Recommendations Endpoint in Your Storefront

Once the recommendation logic is configured, the way you expose Similar Product Recommendations depends on whether you use the SCAYLE Storefront Application or run a custom storefront.

Not using the Storefront Application

If your shop runs on a custom or third-party front end, use the Storefront API to implement Similar Products yourself. Call the dedicated recommendations endpoint to fetch similar products for a given item and build the UI in your stack. Align the integration with your placement and goal. For request and response schemas, see the Storefront API Specifications.

Using the Storefront Application

• Version 1.16.0 or higher (feature included by default)
  • These versions ship with a ready-to-use recommendations component and the related logic. Use the built-in component and follow the Storefront Application’s Recommendations guide to place and configure it.
• Before version 1.16.0 (backport required)
  • If your storefront was created from an older version of the Storefront Application below 1.16.0, add the Similar Products feature by manually backporting and bringing the recommendations component and composable from a newer template into your project.
  • Using the Storefront CLI "feature add" command, you can add the Similar Products Slider feature into your existing Storefront Application-based project. This will try to install the latest version of the @scayle/storefront-product-detail package into your project and will create a SFSimilarProductsSlider.vue. Be aware that you should double-check this component and add its used translation keys to your specific translation files.
  • If you don't want to backport manually from the latest Storefront Application version or use the Storefront CLI, you can also manually implement a custom UI component by using the useSimilarProducts composable provided through the @scayle/storefront-product-detail feature package starting with version 1.8.0.
  • The Similar Products guide then explains how to integrate it:
    • Use the useSimilarProducts composable.
    • Configure the where parameter for your merchandising goal.
    • Place the block where you need it (such as the product detail page).

Best practices:

• Keep the initial implementation simple and consistent with your storefront design.
• Avoid overloading the page with too many recommendation slots.
• Label recommended products clearly so users know what they are.

We recommend using our ready-to-use Storefront component for the implementation.

For more information on the implementation of recommendations in your Storefront Application, please see the Recommendations guide of the Storefront Application.

8. Monitor Results and Iterate

After going live, Similar Product Recommendations can be treated as an evolving feature rather than a one-time setup. When your catalogue evolves, your recommendation setup should do the same.

What to monitor:

• Relevance and diversity of recommended products
• Performance metrics, such as engagement or conversion where available

Best practices:

• Adjust attribute selection or weights if results feel too narrow or too broad.
• Refine image similarity settings if visual matches are inconsistent.
• Add or remove predefined products as business priorities change.

Regular iteration helps ensure that recommendations stay aligned with your assortment, imagery, and customer behavior over time.