Sponsored Banners on category pages
Working with product categories in the Topsort ecosystem
Banner Ads on Category Pages
To display banner ads on category pages, the process is similar to that of search result pages. Instead of using the searchQuery
field, you should use the category
field in your auction request.
There are three options for specifying the category of brands, products, or vendors participating in the auction:
- Single Category
- Multiple Categories
- Category Disjunctions
Request Example - Single Category Banner
Receive up to 5 auction results in 1 API call
{
"auctions": [
{
"type": "banners",
"slots": 1,
"slotId": "homepage",
"device": "mobile",
"category": {
"id": "c_yogurt"
}
}
]
}
Response Example - Category
{
"results": [
{
"winners": [
{
"rank": 1,
"winnerType": "product",
"winnerId": "p_PJbnN",
"resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwiYmFubmVyQWRzIiwiZGVmYXVsdCIsIiJd",
"asset": [
{
"url": "https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-1x.png"
}
]
}
],
"error": false
}
]
}
Example: Category Disjunctions
Category disjunctions allow you to target multiple categories in a single auction request. You can specify multiple categories and the auction will consider ads from any of those categories. This is useful when you want to display banner ads that are relevant to various categories on a specific page.
Here’s an auction request with a single banner slot targeting both hiking boots and running shoes categories using category disjunctions:
{
"auctions": [
{
"type": "banners",
"slots": 1,
"slotId": "categories-ribbon",
"category": {
"disjunction": [
{
"id": "hiking_boots"
},
{
"id": "running_shoes"
}
]
}
}
]
}
The sample response below includes all the necessary information to serve the banner ads:
{
"results": [
{
"winners": [
{
"rank": 1,
"winnerType": "vendor",
"winnerId": "p_PJbnN",
"resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwiYmFubmVyQWRzIiwiZGVmYXVsdCIsIiJd",
"asset": [
{
"url": "https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-1x.png"
}
]
}
],
"error": false
}
]
}
You can request up to 5 auctions in a single request. If you have multiple banner slots on your category pages, you can request auctions for them in one call.