Requesting a Search Term Banner Ad

Search term 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.

Search term Banner Ads use a similar context to Product Ads, you will need your contentStandardId and bannerSlotIds.

The placement attribute for Search term Banner ads has the value "banner-categorysearch".

The Search term Banner Ads use the "Agora Category&Search" content standard.

You will receive your contentStandardId and bannerSlotIdsfrom Project Agora Commerce once your content standard is generated.

The bannerSlotIdsprovided in the examples below are not the ones that will be used.

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

HTTP

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_here
{
    "catalogId": "$MY_CATALOG_ID",
    "searchTerm": "string",
    "placement": "string",
    "contentStandardId": "string",
    "bannerSlotIds": ["string"],
    "maxNumberOfAds": number,
    "sessionId": "string"
}

cURL

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

Exemplar Context

Here is an example of a context:

HTTP

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Chocolate",
    "placement": "banner-categorysearch",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": ["Search_Banner"],
    "maxNumberOfAds": 2,
    "sessionId": "23dn3923-323d"
}

cURL

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Chocolate",
    "placement": "banner-categorysearch",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": ["Search_Banner"],
    "maxNumberOfAds": 2,
    "sessionId": "23dn3923-323d"
}'

What Happens when an Ad Is Successfully Requested

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

HTTP

HTTP/2 200
{
    "ads": [],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Search_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Search banner for brandx chocolate",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

cURL

{
    "ads": [],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "dc5aff9a-e0b1-4bf8-999f-393329b4afae",
            "slotId": "Search_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "retailer.com/linkforwardedurl",
            "altText": "Search banner for brandx chocolate",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

No customer information or cart items are necessary in this simple context. The simple context consists only of search terms and necessary filters.

In order to properly integrate the Search term Banner ad request the searchTerm value shall contain a variable which is used in the search bar of the website's search page and is filled by user input.

This ensures that the ad request is being executed in every case with the value that users enters in the search bar, so that relative ads will show up.

In order to serve a Banner Ad on your website you will have to use as a creative image the imageUrl , and as a landing page the linkUrl as taken from the above ad response. The id also from this response shall be saved for later use for Impression/Click reporting.

The products field is legacy and can be ignored

The text and gtins fields can be ignored in a standard integration

In gtin field of the above responses you will get the pa_id as in the product feed for the product to be displayed.

Reminder: the pa_id is the concatenation of the catalog prefix and each product SKU, so to identify which SKU to display on your side you may need to remove the catalog prefix and the symbols "--"

pa_id= catprefix--SK

Filtered Searches & Multiple Banners

When a user filters their browsing deeper, you are able to serve ads relevant to their filters using productFilters in the context.

In this example, the user has navigated to the Red Wine category within their search, and filtered their browsing to "Shiraz" Red Wines. This is a new request and considered by Project Agora Commerce as a new page, and new set of ads. Even in the rare event the ads served are identical to the unfiltered results. The example below also requests 2 banner slot ids

It is necessary for the 2 bannerSlotIds to be created under the same content Standard in order to be used in the same ad request. bannerSlotIds created under different content Standards can't be used in the same request.

HTTP

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
      ["taxonomy:RedWine>Shiraz"]
    ],
    "placement": "banner-categorysearch",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": ["Search_Banner", "Tile_Banner"],
    "maxNumberOfAds": 2,
    "sessionId": "23dn3923-323d"
}

cURL

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
      ["taxonomy:RedWine>Shiraz"]
    ],
    "placement": "banner-categorysearch",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": ["Search_Banner", "Tile_Banner"],
    "maxNumberOfAds": 2,
    "sessionId": "23dn3923-323d"
}'

As your customers filter deeper in their searches, your request will include more product filters

HTTP

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
       ["taxonomy:RedWine>Shiraz", "Type:Australia", "delivery:DeliveryOnly", "pricerange:$25-$50"]
    ],
    "placement": "banner-categorysearch",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": ["Search_Banner", "Tile_Banner"],
    "maxNumberOfAds": 2,
    "sessionId": "23dn3923-323d"
}

