The below outlines the properties possible in a standard request as outlined in Requesting ads for your request, and the response if you receive an ad.
Banner ads are requested on the same
/generateendpoint as product ads. A single request can be used to retrieve both ad types.
Requested items
| String | Description | Required/optional |
|---|---|---|
bannerSlots | An array of banner slots that you wish to receive banner ads for. By specifying a maxNumberOfAds for the banner slots, you can retrieve more than one banner for the slot. Such a use case would be for carousel placements. | Required |
bannerSlotIds | An array of banner slots that you wish to receive banner ads for | Required, superseded by bannerSlots |
catalogId | Your product catalog identifier for your website. | Required |
contentStandardId | The content standard identifier for your website. | Required |
customerId | The unique identifier for the customer being served ads. | Optional |
filterMode | Optional way of defining the structure of your request. See Ad generation filtering for more information. | Optional, preferred |
maxNumberOfAds | The maximum number of product ads you would like returned up to 15. | Required, enables product ads to be served in the same request. If no product ads are wanted, set to 0 |
options | Optional way of defining the structure of your request. See Ad generation filtering for more information. | Optional, preferred |
placement | The unique placement you are requesting ads for. | Required |
productFilters | Any product filters relevant to your request. Such as a category, location, or size. | Required |
sessionId | The unique identifier of the customer's session. Used for attribution in standard integrations. Review Integration workflow options for more information. | Required in standard integrations |
Returned items
| String | Description | Example value |
|---|---|---|
altText | Alternative text for the hero image in the rare event it doesn't display. | Advertisement for <BRAND>. Art of the Burger. Create your delicious masterpiece. Shop Now. |
contentStandardId | The content standard identifier for your website. | `4ffb80ba-b9a9-4567-8069-79b2eca93473 |
expiry | The expiry of the ad. This is the latest point in which a click can be reported to CitrusAd | 2021-06-01T23:48:16.573967987Z |
id | The unique id of the ad. This is unique to each request made to CitrusAd and cannot be cached. | banner_j2vfi9pN2BiQZk4X9sC55PgNu5k3ODIzOTlfMDAwODc2ODQwMDEwNzM= |
imageUrl | The image link of the banner. | [<https://cdn.[server].io/s/9b93e7f9-d747-4c8b-bcba-2357b280a3b3>](https://cdn.[server].io/s/9b93e7f9-d747-4c8b-bcba-2357b280a3b3`) |
gtins | An array of up to 20 product codes selected from the campaign's advertised products. | [ "7714107", "7163379", "7733636", "7733657", "7733628" ], |
linkUrl | The url forwarded from the banner when the customer clicks the banner. | <https://www.retailer.com/groceries/en-GB/search?query=double-fudge> |
slotId | The id of the specific slot for the banner you have requested. | Category_Top |
tags | This field returns any third party tags entered by the advertiser in their campaign. | { "dv": "<script src=\"<https://cdn.doubleverify.com/dvtp_src.js?ctx=111111&cmp=11111111&sid=111111&plc=111111&adsrv=111&btreg=&btadsrv=&crt=&tagtype=&dvtagver=6.1.src\>" type=\"text/javascript\"></script>" } |
text | Used in bespoke integrations as an additional text field. | |
position | The ad's position in the CitrusAd response. You should honour this position in the event fixed tenancy campaigns are utilised. | 1 |
sellerId | The unique Id of the seller. Will only populate if a sellerId is set on a team. sellerIds are typically used when onboarding marketplace sellers. | 73nns-32sxr-32ss Custom per integration |