# How product blocks work

> What a product block is, how pages and tokens connect it to your storefront, the three modes, the rules that decide whether a visitor sees it, and what the numbers on its card count.

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](https://releva.ai/documentation/guides/product-blocks/create-a-product-block/); for the request and response your developer sees, read [Product blocks on the storefront](https://releva.ai/documentation/reference/sdk/endpoints-the-releva-sdks-call/#product-blocks-in-the-push-response).

## 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](https://releva.ai/documentation/learn/product-feeds/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

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

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

Releva checks these rules on every page load, in this order. A block is shown only when all of them pass:

1. The block is **switched on** and inside its **Show when** dates.
2. The block has a product feed and a segment.
3. If the storefront asks for blocks with certain **Tags**, the block carries at least one of them.
4. 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.
5. 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.
6. The visitor is not a bot.
7. 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

Work through the list above, then check the drawing side:

* **Debug mode.** Open a page of your site with `?rlv_mode=debug` at 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

* **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

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

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.

## Next steps

* [Create a product block](https://releva.ai/documentation/guides/product-blocks/create-a-product-block/): Add a block to a page, choose its mode, feed, audience and layout, and place it on your shop.
* [Turn on a product block and check its results](https://releva.ai/documentation/guides/product-blocks/turn-on-a-product-block-and-check-its-results/): Switch a block on and read its impressions, clicks, purchases and revenue.
* [Product blocks on the storefront: API and SDK](https://releva.ai/documentation/reference/sdk/endpoints-the-releva-sdks-call/#product-blocks-in-the-push-response): See what your storefront receives for each block, if you build your own client.
* [How product feeds work](https://releva.ai/documentation/learn/product-feeds/how-product-feeds-work/): Learn how a feed picks the products a block shows.