Smart Recommender Integration
What is Recommendation API?
Recommendation API is one of the APIs that Insider uses to serve its algorithms to your website.
What is Catalog API?
Catalog API is a REST API designed to receive product information from your end and store it in our database. You can inject and update your product information as frequently as you want. This allows for a more dynamic and up-to-date product feed, eliminating the need to rely solely on user visits to update the product feed.
What is the update frequency of the Catalog API?
Catalog API operates in real time. If a request meets the limitations and structure requirements, the updates are reflected immediately as soon as you send them.
What is hitChecker?
The HitChecker is an automated action that automatically marks products as stock-out if any product hasn't been visited for more than 24 hours, triggered by the chosen interval hours. The interval can be 1, 2, 3, 4, 6, 12 or 24 hours.
What is Crawler?
The crawler is a bot that visits the catalog's product pages and updates the products’ stock status and prices. It can be configured manually. You can reach out to the Insider One team to enable the crawler.
What is ProductFeedETL?
ProductFeedETL (Clickstream) is a process Insider uses to collect product catalog data from a website. It involves JavaScript functions integrated into the site, which gather necessary product details when a user visits a product detail page. The collected data is then pushed to Insider's database through a dedicated API. This API is triggered by the user's visit, ensuring that the latest product information is captured and stored.
How do you collect product catalog data?
Insider provides three different ways of Data Collection:
- Click-Stream (ProductFeedETL): Insider collects the product catalog data via JavaScript functions mapped during the first integration. These functions collect the necessary product catalog data and push it to Insider's database via the dedicated API triggered by the user's visit. The user visits the page that triggers the dedicated API to collect the product catalog from the product detail page via JavaScript functions.
- XML: Insider uses the XML file to get and update the product catalog given by the partners and updated by them.
- Catalog API: Insider can receive the product catalog via Catalog API, a REST API that allows you to send updated data more frequently than the other models.
What is Product XML, and how is it used for Insider's Smart Recommender?
Product XML is a file format for storing a large amount of data. These documents contain your product information, such as itemid, URL, price, and stock status. Insider's system only accepts URLs for XML files; direct uploads are not supported. Additionally, it can update every product field, including custom attributes, through this XML file.
Do I need to create a separate XML integration for each locale?
Yes, you need to establish a product catalog integration for each locale you have.
What happens if I update an active XML file?
It is automatically set as passive, and the validation starts. The passive XML file doesn’t interfere with the existing catalog or recommendations. They are not updated for a couple of hours until you correct the XML file integration. During this period, stock-out API, clickstream, and hit-checker will continue to make stock-out operations (if enabled for you).
From Catalog Ingest API ( Catalog API), why do I receive a warning like this: “message": "Product attribute keys are not included in partners attribute. (attribute_name)is not included in partner attribute map.",”?
Verify that the attributes flagged in the warning exist on the product attributes page and that each attribute's spelling is correct.
What happens if I want to work on the XML file more and don’t want to submit it for validation? Do I have to wait until the validation is completed each time I make a change?
No, you don't have to wait until the validation is completed. You can always save your work as a draft on the editing screen.
How do I resolve data sync issues for Smart Recommender?
You can check the XML Integration Validator to see your XML integration’s validation status and update your sync period.
Can I rename/delete/ change the data type of a custom product attribute?
No, you can't. It is not possible to rename or delete a custom product attribute. However, you can make them passive and create a new custom attribute.
Why the product image is not loaded in the catalog manager? Can I exclude it from the recommendation if the image is not available?
The Product Attributes article states that the image_url parameter is a required default product attribute. The product will not be included in the catalog without an image URL. However, if the image URL is inaccessible or incorrect, Insider unfortunately cannot detect it. To avoid issues with missing or broken images, it's crucial to provide accurate and accessible image URLs when setting up products in the catalog. Double-check that the image URLs you provide are correct and the images are hosted on an available and not blocked server.
How do I edit the product data for Smart Recommender?
You can edit your data by updating your product catalog via your product catalog integration type.
Do I need to pause campaigns when changing the product catalog XML file?
It is not necessary to pause your Smart Recommender campaigns when changing the product catalog XML file. When you update an active XML file, it is automatically set to passive and goes through a validation process.
Until the updated XML is validated, the product information from the last update of your most recently active XML remains valid. This ensures that your catalog and recommendations are not affected during the validation period.
Once the new XML file is successfully validated, it becomes active, and your campaigns will continue running normally with the updated product information and attributes.
Therefore, simply upload the new XML and follow the validation process—no need to pause your campaigns.
Smart Recommender Widget
Why does Smart Recommender not appear?
Your Insider Tag integration might have failed. Make sure that you implement the Insider Tag correctly.
Can I show any specific products on Smart Recommender?
Yes, you can use the manual merchandising algorithm for that.
Can I exclude a specific product or product category from Smart Recommender?
You can exclude any item, category, or custom attribute (such as prohibited items or brands) by using filters. You can do it via the Product Catalog Management page.
Why is Smart Recommender not showing products?
There might be several reasons why Smart Recommender is not showing products:
- Insider's algorithms require a specific number of user events and in-stock products to work. Check your Recommendation Algorithms page to make sure your algorithms are getting updated.
- Your product catalog integration might be incomplete or wrong. Make sure that you have mapped every attribute correctly.
- Check your product catalog to ensure your products have the correct stock, price, and image URL information. Smart Recommender does not recommend any products that are out of stock, have a price of $ 0, or are missing an image URL.
- Due to complex filtering, there may be insufficient recommendations. Smart Recommender doesn't display any products when there are inadequate recommendations. You can check the “Hide the widget if the number of products is less than” setting.
Why are products in Smart Recommender shown with their previous prices instead of the updated ones?
- If the data collection model is Click-Stream (ProductFeedETL), the item may not have been visited once the price is changed. It would be better to wait for 2 hours and check once again. If the issue hasn't been solved, the Insider Help Center can detect and solve it.
- If there is an XML integration, the item should be updated in both XML and on the website. Since Insider's system can sync with the XML every hour, it would be better to wait an hour and check again. If the issue hasn't been solved, the Insider Help Center can detect and solve it.
- If there is Catalog API integration, it should be checked on your side regarding the integration requests and price parameters.
Why does Smart Recommender show the items that have recently gone out of stock?
If you think that the product inventory is not showing correctly in terms of the stocks, check the solutions below:
- If the data collection model is Click-Stream (ProductFeedETL), to exclude the stock-out items from the recommendation, the Insider's system must receive at least one visit once it's out of stock. After this visit, our hourly automation can update the item's stock status. This might take some time. If it takes more time than expected, Insider Help Center can detect and solve it.
- If there is an XML integration, the item should be updated in XML as well as on the website. Since Insider's system can sync with the XML every hour, it would be better to wait for 1 hour and check once again. If the issue hasn't been solved, the Insider Help Center can detect and solve it.
- If there is Catalog API integration, it should be checked on your side regarding the integration requests and stock parameters.
Is it possible to add Color, Brand, or some other information about the items to the Smart Recommender Carousels?
It is possible to use all related product attributes on the design if they are available on the product detail page. To create designs with the attributes, please create a ticket to the Insider Help Center together with your desired design draft.
Why do I see the same items on Smart Recommender?
Because item IDs might differ for items with the same product attributes. Compare their item IDs, if somehow those item IDs are different from each other, make sure that you have them within a variant structure (itemid_variantid for those items that have the size and/or color options), and also the groupcode parameter is correct. You can refer to Important Checkpoints for Insider System Rules for further details.
Why is the discount Badge not visible, or why is its value incorrect?
Because the discount parameter might be incorrectly calculated, check the "discount" parameter and its value in the endpoint. If the value you see is normal, then check its design. If the numbers are abnormal, then reach out to the Insider One team.
How can I show only discounted products or non-discounted products in the Smart Recommender?
You can add “discount ratio” as a filter to the algorithm. To display discounted products, set the discount ratio to more than 0, and for non-discounted products, set it to 0.
Why are Smart Recommendations not updated?
If your recommendations have not been updated, check your algorithms. All of Insider's algorithms, excluding Substitute, Complementary, Chef, and Real-Time User Engagement, work daily. Substitute, Complementary, and Chef algorithms update weekly, while Real-Time User Engagement works in real time.
Smart Recommender Campaigns
Do I need to create campaigns/variations and design from the beginning for each new campaign/variation?
No, you don't. It is possible to duplicate both the campaigns and the variations.
Do I need to create a different campaign for each category page to show products from the current category?
No, you don't. Smart Recommender can get the category information dynamically from the Category page. The only important thing is category breadcrumbs are supposed to be the same as product categories on the product pages. If you want to build a Smart Recommender campaign on Collection pages (Outlet, New, Favorites) where the category breadcrumb differs from the product catalog, you need to set them separately. Please consult the Insider One team for more information.
Is there any campaign/variation count limit?
Theoretically, no, there is not. However, building up too many campaigns might cause an increase in the API size, which can affect the page load.
Is it mandatory to set a control group in every Smart Recommender campaign?
No, it is not.
Can I use Smart Recommender on campaign pages?
Yes, you can target any specific page using the rules on the panel and filters to show desired items on Recommendation Strategies.
How does the traffic allocation split work? Do the same users always see the same recommendations?
The traffic allocation is applied randomly, and each user will stay in the allocated test group during the re-eligibility duration configured in your campaign's Goal step.
Why can't I see my Smart Recommender campaign even though the test bar shows it as visible?
Because the campaign might not have data on the items from the endpoint, and there is probably no product on your endpoint. Check the system rules related to the product feed. If you are about to run a campaign on the category page, most probably getCategories rule on the category page does not match with the getProductCategories on the product page that belongs to the category.
Is it possible to show the exact count of items from the selected filter, such as brand or category?
Yes, it is. Thanks to the Advanced Mixed strategy, you can select each item from any available algorithm and filter. For example, you can show 6 out of 10 products from Brand A or 3 out of 10 products from women's tops.
What parameter starts with #ins_sr on the URL?
This parameter determines if an item has been removed from the website and is no longer available. It is exclusive to the Web Smart Recommender widget. When a user clicks on an item with the #ins_sr parameter in the URL within the widget to view the product's page, the system checks if the item is still present on the page. The item will be marked as out-of-stock in the catalog if it is no longer available.
Users must successfully land on a page for this model to function properly. If a pop-up appears and prevents the user from landing on a page, the model cannot operate as intended.
Does Smart Recommender affect the website speed? How can I check it?
Third-party visualization might affect the website's speed. However, you can take some precautions to optimize this effect. You can set Smart Recommender to show images in lower sizes and with fewer than 10 items at once. You can consult the Insider One team about the Recommendation API as a solution for further information.
Recommendation Strategies
How can I configure the Smart Recommendation settings?
You can modify product recommendation settings on the Recommendation Strategies page.
What is the dynamic filter?
Dynamic filtering allows you to filter product pages dynamically based on the currently viewed product. This means you can recommend products with the same category or brand as the product being viewed. For instance, if a user looks at a red-colored product, you can use dynamic filtering to recommend other red-colored items. Similarly, if they view a product from a particular brand, you can recommend other products from the same brand. Dynamic filtering enhances the personalization of product recommendations based on the user's current browsing context.
What is the difference between the standard filter and the dynamic filter?
The standard filter needs a value to filter like "category does not contain Accessories", so you need to add a value to the filter. The dynamic filter can get its value dynamically from the product being visited by the user (Thus, the dynamic filter is only available on the product pages). For example, you can show S-size shirts when the user is viewing S-size shirts. Refer to Recommended Product Filters for further information.
Can I use recommendation filters with OR conditions?
Yes, with the ANY OF operator in the filter, you can showcase products from multiple categories like X, Y, or Z, from brands A or B, or in colors red or black, and so on. This flexibility allows you to create more dynamic and diverse product recommendations based on multiple criteria simultaneously.
Can I have multiple Smart Recommenders targeting different users based on category affinity?
Yes, this is possible. You can enable the Personalize recommendations based on attribute affinity option to personalize Smart Recommender results. The Smart Recommender attribute affinity engine calculates each user’s affinity for product attributes such as brand, color, or category at an individual level.
By leveraging attribute affinity, you can create hyper-personalized experiences and run different campaigns segmented by category affinity. The attribute engine updates daily to reflect new users and evolving user behavior.
Can I change the traffic allocation for an active Smart Recommender campaign without duplicating it?
Yes, you can update the traffic allocation of an active Smart Recommender campaign without duplicating it. After making the change, be sure to generate the panel to apply the update.
Can I have multiple Smart Recommendation widgets on the same page?
Yes, you can display multiple Smart Recommendation widgets on the same page by creating separate campaigns targeted to that page.