Requesting a Home Page Banner X Ad

Home page banner ads require a simple "context' to be sent to Project Agora Commerce. A "context" is a bit of code that defines the conditions under which a product is shown to a customer.

Banner X Ads use the /bannerx endpoint

Project Agora Commerce may need to enable home page ads before ads can be served.

You will receive your contentStandardId from CitrusAd once your content standard is generated.

Minimum Viable Context:

Below are the minimum values needed to generate a search term ad:

HTTP

POST $BASE_URL/v1/ads/bannerx HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_here
{
    "catalogId": "string",
    "pageType": "string",
    "contentStandardId": "string",
    "bannerSlotIds": [
          {
            "slotId": "string",
      "maxNumberOfAds": number
     }
   ]
}

cURL

curl -iX POST "$BASE_URL/v1/ads/bannerx" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_here" \
-d \
'{
    "catalogId": "string",
    "pageType": "string",
    "contentStandardId": "string",
    "bannerSlotIds": [
          {
            "slotId": "string",
      "maxNumberOfAds": number
     }
   ]
}'

Exemplar Context

Here is an example of a context for the pageType "Home":

HTTP

POST $BASE_URL/v1/ads/bannerx HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "pageType": "Home",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": [
          {
            "slotId": "Homepage_Banner",
      "maxNumberOfAds": 1
     }
   ]
}

cURL

curl -iX POST "$BASE_URL/v1/ads/bannerx" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "pageType": "Home",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": [
          {
            "slotId": "Homepage_Banner",
      "maxNumberOfAds": 1
     }
   ]
}'

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

HTTP

HTTP/2 200
{
    "ads": [
        {
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Homepage_Banner",
            "banners": [
                {
                    "citrusAdId": "shotgun_kZp9yTCMm71vTo7iyQaK9I_YB09FUFYzNzBTQ0FO",
                    "citrusCampaignName": "milo-campaign-lakjsdf09kj",
                    "citrusContentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
                    "citrusSlotId": "Homepage_Banner",
                    "citrusExpiry": "2019-12-10T06:13:25.380294198Z",
                    "headingText": "BannerMilo Milo shop now button",
                    "bannerText": "<strong>Try Milo Cereal</strong>",
                    "bannerTextColour": "48a94c",
                    "heroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574",
                    "heroImageAltText": "Milo product image",
                    "ctaFlag": true,
                    "ctaText": "Shop now",
                    "ctaTextAccessibility": "for Milo products",
                    "ctaLink": "retailer.com/everything/search/heritage%20mill?pageNumber=1",
                    "secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
                    "secondaryHeroImageAltText": "Milo Logo",
                    "secondaryHeroMode": "landscape",
                    "backgroundColour": "895b5b",
                    "backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "backgroundImagePosition": "FILL",
                    "secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "secondaryBackgroundImagePosition": "LEFTALIGNED",
                    "tags": {}
                }
            ]
        }
    ]
}

cURL

{
    "ads": [
        {
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Homepage_Banner",
            "banners": [
                {
                    "citrusAdId": "shotgun_kZp9yTCMm71vTo7iyQaK9I_YB09FUFYzNzBTQ0FO",
                    "citrusCampaignName": "milo-campaign-lakjsdf09kj",
                    "citrusContentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
                    "citrusSlotId": "Homepage_Banner",
                    "citrusExpiry": "2019-12-10T06:13:25.380294198Z",
                    "headingText": "BannerMilo Milo shop now button",
                    "bannerText": "<strong>Try Milo Cereal</strong>",
                    "bannerTextColour": "48a94c",
                    "heroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574",
                    "heroImageAltText": "Milo product image",
                    "ctaFlag": true,
                    "ctaText": "Shop now",
                    "ctaTextAccessibility": "for Milo products",
                    "ctaLink": "retailer.com/everything/search/heritage%20mill?pageNumber=1",
                    "secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
                    "secondaryHeroImageAltText": "Milo Logo",
                    "secondaryHeroMode": "landscape",
                    "backgroundColour": "895b5b",
                    "backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "backgroundImagePosition": "FILL",
                    "secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "secondaryBackgroundImagePosition": "LEFTALIGNED",
                    "tags": {}
                }
            ]
        }
    ]
}

You may receive less fields within a banner object, this will occur when a banner is configured without all possible fields.

Requesting Multiple Banners

The example below requests 2 banner slot ids in the same home page request:

HTTP

POST $BASE_URL/v1/ads/bannerx HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "pageType": "Home",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": [
          {
            "slotId": "Homepage_Banner",
      "maxNumberOfAds": 1
     },
               {
            "slotId": "Homepage_Single_Tile",
      "maxNumberOfAds": 1
     }
   ]
}

cURL

curl -iX POST "$BASE_URL/v1/ads/bannerx" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "pageType": "Home",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": [
          {
            "slotId": "Homepage_Banner",
      "maxNumberOfAds": 1
     },
               {
            "slotId": "Homepage_Single_Tile",
      "maxNumberOfAds": 1
     }
   ]
}'

What Happens When an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

HTTP

