Introduction

Commerce Display Grid Shelf is an in-grid commerce display unit combining branding assets with consecutive product tiles up to the entire grid row or site width.

Rendering Examples

Desktop

Mobile

Response Keys

Response Example

{
  "status": "OK",
  "placements": [
    {
      "viewHome_API_desktop-commerce-display-grid-shelf": [
        {
          "format": "CDGS",
          "products": [
            {
              "ProductName": "RMP Product",
              "ProductId": "134679258",
              "ProductPage": "https://example.com/product",
              "Image": "https://example.com/assets/image.jpg",
              "Rating": "-1",
              "Price": "8.49",
              "ComparePrice": "8.49",
              "Shipping": "0",
              "ClientAdvertiserId": "123",
              "AdvertiserId": "431248565",
              "RenderingAttributes": "{\"brand\":\"brandname\",\"numberOfReviews\":\"0\",\"shippingCost\":\"0\"}",
              "OnLoadBeacon": "//b.us5.us.criteo.com/rm?rm_e=...",
              "OnViewBeacon": "//b.us5.us.criteo.com/rm?rm_e=...",
              "OnClickBeacon": "//b.us5.us.criteo.com/rm?rm_e=...",
              "OnBasketChangeBeacon": "//b.us5.us.criteo.com/rm?rm_e=...",
              "OnWishlistBeacon": "//b.us5.us.criteo.com/rm?rm_e=..."
            }
          ],
          "products_order": [
            {
              "products": ["134679258"],
              "isMandatory": false
            }
          ],
          "rendering": {
            "background_image": "https://cdn.example.com/images/desktop-banner.jpg",
            "background_image_alt_text": "Accessible description for desktop background image",
            "mobile_background_image": "https://cdn.example.com/images/mobile-banner.jpg",
            "mobile_background_image_alt_text": "Accessible description for mobile background image",
            "redirect_url": "https://example.com/click-destination",
            "redirect_target": "_blank",
            "redirect_url_app": "app://example/click-destination",
            "cta_text": "Shop Now",
            "cta_text_color": "#FFFFFF",
            "cta_color": "#CCCCCC",
            "legal_text": "©2025 Example Inc. All rights reserved.",
            "more_info_text": "Terms and conditions apply. Tap to view more.",
            "color_mode": "lightcommand"
          },
          "OnLoadBeacon": "//b.us5.us.criteo.com/rm?rm_e=...",
          "OnViewBeacon": "//b.us5.us.criteo.com/rm?rm_e=...",
          "OnClickBeacon": "//b.us5.us.criteo.com/rm?rm_e=...",
          "OnFileClickBeacon": "//b.us5.us.criteo.com/rm?rm_e=...",
          "OnBundleBasketChangeBeacon": "//b.us5.us.criteo.com/rm?rm_e=..."
        }
      ]
    }
  ]
}

Specifications

General

The Commerce Display Grid Shelf unit is composed of two different parts:

• A branding zone,
• A product zone.

The format can be displayed either in-grid or out-of-grid. The format must be able to host at least 2 products (or more).

The branding zone size should be equal to the product tile sizes and will redirect to 1 URL. Products will redirect to the respective PDP.

When a website is responsive,

• all tiles must always be at the same size.
• if in list view or single column grid, format will change to Alternative Mobile Layout.

Asset Sizes and Behavior

Background Image Specifications

Dimensions
The background image asset is 1500x1500 pixels.

Device Support
This asset can cover both desktop and mobile/APP placements based on the detected device and layout.

It will not render at its original size but instead scaled down to accommodate double density screens (or higher) for improved quality.

Alignment and Cropping

There is a minimum cropping area of the image asset called the Retailer safety zone. This Retailer safety zone will change with each preset scaling of the asset.

Both Brand safety zone and component placeholders are centered in the image, therefore the background image needs to be centered within the branding zone and cropped on all sides.

Brand Safety zone The Brand safety zone is the area that is always guaranteed to be visible and unobstructed. The brand will design all their main messaging and critical visuals within this area.

Component Placeholders
Two equal internal placeholders are used for legal text and a call-to-action (CTA) button. These are treated as margins and ensure no overlap with the Brand safety zone.

Scaling Rules

Depending on the device and grid size, the background image is displayed at one of the following scales:

• 26% (390×390),
• 33.33% (500×500),
• or 50% (750×750).

Grid-Based Scaling Presets

These presets define the image scale based on standard grid tile dimensions:

• Mobile Grid When the device is mobile and the tile width is between 140 and 180 pixels, and the height is between 257 and 390 pixels:
  • the image is displayed at 26% scale (390 by 390 pixels).
  • The Retailer safety zone is 140 px by 258 px.
    • Brand safety zone is 140 px by 195 px.
    • Each component placeholder is 140 px by 31 px.
• Regular Grid For tile widths between 180 and 500 pixels and heights between 300 and 500 pixels:
  • the image is displayed at approximately 33% scale (500 by 500 pixels).
  • The Retailer safety zone is 180 px by 330 px.
    • Brand safety zone is 180 px by 250 px.
    • Each component placeholder: 180 px by 40 px.
