> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Sponsored Banners
> Learn how to use the auctions API to create auctions for listings and banners.
Banner Ad Integration: 3 stages
1. **Banner Configurations**: Create and share ad slots.
2. **Auctions for Banners**: Work with auction variables, requests and responses
3. **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](http://example.com/home) | 100 | 50 | 40 | 40 |
| right-slot-2 | Homepage Christmas | [http://example.com/home](http://example.com/home) | 50 | 200 | | |
Use [this sample
file](https://docs.google.com/spreadsheets/d/1KMnGnYp6D3u4kwwofm3nZ97Jgwtvys5fqEfGRmO3aVQ/edit#gid=0)
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**
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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture), which will let you provide multiple sources to the client browser. For example, if the asset has 2 sources:
```json theme={null}
"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:
```html theme={null}
```
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](https://github.com/Alamofire/AlamofireImage)** to handle download and render options. You may get your client's device scaling factor by calling and pick the right size.
```swift theme={null}
[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:
```java theme={null}
// Get the screen's density scale
final float scale = getResources().getDisplayMetrics().density;
```