HTTP/2 200
{
    "ads": [
        {
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Homepage_Banner",
            "banners": [
                {
                    "citrusAdId": "shotgun_kZp9yTCMm71vTo7iyQaK9I_YB09FUFYzNzBTQ0FO",
                    "citrusCampaignName": "milo-campaign-lakjsdf09kj",
                    "citrusContentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
                    "citrusSlotId": "Homepage_Banner",
                    "citrusExpiry": "2019-12-10T06:13:25.380294198Z",
                    "headingText": "BannerMilo Milo shop now button",
                    "bannerText": "<strong>Try Milo Cereal</strong>",
                    "bannerTextColour": "48a94c",
                    "heroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574",
                    "heroImageAltText": "Milo product image",
                    "ctaFlag": true,
                    "ctaText": "Shop now",
                    "ctaTextAccessibility": "for Milo products",
                    "ctaLink": "retailer.com/everything/search/heritage%20mill?pageNumber=1",
                    "secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
                    "secondaryHeroImageAltText": "Milo Logo",
                    "secondaryHeroMode": "landscape",
                    "backgroundColour": "895b5b",
                    "backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "backgroundImagePosition": "FILL",
                    "secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "secondaryBackgroundImagePosition": "LEFTALIGNED",
                    "tags": {}
                }
            ]
        },
         {
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Homepage_Single_Tile",
            "banners": [
                {
                    "citrusAdId": "shotgun_8d6bd7aa780d2278cf743d95cbdcfb7d262c5ba0575446cba91b628720975bx",
                    "citrusCampaignName": "brandb-campaign-lakjsdf09kj",
                    "citrusContentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
                    "citrusSlotId": "Homepage_Single_Tile",
                    "citrusExpiry": "2019-12-10T06:13:25.380294198Z",
                    "headingText": "BannerBrandA BrandAChocolateBlocks shop now button",
                    "bannerText": "<strong>You'll love BrandA's NEW Chocolate Blocks</strong>",
                    "bannerTextColour": "48a94c",
                    "heroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574",
                    "heroImageAltText": "BrandA product image",
                    "ctaFlag": true,
                    "ctaText": "Shop now",
                    "ctaTextAccessibility": "for BrandA products",
                    "ctaLink": "retailer.com/everything/search/brand%20%a?pageNumber=1",
                    "secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
                    "secondaryHeroImageAltText": "BrandA Logo",
                    "secondaryHeroMode": "landscape",
                    "backgroundColour": "895b5b",
                    "backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "backgroundImagePosition": "FILL",
                    "secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "secondaryBackgroundImagePosition": "LEFTALIGNED",
                    "tags": {}
                }
            ]
        }
    ]
}

cURL

{
    "ads": [
        {
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Search_Banner",
            "banners": [
                {
                    "citrusAdId": "shotgun_kZp9yTCMm71vTo7iyQaK9I_YB09FUFYzNzBTQ0FO",
                    "citrusCampaignName": "milo-campaign-lakjsdf09kj",
                    "citrusContentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
                    "citrusSlotId": "Search_Banner",
                    "citrusExpiry": "2019-12-10T06:13:25.380294198Z",
                    "headingText": "BannerMilo Milo shop now button",
                    "bannerText": "<strong>Try Milo Cereal</strong>",
                    "bannerTextColour": "48a94c",
                    "heroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574",
                    "heroImageAltText": "Milo product image",
                    "ctaFlag": true,
                    "ctaText": "Shop now",
                    "ctaTextAccessibility": "for Milo products",
                    "ctaLink": "retailer.com/everything/search/heritage%20mill?pageNumber=1",
                    "secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
                    "secondaryHeroImageAltText": "Milo Logo",
                    "secondaryHeroMode": "landscape",
                    "backgroundColour": "895b5b",
                    "backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "backgroundImagePosition": "FILL",
                    "secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "secondaryBackgroundImagePosition": "LEFTALIGNED",
                    "tags": {}
                }
            ]
        },
         {
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Search_Single_Tile",
            "banners": [
                {
                    "citrusAdId": "shotgun_8d6bd7aa780d2278cf743d95cbdcfb7d262c5ba0575446cba91b628720975bx",
                    "citrusCampaignName": "brandb-campaign-lakjsdf09kj",
                    "citrusContentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
                    "citrusSlotId": "Search_Single_Tile",
                    "citrusExpiry": "2019-12-10T06:13:25.380294198Z",
                    "headingText": "BannerBrandA BrandAChocolateBlocks shop now button",
                    "bannerText": "<strong>You'll love BrandA's NEW Chocolate Blocks</strong>",
                    "bannerTextColour": "48a94c",
                    "heroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8851d59f0574",
                    "heroImageAltText": "BrandA product image",
                    "ctaFlag": true,
                    "ctaText": "Shop now",
                    "ctaTextAccessibility": "for BrandA products",
                    "ctaLink": "retailer.com/everything/search/brand%20%a?pageNumber=1",
                    "secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
                    "secondaryHeroImageAltText": "BrandA Logo",
                    "secondaryHeroMode": "landscape",
                    "backgroundColour": "895b5b",
                    "backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "backgroundImagePosition": "FILL",
                    "secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
                    "secondaryBackgroundImagePosition": "LEFTALIGNED",
                    "tags": {}
                }
            ]
        }
    ]
}

If you are unsure of the strings displayed on this page. Take a look at the Reference page.