Banner X Ad Integration Guide

Overview

The Banner X Ad Integration Guide explains what a retailer must provide in order to serve Banner X Ads. Project Agora Commerce generates Banner X Ads in a similar way that Project Agora Commerce serves Banner Ads. Retailers have control of generated banners.

Integration Process

The following steps on Project Agora Commerce side will be completed within the Project Agora Commerce staging environment. Once everything is working correctly, you will then be ready for production. The integration process for Banner X Ads is typically straightforward:

1. Provide necessary data to Project Agora Commerce to generate your content standard

2. Your content standard will be sent for approval

3. Once approved, your content standard will be loaded into your namespace and your content standard ID will be generated

4. Your Banner X endpoint will be generated

5. Your Banner X creator will be generated

6. You are ready to request Banner X Ads

Are You Ready to Request BannerX Ads?

This guide assumes you have already created your catalog, created your products, and are sending customer and order data to Project Agora Commerce.

Syncing Catalog & Products

In order to request Banner X Ads, you must provide a context. See "The Banner X Ad Context" for more information.

What's the difference between Banner Ads and Banner X Ads?

Banner X ads are responsive banner ads. These are multi-component banners that are served to a retailer's front end. Project Agora Commerce sends each individual component of the banner and the styling of these banners is handled by the retailer's front end. As Banner X banners are multi component, the context and requests are slightly different to normal banners.

There is one noticeable difference in the Banner X context. Where bannerSlotIds is used in banner ads, slotIds is used in Banner X ads. Additionally, you are able to call multiple of the same banner slots with the maxNumberOfAds option.

This can be seen in the example below:

HTTP

   "slotIds": [
      {
        "slotId": "Category_1_Banner",
        "maxNumberOfAds": 1
      },
    ],

The returned object

As Project Agora Commerce is serving multiple components to a retailer instead of one, the returned object is different. Banner X integrations differ greatly depending on each integration. Below is an example of the banners section of the returned object for a single Banner X. This would be a simple Banner X Ad:

 "banners": [
        {
            "citrusAdId": "shotgun_8d6bd7aa780d2278cf743d95cbdcfb7d262c5ba0575446cba91b628720975ob",
            "citrusCampaignName": "milo-campaign-lakjsdf09kj",
            "citrusContentStandardId": "fd0f8b2d-a4c8-4599-b4e5-fbcfd4eb14b7",
            "citrusSlotId": "Category_1_Banner",
            "citrusExpiry": "2002-10-02T15:00:00.05Z",         
            "ctaFlag": true,
            "ctaLink": "retailer.com/a/a-national/everything/search/heritage%20mill?pageNumber=1",
            "ctaText": "Shop Now",
            "bannerText": "<strong>Try Milo Cereal",
            "headingText": "BannerMilo Milo shop now button",
            "heroImageUrl": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574",
            "heroImageAltText": "Milo product image",
            "backgroundImageUrl": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59rxf543",
            "backgroundImagePosition": "FILL",
            "secondaryHeroMode": "BLOCK",
            "backgroundColour": "#849fr2",
            "bannerTextColour": "#000000",
            "ctaTextAccessibility": "Link to all Milo products on Coles online.",
            "secondaryHeroImageUrl": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
            "secondaryHeroImageAltText": "Milo Logo",
            "secondaryBackgroundImageUrl": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-ewqdz-xwzxe154r",
            "secondaryBackgroundImagePosition": "LEFTALIGNED"
        }
      ]

Banner X integrations differ greatly as they are largely custom to each retailer's needs. Your returned object may not appear similar to those displayed on this page.

The Banner X Ad Context

In order to request Banner X Ads, you must provide a context. See "The Banner X Ad Context"