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