> ## 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 | | |

<Note>
  Use [this sample
  file](https://docs.google.com/spreadsheets/d/1KMnGnYp6D3u4kwwofm3nZ97Jgwtvys5fqEfGRmO3aVQ/edit#gid=0)
  to bulk upload banner configurations.
</Note>

## **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.
</Note>

### 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 |
| `winners.asset.content` | object | Optional metadata associated with the banner creative. |
| `winners.asset.content.altText` | string | Optional advertiser-provided alternative text for the banner creative. |
| `winners.asset.content.aiGenerated` | string | Present as `"true"` when the advertiser declared that the image was generated or modified with AI. |

# **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:

When `asset[].content.altText` is returned, use the value for the image's HTML `alt` attribute so screen readers can communicate the advertiser-provided description. Treat alt text as untrusted advertiser-authored text and assign or escape it safely when rendering HTML.

```html theme={null}
<picture>
  <source
    width="400"
  />
  <img
    src="https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-1x.png"
    alt="A red bottle of soda on a picnic table"
  />
</picture>
```

If `asset[].content.aiGenerated` is `"true"`, the advertiser has declared that the image was generated or modified with AI. Marketplaces can use this metadata when implementing their own AI-content disclosure requirements.

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;
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.