• Large Grid When the tile width is greater than 270 pixels and the height is greater than 500 pixels
  • the image is displayed at 50% scale (750 by 750 pixels).
  • The Retailer safety zone is 270 px by 495 px.
    • Brand safety zone is 270 px by 375 px.
    • Each component placeholder: 270 px by 40 px.

Flexible Scaling Rules

In specific layout scenarios, the image scales differently depending on the aspect ratio and size constraints.

Long and Narrow Tiles

The image scales to fit the tile height if all the following conditions are true:

• Tile width is between 180 and 270 pixels.
• Tile height is greater than 500 pixels.
• The height-to-width ratio is less than 2.78.

Wide or Double-Tile Grids

The image scales to fit the tile width if all the following conditions are true:

• Tile width is greater than 500 pixels.
• Tile height is greater than 500 pixels (minimum 332 pixels).
• The width-to-height ratio is less than or equal to 1.5.

Non-compliant Tile Dimension

If the grid tiles do not match any of the above scenarios, other solutions can be determined and implemented as long as the Retailer safety zone and Brand safety zone is respected within the image.

Alternative Mobile Layout

This layout variant is optimized for mobile devices and single column product grids/lists and includes a horizontal product slider beneath a branded background area.

Background Image

• The background image size is 1280 by 400 pixels.
• It is divided into two sections:
  • A branding zone at the top
  • A product zone positioned below the branding zone
• The image is fully responsive:
  • It scales proportionally based on the width of its parent container.
  • As the width decreases, the height decreases proportionally.
  • The image is never cropped.

Product Slider Behavior

• Products are displayed in a horizontally scrollable slider.
• Navigation dots appear below the slider to indicate the user’s current position:
  • One dot is shown for each product.
  • The dot representing the visible product is darker to show its active status.
  • If there is only one product, no dots are displayed.

Available Options

The available options are adding a CTA, a legal text, a "more info" text as well as color modes.

Redirection

When a user clicks on the branding zone or the CTA button, they should be redirected to the link defined within the response. There are two possible redirection options:

• Self (open in the same tab)
• Blank (open in a new tab)

Call to Action (CTA)

A CTA button can be added as an option. If enabled, it will appear at the bottom of the branding zone or above the legal text. When the user clicks on button, they will be redirected to the link.

Legal Text

Legal text can be added as an option and is always visible (90 characters maximum, including spaces).

More info

More info text can be added as an option (180 characters maximum, including spaces).

If the option is enabled:

• While hovering over the branding zone, an (i) icon is displayed in the top-left corner.
• When hovering the (i) icon, the "More info" text is displayed on top of the branding zone.
• On mobile, it is always visible or displayed when the user clicks on "See more”.

Color Mode

The advertiser can choose between two preset color modes to ensure the best contrast between text options and the branding zone. Options appear while hovering over the Branding Zone.

Light mode

• Background color: #FFFFFF 80%
• Icon color: #6A6A6A
• Legal text color: #000000

Dark mode

• Background color: 6A6A6A 80%
• Icon color: #FFFFFF
• Legal text color: #FFFFFF

Technical Details

Responsive

The rendering is based on the grid of the page and detected device.

Styling

Element styles, such as fonts, button corner radius, and navigation controls, are determined by the retailer and the following details shows our default styles. However, button and text area dimensions must be adhered to so that the Retailer Safety Zone, Brand Safety Zone and component placeholders are respected.

Call-to-Action (CTA) Button

• Max characters: 25
• Size: 150 by 30 pixels
• Font: Roboto Regular, 12 pixels
• Margin
  • Grid layout: 5 pixels below button
  • Alternative Mobile Layout: 10 pixels below button

Legal Text and More Info

Desktop

• Background: Displayed over a colored layer (the layer color adapts based on color mode)

Alternative Mobile Layout

• Legal and More info text will be displayed together
• "See less" / "See more" option for expanded or contracted view of text
• Padding: 8 pixels, all sides
• Font: same as Grid layout
• Max characters: same as Grid layout
• Background: Displayed over a colored layer (the layer color adapts based on color mode)

Layout and Borders

• Grid layout (desktop and mobile): 1px border surrounds both the branding and product zones.
• Alternative Mobile Layout: 2px border surrounds the full creative, including product listings.
  • Padding: 10 pixels of spacing around each product listing.

Background Image

• Grid layout (desktop and mobile):
  • The background image is centered and is cropped from all sides
  • Image size rendering is determined by grid-based scaling presets
• Alternative Mobile Layout:
  • The background image has a fixed position and is never cropped
  • It scales proportionally to fit its container.

Navigation and Slider Behavior

• The design of navigation dots or arrows are customizable to match the retailer’s native UI
• When the user releases the slide, the product with the largest percentage of visibility becomes the main displayed product

Product Zone Behavior

• Product information dynamically fits within the product zone
• For Grid layouts (desktop and mobile), the tile height is determined by tallest product in the row.
• For the Alternative Mobile Layout, the product zone maintains a consistent height, regardless of the width of the branded header

Alternative Mobile Layout Product Visibility Logic

• If only one product is present:

  • The product is 100% in view

• If the viewed product is first or last in the list:

  • The main product is 80% in view
  • The adjacent (secondary) product is 20% in view

• If the viewed product is in the middle of the list:

  • The main product is 80% in view
  • Each adjacent product is 10% in view