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
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
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Shoe Sale</title>
<style>
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
display: flex;
justify-content: center;
align-items: center;
min-height: 100vh;
background: #F0F0F0;
font-family: 'Georgia', serif;
}
.ad-container {
width: 410px;
height: 710px;
background-image: url('https://media2.giphy.com/media/v1.Y2lkPTc5MGI3NjExbXh1YXdieHlwOGxtdjNtbmZ4YWcxZGd1OGRreWFmczF2aTkyOGE2bCZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/3HpSslnzl7mKx0Yzhi/giphy.gif');
background-size: cover;
background-position: center;
display: flex;
flex-direction: column;
justify-content: flex-end;
align-items: center;
padding: 50px;
text-align: center;
position: relative;
}
.header {
color: #000000ff;
font-size: 64px;
font-weight: bold;
margin-bottom: 20px;
text-shadow: 2px 2px 4px rgba(255, 255, 255, 0.8);
}
.cta-button {
background-color: transparent;
color: #000000ff;
border: 2px solid #000000ff;
padding: 18px 40px;
font-size: 20px;
font-weight: bold;
cursor: pointer;
border-radius: 8px;
transition: all 0.3s;
backdrop-filter: blur(5px);
background: rgba(255, 255, 255, 0.8);
}
.cta-button:hover {
background-color: #000000ff;
color: #FFFFFF;
transform: translateY(-2px);
}
.cta-button:active {
transform: translateY(0);
}
</style>
</head>
<body>
<div class="ad-container">
<h1 class="header">50% off</h1>
<button class="cta-button">Browse winterwear</button>
</div>
</body>
</html>
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 enclosed within an <img> tag, 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.
Note
There are two options to match the size of the returned image with the slot:
- Make the image rendering implementation responsive to fit dynamic slot sizes (recommended).
- Upload images having the same size as your slot dimensions.
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.
Weblayer
Expose Bloomreach Engagement Weblayers to use as assets in Discovery. These are fully customizable assets that can use various elements and styles. Weblayers seamlessly integrate Bloomreach Engagement’s rich customer data into assets to create targeted and hyper-personalized media campaigns (using user profile details) or collect user inputs.
Benefits of weblayer assets
-
Create assets in a user-friendly editor, with full control over the elements and parameters through the code editor.
-
Design interactive weblayer assets with buttons, sign-up forms, countdown timers, and animated elements using the visual editor mode.
-
Show personalized details in your assets—like "Welcome back, Sarah" or location-specific offers—that update automatically for each customer.
Note
Define parameters in your weblayers to personalize them. The template parameters can be used to display personalized content like the user’s name, region, or any other user data that you capture in Engagement.
Bloomreach returns a weblayer asset as an HTML <div> in the API response, which can be rendered in your product grid slots.
Expose a weblayer
Warning
Once a weblayer has been exposed to Discovery, it is indicated by a lock (🔒) symbol, and it can’t be edited, or launched from Engagement. This prevents interference with the live experience.
Create a copy to use the same weblayer again.
If you use Real-time segments, your Bloomreach Engagement and Discovery dashboards are already connected. Otherwise, contact your Customer Success Manager or Business Services Consultant to set up this connection.
Follow the steps given below to expose a weblayer from your Engagement dashboard:
-
Navigate to Campaigns > Weblayers in the Bloomreach Engagement dashboard.
-
Hover over the desired weblayer you want to display in the product grid.
-
Click the v arrow next to the Edit button to view a dropdown list. Select the Expose to Bloomreach Discovery option.
-
Click Expose in the confirmation modal to complete the action. The weblayer takes up to 30 minutes to appear in Discovery.
The option to expose to Discovery is only available for weblayers with the following settings in Engagement -
-
Consent category is set to General consent.
-
Audience is set to All customers.
-
Its status is set to active (launched) in Engagement.
Refer to the Conflicts in Engagement assets section to learn how conflicting settings are resolved.
Note
If you don't have the required weblayer to expose already available, create a new one and configure it before exposing.
Best practices for weblayers as assets
Weblayers need specific configuration to work as assets in product grids. When creating a weblayer for Discovery:
-
Set the weblayer dimensions to fit your product slot size. Weblayers don't scale automatically.
-
Design for grid display rather than pop-up use—remove close buttons ('x') and similar pop-up elements.
Clarity
Expose Bloomreach’s AI shopping assistant, Clarity, from Engagement to use it as an asset in Discovery. Place Clarity assets in the grid with triggers (conversation starter questions) for shoppers to start interacting with the assistant.
Configure and set up
Clarity is set up and configured by Bloomreach. To use Clarity as a media asset in the product grid, consult your Customer Success Manager (CSM) or Business Services Consultant.
Once set up, Clarity can be exposed and used in Discovery just like any other weblayer.
Warning
A Clarity weblayer should contain the term “Clarity” in its name (preferably at the first position) for Discovery to identify it as a Clarity asset type.
Preview and display
The preview of a Clarity asset in the Discovery dashboard is only a sample placeholder image. The actual contents of the asset can differ from the preview.
Bloomreach returns the Clarity asset as an HTML <div>, which can be rendered in your product grid. It is followed by a <meta> tag containing a dynamic Base64 string. This string is decoded and used by the Clarity asset to set the context for the starting questions based on the shopper’s query.
Here is an example of a Clarity asset injected into a product grid. In this example, the width of the slot is conditionally increased if a Clarity asset is rendered in the slot:
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.
Conflicts in Engagement assets
When the same weblayer or Clarity asset has different settings in Bloomreach Engagement and Discovery, the Discovery settings take priority.
How conflicts are resolved:
- Audience targeting: Discovery rules override Engagement settings.
- Scheduling: Discovery timing controls when assets appear.
- Tracking and analytics: Event data still flows to your Engagement dashboard for reporting and analytics.
This ensures consistent and controlled behavior in your product grid while maintaining complete analytics visibility.
Note
Manage targeting from Engagement using Real-time segments:
Create and expose a Real-time segment in Engagement.
Create a corresponding audience in Discovery using this segment.
Apply this audience to your weblayer or Clarity assets.
Updated 4 days ago