Requesting a Home Page Banner 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 an ad is shown to a customer.
Home Page Banner Ads use a similar context to Product Ads, you will need your contentStandardId
and bannerSlotIds
.
Context:
Below are the values needed to generate a home page ad:
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_here
{
"pageType": "Home",
"catalogId": "$MY_CATALOG_ID",
"contentStandardId": "string",
"bannerSlotIds": ["string"],
"maxNumberOfAds": number
}
Exemplar Context
Here is an example of a context for the pageType "Home"
:
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
"pageType": "Home",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"bannerSlotIds": ["Home_Banner"],
"maxNumberOfAds": 2
}
What Happens when an Ad Is Successfully Requested
When you successfully request an ad, you receive the following object:
HTTP/2 200
{
"ads": [],
"banners": [
{
"id": "banner_syCZH8KEezQH4zAwlPrfLoUTYd0yODk5MDQ5UA==",
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"slotId": "Home_Banner",
"imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
"linkUrl": "https://www.retailer.com/linkforwardedurl",
"altText": "Home banner for brandx laptop",
"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 necessary filters.
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 and Order reporting.
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
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
"pageType": "Home",
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"contentStandardId": "21r372ba-dce6-46f2-bd16-1b923b9189f9",
"bannerSlotIds": ["Home_Banner", "Tile_Banner"],
"maxNumberOfAds": 3
}
What Happens when an Ad Is Successfully Requested
When you successfully request an ad, you receive the following object:
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": "Home_Banner",
"imageUrl": "https://assets.flavedo.io/s/BuzjrZS0fdyWw-NOyTh9Z6wxsvrdbtmXzwrDCvmSr4o=",
"linkUrl": "https://www.retailer.com/linkforwardedurl",
"altText": "Home banner for brandx Laptop",
"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": "Tile banner for brandy Laptop",
"text": "",
"gtins": [
"catpref--2790492P",
"catpref--6902690P",
"catpref--8891466P"
],
"expiry": "2019-12-10T01:46:07.518340479Z",
"tags": {}
}
],
"products": []
}
Last updated