How product blocks work
A product block is a list of recommended products that Releva places on your site. You configure it under Personalization › Product Blocks; the Releva SDK on your storefront asks for the blocks of the current page, draws them, and reports views and clicks back. This page explains the pieces. For the click-by-click setup, read Create a product block; for the request and response your developer sees, read Product blocks on the storefront.
What a block is made of
Section titled “What a block is made of”| Part | Where you set it | What it does |
|---|---|---|
| Page | The page selector on the list | The page type of your shop the block belongs to (product page, category page, cart…). Shared with Banner Blocks. |
| Product feed | General › Product Feed | Picks and ranks the products: an algorithm plus rules. See How product feeds work. |
| Mode and Products to Show | General | How the feed’s results relate to the products already on the page, and the maximum and minimum number of products. |
| Audience | Audience | A Behavior segment (include or exclude), an optional real-time Profile filter, and a Show when schedule. |
| Display mode, URL filter, Locales to Display | Display Configuration | Inline (Static) or over the page (Pop-up, Flyout, Bar), plus the URLs and languages the block is limited to. |
| Layout, CSS Selector, Insert strategy | Display Configuration and Appearance | The template that draws the products, the element it attaches to, and where it goes relative to that element. |
| Switch | The card on the list | A new block is saved off. Nothing is shown until you turn it on. |
A block needs a product feed and a segment to be served at all. A layout is optional: without one, the SDK hands the products to your own code instead of drawing them.
Pages and tokens
Section titled “Pages and tokens”Your shop has one Releva page per page type, not per URL. Every page has a token (shown as Token: at the top of the list). Your storefront sends that token with each page load, and Releva answers with the blocks of that page. The same product-page token is sent on every product URL.
If your shop has no pages, Product Blocks opens New Page. Create one with New Page, then give its token to your developer. A page can also carry a URL Path in Page Settings (the settings icon next to the token): when a storefront sends no token, Releva matches the page by that path instead. The path is the part after your domain, without a trailing slash.
The three modes
Section titled “The three modes”Your integration can send the ids of the products already on the page (a category listing, the cart contents). The mode decides what the feed’s results may contain:
| Mode | Result |
|---|---|
| Highlight | The feed’s top products. They may include products already on the page. |
| Discover | The feed’s top products that are not on the page. |
| Re-Rank | Only the products on the page, in the feed’s order. The number shown equals the number of ids sent, so a page that sends no ids gets nothing. Products to Show is hidden for this mode. |
Products to Show has two ends: the most products a block shows and the fewest it needs. When the feed finds fewer products than the minimum, the block is sent to the page with an empty product list and the SDK draws nothing. Randomize shuffles the products on every page load.
Who sees a block
Section titled “Who sees a block”Releva checks these rules on every page load, in this order. A block is shown only when all of them pass:
- The block is switched on and inside its Show when dates.
- The block has a product feed and a segment.
- If the storefront asks for blocks with certain Tags, the block carries at least one of them.
- The visitor is in the Behavioral Segment (or not in it, with Action set to Exclude), combined with the Profile filter by And / Or. A segment with no rules matches everyone.
- The page URL passes the URL filter. Show only where URL contains and Hide where URL contains take plain text fragments, not patterns; several fragments are separated by
|. The filter matches when the URL contains any of them. - The visitor is not a bot.
- The visitor’s language is in Locales to Display, or the list is empty.
Visitors in the control group of an A/B test (Analytics › A/B Tests) receive the block with no products, so that the test can compare them with everyone else.
Changes you save apply on the visitor’s next page load. A block that starts or ends by its schedule can take up to a minute to appear or disappear, because the page configuration is cached for 60 seconds.
Why a block is not shown
Section titled “Why a block is not shown”Work through the list above, then check the drawing side:
- Debug mode. Open a page of your site with
?rlv_mode=debugat the end of the URL. The SDK then logs every request to the browser console, and Releva returns switched-off and out-of-schedule blocks too, so you can see a block before you turn it on. Debug mode lasts until you close the tab. - Layout and selector. The SDK draws a block only when it has a layout, a CSS Selector that matches an element on the page, and at least one product. A block without a layout is passed to your integration’s callback; if nobody renders it, nothing appears.
- Products. Open the feed under Data Platform › Product Feeds: a feed whose rules exclude most of the catalog can return fewer products than the block’s minimum.
- Curl and monitoring tools. Requests with a non-browser user agent count as bots and get no blocks. Test with a browser or send a browser user agent.
Display modes
Section titled “Display modes”- Static places the block inside the page at the CSS Selector, using the Insert strategy: Before or After the element, at the Beginning of or End of it, or Replace it.
- Pop-up, Flyout and Bar show the block over the page. They add a Trigger (show immediately, after scrolling a share of the page, after some seconds, on leave intent, when a product is added to the wishlist or the cart) and a Session Interval (show every N sessions). Their look is set on Appearance: card size, position, overlay, close button and custom CSS.
- Custom is for integrations that draw the block with their own code.
How results are counted
Section titled “How results are counted”The card on the list shows event counts for the selected period:
| Number | Counts | Share shown next to it |
|---|---|---|
| Page Views | Views of the page (the same on every card of that page) | |
| Impressions | Times the block was at least a quarter visible on screen (reported by the SDK once per block per page load) | of page views |
| Clicks | Clicks on a recommended product | of impressions |
| Products to Cart | Cart additions attributed to the block | of clicks |
| Purchased Products | Purchases attributed to the block | of products to cart |
| Revenue | Value of the attributed purchases, in your shop’s currency |
A cart addition or purchase is attributed to a block when the visitor clicked a product in that block during the previous day. The clicked product itself attributes first; a purchase of another product falls back to the block the visitor clicked most recently.
Statistics on a card opens a page with a funnel and a daily chart of Impressions, Clicks and Conversions. These count unique profiles, so they are lower than the event counts on the card. A Products Purchased card lists the products bought through the block when there are any.
Limits
Section titled “Limits”Each page can run a fixed number of blocks at the same time (10 by default; shown as “N of 10 product blocks running”). When the page is at its limit, New Product Block and the switches of the blocks that are off are disabled, and saving a block that would go over the limit shows Product block limit reached. Shops with a large catalog also have a limit on the number of distinct feeds per page. Only a Releva super admin can raise these limits.