cURL

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
       ["taxonomy:RedWine>Shiraz", "Type:Australia", "delivery:DeliveryOnly", "pricerange:$25-$50"]
    ],
    "placement": "banner-categorysearch",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": ["Search_Banner", "Tile_Banner"],
    "maxNumberOfAds": 2,
    "sessionId": "23dn3923-323d"
}'

What Happens when an Ad Is Successfully Requested

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

HTTP

HTTP/2 200
{
    "ads": [],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Search_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Search banner for brandx red wine",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        },
        {
            "id": "banner_t3UBEfcaPYCI1bbUtgH-iqddWfwyODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Tile_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxcZjtL1mXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Search tile banner for brandy red wine",
            "text": "",
            "gtins": [
                "catpref--2790492P",
                "catpref--6902690P",
                "catpref--8891466P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

cURL

{
    "ads": [],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Search_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Search banner for brandx red wine",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        },
        {
            "id": "banner_t3UBEfcaPYCI1bbUtgH-iqddWfwyODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Tile_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxcZjtL1mXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Search tile banner for brandy red wine",
            "text": "",
            "gtins": [
                "catpref--2790492P",
                "catpref--6902690P",
                "catpref--8891466P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

Requesting Product Ads

To request Product Ads and Banner Ads in the same request, use the maxNumberOfAds field to specify the number of Product Ads requested.

Below is an example requesting 3 Product Ads and 2 Banner Ads

HTTP

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
       ["taxonomy:RedWine>Shiraz", "Type:Australia", "delivery:DeliveryOnly", "pricerange:$25-$50"]
    ],
    "placement": "banner-categorysearch",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": ["Search_Banner", "Tile_Banner"],
    "maxNumberOfAds": 3,
    "sessionId": "23dn3923-323d"
}

cURL

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
       ["taxonomy:RedWine>Shiraz", "Type:Australia", "delivery:DeliveryOnly", "pricerange:$25-$50"]
    ],
    "placement": "banner-categorysearch",
    "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
    "bannerSlotIds": ["Search_Banner", "Tile_Banner"],
    "maxNumberOfAds": 3,
    "sessionId": "23dn3923-323d"
}'

What Happens when an Ad Is Successfully Requested

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

HTTP

HTTP/2 200
{
    "ads": [
        {
            "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
            "gtin": "catpref--2899049P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516943179Z"
        },
        {
            "id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==",
            "gtin": "catpref--9891566P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516948637Z"
        },
        {
            "id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==",
            "gtin": "catpref--2902620P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
          
    ],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Search_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Search banner for brandx red wine",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        },
        {
            "id": "banner_t3UBEfcaPYCI1bbUtgH-iqddWfwyODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Tile_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxcZjtL1mXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Search banner for brandy red wine",
            "text": "",
            "gtins": [
                "catpref--2790492P",
                "catpref--6902690P",
                "catpref--8891466P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

cURL

{
    "ads": [
        {
            "id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
            "gtin": "catpref--2899049P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516943179Z"
        },
        {
            "id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==",
            "gtin": "catpref--9891566P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:46:07.516948637Z"
        },
        {
            "id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==",
            "gtin": "catpref--2902620P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
          
    ],
    "banners": [
        {
            "id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Search_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Search banner for brandx red wine",
            "text": "",
            "gtins": [
                "catpref--2899049P",
                "catpref--9891566P",
                "catpref--2902620P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        },
        {
            "id": "banner_t3UBEfcaPYCI1bbUtgH-iqddWfwyODk5MDQ5UA==",
            "contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
            "slotId": "Tile_Banner",
            "imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxcZjtL1mXzwrDCvmSr4o=",
            "linkUrl": "https://www.retailer.com/linkforwardedurl",
            "altText": "Search banner for brandy red wine",
            "text": "",
            "gtins": [
                "catpref--2790492P",
                "catpref--6902690P",
                "catpref--8891466P"
            ],
            "expiry": "2019-12-10T01:46:07.518340479Z",
            "tags": {}
        }
    ],
    "products": []
}

sessionId is needed to be included in the ad request as it will be used later in order reporting. For more information please check the "Syncing Order Data" page

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