Skip to content

API Integration for Content Banners

This section outlines how to integrate Content Banners using the Hello Retail API. These banners are injected alongside product results and identified using specific flags and fields in the API responses.

For more information on the correct implementation for our managed solutions have a look here.

Request Format

When requesting product data, the request typically resembles the following:

{
  "query": "*",
  "key": "b8e5d3ea-f70d-47e1-9029-ab504596b352",
  "format": "json",
  "deviceType": "DESKTOP",
  "products": {
    "count": 10
  }
}

Response Structure

You can see an updated response that includes the banners being returned. Here, it is important that this can be injected alongside the products. You can see the response having a property called "isBanner," which is used to determine if the sent item is a product or indeed a banner. Alongside that, we send further relevant data for this to be tracked like a normal retail media product.  Furthermore, we send certain data that is relevant to the individual images that your search needs to accept. For each of the sizes that are set, we sent their information with the request the and for the specific size that you will be able to set up in the HelloRetail platform, so they should be as descriptive as possible. You then need to make sure to adjust your shop's template to be able to accept the banners successfully within your template. 

{
"query": "*",
"products":{
"start": 0,
"requestedCount": 10,
"returnedCount": 10,
"totalCount": 12,
"results": [
      {
        "isBanner": true,
        "retailMediaCampaignId": "68148f8003b5bc24b142b718",
        "description": "aa",
        "id": "68148f8003b5bc24b142b719",
        "title": "Forsiden - Det er fedt",
        "trackingCode": "ps-...|b-...|...",
        "url": "https://woocommerce.test/#...",
        "bannerImages": {
          "wide": {
            "altText": "_9780060289003.jpg",
            "width": 300,
            "height": 200,
            "url": "https://banners-test.helloretailcdn.com/.../300x200.jpeg"
          },
          "tall": {
            "altText": "_9780060289003.jpg",
            "width": 200,
            "height": 300,
            "url": "https://banners-test.helloretailcdn.com/.../200x300.jpeg"
          }
        }
      }
    ]
  }
}

This response structure enables banners to be rendered dynamically alongside standard product listings by detecting the isBanner property and utilizing the provided image sizes and URLs.