Sponsored Banners
Learn how to use the auctions API to create auctions for listings and banners.
Banner Ad Integration: 3 stages
- Banner Configurations: Create and share ad slots.
- Auctions for Banners: Work with auction variables, requests and responses
- Rendering Banners: render and display the winning banner assets
Banner ads can be used as homepage sliders, featured brands, and carousels.
Banner Configurations
Provide a list of pages with unique identifiers for each banner slot.
Landing Pages: Homepage or Custom Pages
Create slots for high-traffic homepages or other landing pages.
A slot includes:
- SlotID: A unique identifier that can contain alphanumeric characters and the following symbols:
!"#$%&'()*+,-._/:;<>?@[]^{}~=
- Name: A descriptive name (e.g. Homepage Slide 1, Above Trending Products ).
- URL or Deeplink: The URL where the slot is located.
- Landing Page name: The slot’s corresponding landing page.
- Image Width and Height, if you require different sizes across devices we support 1 more set of image sizes
SlotID | Landing Page Name | URL or Deeplinks | Width | Height | Additional Width (optional) | Additional Height (optional) |
---|---|---|---|---|---|---|
top-slot-1 | Homepage Christmas | http://example.com/home | 100 | 50 | 40 | 40 |
right-slot-2 | Homepage Christmas | http://example.com/home | 50 | 200 |
Use this sample file to bulk upload banner configurations.
Category and Search
Allow vendors to target specific categories and keywords. Define banner slots and share them.
Example:
SlotID | Width | Height | Alternative Width (optional) | Alternative Height (optional) |
---|---|---|---|---|
category-bottom | 100 | 50 | 40 | 40 |
/Auction Requests for Banners
:::note Storing the resolvedBidId.
The resolvedbidId simplifies event attribution and recording for you and your vendors, similar to auctionID in sponsored listings. It needs to be stored so events can be reported later, either as a cookie or session variable for web applications, or stored as an internal variable for mobile apps. :::
Requests Fields
Variable | Type | Definition | Required/optional | Notes |
---|---|---|---|---|
type | string | Type of auction | required | Must be set as “banners” |
slots | integer | Maximum number of auction winners | required | number of winners you would like the auction to return |
slotId | string | External slot ID provided by the marketplace. | required | Format: ^[\w!\"#$%&'()_+,\-._/:;<>?@\[\]^\{\}~=\\]\_$ |
categoryId | string | Marketplace’s category ID for the auction. | required only if category banners | Defaults to homepage auction if no category ID provided. |
searchQuery | string | required only if search banners *you can pass both categoryID and searchQuery in the same call | Example “blue running shoes” | |
device | string | Target device: desktop or mobile. | optional | Enum: “desktop” or “mobile.” Defaults to “desktop.” |
Response Fields
Variable | Type | Definition |
---|---|---|
resultType | string | “banners” |
winners.resolvedBidId | string | A Topsort ID to be used when this item is interacted with (for reporting impressions or clicks) |
winners.type | string | Type of the winning bid. Enum: “product”, “vendor”, “brand”, “url”. |
winners.rank | integer | The product’s auction rank indicates its position, with 1 being the winner. In the auction response, the winners array is sorted, and the rank corresponds to the entry’s index. |
winners.id | string | The marketplace’s unique ID for the winning entity. |
winners.asset | array | |
winners.asset.url | string | URL source for a banner asset. The asset is served by Topsort’s CDN, contained in asset array |
Rendering Banners
Set the banner configurations inside the Topsort admin dashboard. Insert the banner in your web app’s DOM or add a component to your mobile app code.
Web Apps
For web apps, use the picture
element, which will let you provide multiple sources to the client browser. For example, if the asset has 2 sources:
"asset": [
{
"url": "https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-1x.png",
"mimeType": "image/png",
"dimensions": {
"width": 400,
"height": 100,
}
},
{
"url": "https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-2x.png",
"mimeType": "image/png",
"dimensions": {
"width": 800,
"height": 200,
}
}
]
Then you may generate the following HTML:
<picture>
<source
width="400"
srcset="https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-1x.png 400w, https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-2x.png 800w"
>
<img src="https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-1x.png" alt="banner">
</picture>
The client’s browser will then choose the most adequate size depending on the user’s device capabilities and only fetch the size that best fits the user’s device.
Native iOS (Swift)
We recommend using AlamofireImage to handle download and render options. You may get your client’s device scaling factor by calling and pick the right size.
[UIScreen mainScreen].scale;
In Android (Java)
Use Glide library to render and cache images. As with iOS, you will need to check the device’s scaling factor to determine which image to download:
// Get the screen's density scale
final float scale = getResources().getDisplayMetrics().density;