HomeEngagementContentDiscoveryOther resources
Guides

Assets and media rules

Suggest Edits

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.

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 2 days ago