Assets and media rules
Assets are placed into the product grid through media rules, and together they provide the functionality to display media in the grid.
Integration
Complete the technical integration to display the configured media on your live site or application. The initial integration, where a developer integrates the API response in your product grid, is required to apply all the media rules.
Assets
Assets are customizable media elements that can be injected into your product grid. Unlike products, assets are created specifically to enhance the shopping experience and can be displayed in two ways: banners (displayed across the top of the grid) and grid slots (media placed in specific positions between products).
Banners
Banners are wide media assets that span the full width of your product grid and appear at the top of the grid. They're ideal for messages or notifications relevant to a broad set of products or shoppers. Here are some general real-life use cases of banners for inspiration:
- Promotional announcements:
- Seasonal sales and limited-time offers
- New collection launches
- Flash sale countdowns
- Free shipping thresholds or delivery promotions
- Category guidance:
- Category-specific shopping tips ("Winter coat buying guide")
- Size charts or fit guides for apparel
- Ingredient highlights for beauty/food categories
- Brand messaging:
- Sustainability commitments or certifications
Holiday greetings or seasonal messages
- Sustainability commitments or certifications
Grid slots
Media in grid slots are assets that occupy certain positions within the product grid. They blend seamlessly with products and appear in specific slots you define. Media shown inside grid slots can be more focused. Here are some general real-life use cases of media in grid slots for inspiration:
- Educational content:
- How-to videos or tutorials related to surrounding products
- Buying guides for complex product categories
- Comparison charts between product types
- FAQs or specifications for technical products
- Brand story snippets
- Cross-selling:
- Complementary product suggestions
- Bundle offers related to browsed items
- Accessory recommendations
- "Complete the look" suggestions in fashion
- Recipe cards in grocery categories
- Social proof and urgency:
- Customer review highlights
- "Trending now" or "Bestseller" callouts
- Stock level notifications
Asset types
Each individual asset can be of one of the following types:
Text
A text asset contains plain text. The API response returns the raw text, which can be styled and displayed on your site as needed.
These assets are quick to set up and use, but offer limited customization.
The maximum size for a plain-text asset is 100 KB.
Image
Image assets can be created through an image upload or a public image URL. The API response returns the image file or URL, which can be rendered to fit in the appropriate position.
Image hotspots
Hotspots are specific clickable parts of the image that open links. To add hotspots, click the desired part of an image asset in the preview section and draw a box with your mouse (you must drag from top left to bottom right). This area is for the hotspot link.

The following fields define your hotspot link:
- ID (default) — The unique identifier for the hotspot.
- URL — The URL to open to when a site visitor clicks the hotspot area.
- Title — The name of the hot link.
- Alt — The text to display when a site visitor hovers over the hotspot.
Image specifications
Any of the following image file types are allowed:
- JPG
- PNG
- BMP
- GIF
- Animated GIF
There is no image size (or dimension) limit. Bloomreach returns the image as uploaded, and your development team renders it on your site. Typically, organizations have a particular size or set of sizes that work with their page templates and designs. Get help from your development or design team for this information. The image size is generally needed only for a one-time integration into your site.
If you're testing media for the first time, we recommend that you run your test in a staging environment during the integration process. The integration team can upload various image sizes of banners/slot media to see what works best for your site before you, as a business user, configure media in the Bloomreach dashboard.
HTML
HTML assets are created using the CKEditor tool. This allows you to interactively create rich media assets containing multiple HTML elements.
Use the buttons in the CKEditor to add different HTML elements to your asset. HTML assets provide maximum control over the layout and customization of all asset types.
The maximum size for an HTML asset is 100 KB.
Note
Click the Source button in the CKEditor to preview the created asset's source HTML. This format matches that of the rich text HTML returned in the API response.

Media rules
Media rules can be created at the global, search, or category level. These rules define the scope, assets, positioning, and targeting of the media displayed in the product grid.
Asset selection and positioning
Media rules allow you to choose various positions in the grid and the assets to show in them. For each rule, a banner above the grid and a maximum of 5 of the first 72 grid slots can be selected to display assets.
When media is added to any slot, all the following products in the grid shift by one slot.
Some slots may be locked or unavailable for selection. This can be due to the following reasons:
-
Conflicts emerging from other media rules at a higher site level, or global level.
-
The slots have product merchandising operations like sequential lock, lock in place, or conditional slot already applied to them.
-
The queries or categories have group merchandising enabled. In this case, none of the grid slots are available, but the banner above the grid can be selected.
Additional settings
Each media rule has additional settings to configure audience targeting and the duration of the media’s visibility. These settings help control and personalize the media's behavior.
Conflict resolution
Conflicts in the grid positions and their reasons are highlighted while creating or editing media rules. This prevents you from adding assets into conflicting positions for the same queries/categories.

Conflicts emerging between common keywords or categories in multiple media rules are merged or resolved using the general conflict resolution principles for ranking rules.
The priority order of media rules is determined based on their specificity. Conflicts are merged with or overridden by higher-priority rules.
Specificity of media rules affects the priority order in the following ways:
-
More specific rules have higher priority over broader rules. For example, a rule for the keyword “shirt” would have higher priority over a rule for a wildcard “
*
”. -
Rules with more conditions have higher priority. For example, a media rule with a set duration would have higher priority over a rule without a duration for the same query/category.
-
For rules with the same specificity, the most recently updated rule has higher priority.
Updated about 4 hours ago