Skip to main content

Recommendations and merchandising FAQ

How do I enable and access product recommendation features?​

Product recommendation capabilities are a premium feature, so contact your Customer Success Manager to enable them on your Kameleoon account. Access the Product recommendations workspace by navigating to Settings > Recommendations.

What is a product recommendation strategy?​

A recommendation strategy defines how you select and filter products to display. When you create a strategy, you must enter a name, description, and define the maximum number of products to display in the block. After you save the strategy, you configure its rules, templates, and design.

How do I publish a recommendation strategy on my website?​

Click Recommendations > Recommendation strategy. Then, click your recommendation block > Copy code to generate your block's snippet and paste it into your page's source code where you want the block to appear.

Alternatively, use Kameleoon's Activation API to serve product recommendations. The API uses the latest saved template version and returns a JSON object containing the recommended products and the template's HTML. The API response does not include CSS; you must apply styling to the output manually.

When implementing your block's code, you must include the data-recommender-code (product recommendation block ID) parameter. For blocks using algorithms like Similar and They also buy this, you must include the data-recommender-item parameter to specify the current product's ID.

If you notice a large discrepancy between your total inventory and the number of products available for recommendation by the Popular or Trending algorithms (labeled Widgetable products), it's because these algorithms have strict data quality requirements.

For a product to be considered widgetable and thus eligible to be shown in a recommendation, it must have all four critical fields correctly set up and imported:

  • Price
  • Name
  • URL
  • Picture (image URL must be valid and retrievable)

If any of these essential attributes are missing or incorrect (for example, a broken image URL), the product is filtered out and will not appear in the recommendation algorithm's results.

How to troubleshoot missing images​

A common reason a product is not widgetable is that the image could not be successfully downloaded during the catalog synchronization process.

Top reasons images cannot be downloaded​

If your product has a valid image URL but is still missing the picture, the issue likely lies with your shop's server configuration:

  • Server overload: Your shop's storage or server cannot handle the high volume of requests generated by Kameleoon's system, which downloads images using 50 simultaneous threads, which often causes timeout errors.
  • Anti-DDoS blocking: Your shop's anti-DDoS protection or firewall is blocking our requests based on the IP address. You must whitelist all the Kameleoon cluster's IPs to ensure uninterrupted access. You can find a list of the IPs here.

How to find problematic products​

You can quickly identify which products are missing the required data fields by accessing your Products Database.

  1. Click Settings > Recommendations > Products > Data feed.
  2. Select False from the Widgetable dropdown.
  3. Click on any product that appears to view its attributes. The issue (for example, missing price, failed image retrieval) is highlighted in the product's attribute list.

Algorithm time window reminder​

When troubleshooting results, note that the Trending algorithm calculates recommendations based strictly on sales orders that occurred within your selected time window. The algorithm excludes sales older than this configured duration.

How often does the product data feed update?​

You can customize the frequency and specific timing of your product data feed updates in Store settings.

Can I use product recommendations in email campaigns?​

No. Currently, product recommendations are supported for web and app channels only. You cannot push dynamic recommendation widgets directly to email templates.

Is there a preview mode for recommendations?​

Yes, you can preview and simulate your product recommendations on your website using the Widget Studio.

To do this, create a widget that contains your product recommendation block, then add it to your experiment. Once configured, you can use the simulation feature in the Widget Studio to visualize the widget. Simulating allows you to verify both the design and the products returned by the algorithm before launching.

Yes. You can apply sorting criteria to the products returned by an algorithm. For example, you can choose to sort the displayed results by top revenue to prioritize high-value items.

Can I use regular expressions in recommendation rules?​

No. Regular expressions (regex) are not currently available for defining complex matching logic within recommendation rules.

Can I import my own recommendation algorithm?​

No. The platform does not support Bring Your Own Algorithm (BYOA). You must utilize the suite of built-in algorithms provided by Kameleoon.

Is there a limit to the number of recommendations I can display?​

While the system does not enforce a strict limit, requesting a large number of products impacts algorithm performance and increases response times. You should display fewer than 50 products per block. To display larger product sets, use Collections.

Do all algorithms work everywhere on my site?​

No, some algorithms only work under specific conditions. For example, the Similar products algorithm, the Products usually purchased with this item algorithm, and the Store recommendations algorithm only work on product detail pages. The Products usually viewed with this product algorithm only works if the cart contains items.

Can I use product sizes imported from Google Merchant in Liquid recommendation templates?​

Yes. You can use the product size as an HTML variable in your template, provided that the size appears as a parameter in the data feed.

Can I use a custom field name (like shop_recommend) for the Store Recommendations algorithm?​

No. The Store Recommendations algorithm specifically requires the accessories field in your data feed. It does not recognize custom field names for defining manual product relationships.

To manually link products (for example, to display complementary items), you must map the related product IDs to the accessories field.

The algorithm displays only the products linked via the accessories tag. However, you can restrict these results further by applying standard filters to the recommendation block (for example, to exclude out-of-stock items from the manual list).

How do I provide data for the Currently on wishlist recommendation algorithm?​

To use the Currently on wishlist algorithm, you must explicitly track when a user adds an item to their wishlist. The recommendation engine does not automatically detect these interactions without a specific API signal.

You must implement the trackAddToWishList() method from the Activation API. This method sends the necessary event data to Kameleoon, which populates the wishlist algorithm.

Which attributes can I import from Google Merchant Center versus Kameleoon XML?​

The supported attributes depend on your feed format. Be aware of the following limitations regarding labels and stock data:

Custom labels (custom_label_0 - custom_label_4)​

  • Not supported.
  • The recommendation module does not import custom_label attributes from Google Merchant Center feeds. You cannot use these fields for filtering or display.

Stock quantity (stockquantity)​

  • Google Merchant Feeds: Not supported. The Google product data specification does not include a numerical stock count (only "availability" status). Therefore, you cannot import exact inventory numbers via Google CSV/XML.
  • Kameleoon XML: Supported. To use exact stock counts, you must use the native Kameleoon XML format and populate the stockquantity field.
  • Viewing and using stock data: If you import stock data via Kameleoon XML, the values appear in the Data feed overview. You can use the stockquantity attribute to create filters (for example, stockquantity > 5).

How do I decide between XML import and API import for my catalog?​

You must base your decision on your catalog size and technical infrastructure. Use the XML import method if your catalog contains fewer than 50,000 products, and you lack a website data layer. Conversely, use the Product Recommendation API if your catalog exceeds 50,000 products.